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-ring-compat, 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

[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:

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; for safe Rust APIs, use wolfcrypt.

How it works

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
4. pkg-config

Need FIPS 140-3 validation in your Rust application? wolfCrypt is FIPS 140-3 validated. Contact wolfSSL for a commercial FIPS license and the validated source tree.

References

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

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.