wolfcrypt-sys 0.2.1

# wolfcrypt-sys

Raw FFI bindings to wolfCrypt, generated by bindgen. This is the foundation
crate for the wolfssl-rs workspace.

Prefer the higher-level crates ([`wolfcrypt`](../wolfcrypt),
[`wolfcrypt-ring-compat`](../wolfcrypt-ring-compat),
[`wolfcrypt-tls`](../wolfcrypt-tls)) over depending on this directly.

## Why

`wolfcrypt-sys` separates the generated FFI from the safe wrappers so that:

- The bindgen output can be regenerated (by updating the wolfSSL source)
  without a breaking-change version bump on `wolfcrypt` or `wolfcrypt-rs`.
- It emits `DEP_WOLFCRYPT_SYS_*` cargo metadata (include paths, cfg flags,
  lib dirs) via the `links = "wolfcrypt_sys"` key so downstream crates do
  not need to re-discover the wolfSSL installation.
- Per-algorithm cfg flags (`wolfssl_aes_gcm`, `wolfssl_ecc_p384`, …) are
  parsed from the compiled wolfSSL and emitted here; higher-level crates
  use these flags to gate algorithm support at compile time.

## Usage

```toml
[dependencies]
wolfcrypt-sys = { version = "0.1", features = ["vendored"] }
```

Every function in this crate is `unsafe` — there is no safe wrapping layer.
Minimal example calling the bindgen-generated `wc_Sha256Hash` one-shot
helper:

```rust
use wolfcrypt_sys::wc_Sha256Hash;

fn sha256(data: &[u8]) -> Result<[u8; 32], core::ffi::c_int> {
    let mut digest = [0u8; 32];
    // SAFETY: `data` is a readable slice of `data.len()` bytes; `digest`
    // is a writable 32-byte buffer matching SHA-256's output size. The
    // bindgen signature uses `word32` for the input length; we cast from
    // `usize` and assume the caller does not exceed `u32::MAX`.
    let rc = unsafe {
        wc_Sha256Hash(data.as_ptr(), data.len() as u32, digest.as_mut_ptr())
    };
    if rc == 0 { Ok(digest) } else { Err(rc) }
}
```

For typed wrappers around the opaque wolfCrypt structs (`Aes`, `WC_RNG`,
`wc_ed25519_key`, …), use [`wolfcrypt-rs`](../wolfcrypt-rs); for safe Rust
APIs, use [`wolfcrypt`](../wolfcrypt).

## How it works

```text
wolfssl-src       Compiles wolfSSL C source; emits DEP_WOLFSSL_SRC_* metadata
      │
wolfcrypt-sys     build.rs reads wolfSSL metadata; runs bindgen over wolfssl/
      │           headers; emits DEP_WOLFCRYPT_SYS_{CFGS,INCLUDE,ROOT,…}
      │           (links = "wolfcrypt_sys")
      │
wolfcrypt-rs      Reads DEP_WOLFCRYPT_SYS_* to compile compat_shim.c
```

The generated `bindings.rs` is written to `$OUT_DIR` and `include!`-d into
`lib.rs`. The allowlist covers wolfCrypt algorithm structs and functions;
wolfSSL TLS types are excluded.

The build script searches for wolfSSL in this order:

1. `WOLFSSL_LIB_DIR` + `WOLFSSL_INCLUDE_DIR` environment variables
2. `WOLFSSL_DIR` install prefix
3. `vendored` feature + `WOLFSSL_SRC` — compiles from source via
   [`wolfssl-src`](../wolfssl-src)
4. `pkg-config`

| Feature | Description |
|---------|-------------|
| `vendored` | Compile wolfSSL from source via `wolfssl-src` (requires `WOLFSSL_SRC` or the bundled submodule) |
| `fips` | Enable the FIPS 140-3 code path (commercial license required) |
| `riscv-bare-metal` | Bare-metal RISC-V configuration (Caliptra); implies `vendored` |
| `cryptocb-only` | Build wolfSSL with only the CryptoCb callback routing layer; implies `vendored` |
| `cryptocb-pure` | Minimal CryptoCb-only build (no SSL/EVP/HKDF/ASN-template); implies `vendored` |

Need FIPS 140-3 validation in your Rust application? wolfCrypt is FIPS 140-3
validated. [Contact wolfSSL](https://www.wolfssl.com/license/) for a
commercial FIPS license and the validated source tree.

## References

- [wolfcrypt](../wolfcrypt) — safe RustCrypto trait implementations
  (preferred high-level API)
- [wolfcrypt-rs](../wolfcrypt-rs) — typed wrappers around opaque wolfCrypt
  structs
- [wolfcrypt-tls](../wolfcrypt-tls) — TLS client/server using the same
  backend
- [wolfssl-src](../wolfssl-src) — vendored wolfSSL C source build
- [wolfSSL repository](https://github.com/wolfSSL/wolfssl)
- [wolfSSL / wolfCrypt documentation](https://www.wolfssl.com/documentation/)
- [workspace README](../README.md)

## Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

## License

GPL-3.0-only OR LicenseRef-wolfSSL-commercial.

The underlying wolfSSL C library is licensed under GPL-3.0-or-later with a
commercial option available from [wolfSSL Inc.](https://www.wolfssl.com/license/)