wolfhsm

Safe Rust client for wolfHSM hardware security modules. Wraps the wolfHSM C client library with an idiomatic Rust API; the wolfHSM server runs separately on secure hardware (Infineon TC3xx, Microchip PIC32CZ, Renesas RH850, etc.) or a POSIX simulator.

Why

The wolfHSM C client is portable and small, but it is a raw C API. This crate adds the Rust guarantees the C API cannot express:

• Hardware-isolated keys — ECC P-256, Ed25519, Curve25519, RSA, ML-DSA, AES, CMAC keys are generated and stored inside the secure enclave; private key material never crosses the transport.
• RAII cache-slot management — closure-based key APIs guarantee server cache slots are evicted on every path, including when the closure returns Err.
• Typed key handles — EccP256Key, RsaKey, Ed25519Key, AesKey, Curve25519Key, MlDsaKey, CmacKey prevent mixing key types at compile time.
• Result everywhere — no raw C return-code checking in application code.
• RustCrypto interop — EccP256Key::signer and Ed25519Key::signer return signature::Signer adapters, so HSM keys plug into any code expecting a signature::Signer.
• &mut Client enforces protocol — the wolfHSM transport allows only one in-flight request; requiring &mut Client on every method makes the borrow checker enforce that invariant.

Usage

[dependencies]
wolfhsm = "0.1"

Connect and sign

use wolfhsm::{Client, Transport};

let mut client = Client::connect(
    Transport::Tcp { ip: "127.0.0.1".into(), port: 8080 },
    1, // client id
)?;

let digest = [0u8; 32]; // SHA-256 of the data to sign
let sig = client.with_ecc_p256_key(|key, client| {
    key.sign_digest(client, &digest)
})?;

with_ecc_p256_key generates the key, runs the closure, and always evicts the cache slot — even if the closure returns Err.

Multiple operations on the same key

let (pub_der, sig) = client.with_ecc_p256_key(|key, client| {
    let pub_der = key.public_key_der(client)?;
    let sig = key.sign_digest(client, &digest)?;
    Ok((pub_der, sig))
})?;
// Cache slot evicted here, regardless of outcome.

NVM (persistent object store)

use wolfhsm::NvmId;

let id: NvmId = /* … */;
client.nvm_add(id, /* access */ 0, /* flags */ 0, b"my-key", &key_bytes)?;
let data = client.nvm_read(id, /* offset */ 0)?;
client.nvm_delete(id)?;

CryptoCb integration

Register the HSM as a wolfCrypt CryptoCb device so existing wolfCrypt code routes operations to the HSM transparently:

use wolfhsm::CryptoCbGuard;

let _guard = CryptoCbGuard::register(&mut client)?;
// While `_guard` is alive, wolfCrypt operations using DEV_ID are
// dispatched to the HSM. Dropped on scope exit.

RustCrypto Signer

use signature::Signer;

client.with_ecc_p256_key(|key, client| {
    let signer = key.signer(client);
    let sig: p256::ecdsa::DerSignature = signer.sign(b"message");
    Ok(sig)
})?;

How it works

wolfhsm-src     Compiles the wolfHSM C client library from source via the
│               cc crate; emits DEP_WOLFHSM_SRC_{INCLUDE,LIB}.
│
wolfhsm-sys     bindgen-generated FFI to wh_client.h plus C shims that
│               stack-allocate wolfCrypt key/context structs on the
│               C side (those types are opaque from Rust).
│
wolfhsm         Safe Rust API — Client, typed key handles, NVM,
                counters, CryptoCb, RustCrypto adapters (this crate).

The communication model is request/response over a transport:

Your app (Rust) → wolfhsm → wolfHSM C client → TCP/UDS/SHM → wolfHSM server

The server is a separate process or secure-element firmware. It must be running before Client::connect is called.

Transport variants

Feature flags

Build prerequisites

A wolfHSM source tree and a compiled wolfSSL with WOLF_CRYPTO_CB enabled are required at build time. Configuration is handled by wolfhsm-src and wolfhsm-sys; see those crates for the full set of supported environment variables (WOLFHSM_SRC, WOLFSSL_DIR, WOLFSSL_INCLUDE_DIR, WOLFSSL_SRC).

References

• wolfhsm-sys — raw FFI bindings; use this only if you need a wolfHSM C symbol that is not yet wrapped here
• wolfhsm-src — vendored wolfHSM C source build
• wolfcrypt-tls — safe Rust TLS using wolfSSL (the wolfssl crate name)
• wolfHSM repository
• wolfHSM documentation
• workspace README

Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

wolfHSM is copyright wolfSSL Inc. and its contributors.

License

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

The underlying wolfHSM C library is licensed under GPL-3.0-or-later with a commercial option available from wolfSSL Inc.