wolfhsm-sys

Raw Rust FFI bindings to wolfHSM, auto-generated by bindgen at build time.

Most users should depend on the higher-level wolfhsm crate instead. Use wolfhsm-sys directly only if you need access to wolfHSM C API symbols that are not yet wrapped by wolfhsm.

What

wolfhsm-sys exposes the wolfHSM C client API directly as unsafe Rust functions and types. The bindings cover:

• Client API — the complete wh_Client_* function set: connect/disconnect, key generation and caching, ECC/RSA/AES/CMAC/HKDF operations, NVM object store, counters, certificate management, authentication, SHE key management, and custom callbacks
• Communication layer — wh_Comm_* connection and framing primitives
• POSIX transport types — PosixTransportTcp*, PosixTransportUds*, PosixTransportShm* structs and init/connect/disconnect functions
• Constants and error codes — WH_* and WOLFHSM_* result codes and configuration constants

The bindings also include a small C shim (shims.c) that stack-allocates wolfcrypt structs on the C side — necessary because wolfcrypt types are opaque in the Rust FFI and cannot be zero-initialized from Rust.

Why

wolfhsm-sys separates the generated FFI from the safe wrapper so that:

• The bindgen output can be regenerated (by bumping wolfhsm-src) without a breaking-change version bump on wolfhsm.
• Downstream crates with unusual requirements can use the raw bindings without pulling in the opinionated safe API.
• The links = "wolfhsm_sys" key prevents multiple copies of the wolfHSM static archive from being linked into the same binary.

How it works

build.rs performs five steps:

1. Read wolfSSL metadata — reads DEP_WOLFCRYPT_SYS_* from wolfcrypt-sys (wolfSSL include paths, vendored flag, lib dirs).
2. Read wolfHSM metadata — reads DEP_WOLFHSM_SRC_INCLUDE and DEP_WOLFHSM_SRC_LIB from wolfhsm-src (wolfHSM include path and compiled library location).
3. Compile shims.c — a small C translation unit that stack-allocates wolfcrypt key and context structures and exposes them via thin wrapper functions callable from Rust.
4. Emit link directives — instructs rustc to search for libwolfhsm.a in the wolfhsm-src output directory and link it, followed by the wolfSSL library.
5. Run bindgen — generates bindings.rs in OUT_DIR from wrapper.h, which includes wh_client.h and the POSIX transport headers. The allowlist captures wh_Client_* functions, wh_Comm_*, posixTransport* types and functions, and WH_* / WOLFHSM_* constants; wolfSSL internals are excluded.

How to use

[dependencies]
wolfhsm-sys = "0.1"

use wolfhsm_sys::*;

unsafe {
    // Configure a TCP transport to the wolfHSM server
    let mut tcp_ctx: PosixTransportTcpClientContext = core::mem::zeroed();
    // ... set ip/port fields, call posixTransportTcp_Connect, wh_Client_Init, etc.
}

All functions are unsafe. For a safe API see the wolfhsm crate.

Build requirements

• The wolfhsm-src crate must be a direct [dependency] (not [build-dependency]) so Cargo propagates its DEP_WOLFHSM_SRC_* metadata to this crate's build script. wolfhsm-sys declares this dependency automatically — you do not need to add wolfhsm-src to your own Cargo.toml.
• wolfHSM source: set WOLFHSM_SRC or initialise the bundled submodule.
• wolfSSL headers: set WOLFSSL_DIR or WOLFSSL_INCLUDE_DIR.

See wolfhsm-src for full configuration details.

Features

References

• wolfHSM repository
• wolfHSM documentation
• wolfssl-rs workspace

Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

wolfHSM is copyright wolfSSL Inc. and its contributors.

License

GPL-3.0-only OR LicenseRef-wolfSSL-commercial

Available under the GNU General Public License v3.0. For proprietary or commercial use, a commercial license is available from wolfSSL Inc.