wolfhsm-sys 0.1.3

Auto-generated Rust FFI bindings to wolfHSM
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# wolfhsm-sys

Raw Rust FFI bindings to [wolfHSM](https://github.com/wolfSSL/wolfHSM),
auto-generated by `bindgen` at build time.

Most users should depend on the higher-level [`wolfhsm`](https://crates.io/crates/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

```toml
[dependencies]
wolfhsm-sys = "0.1"
```

```rust
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`](https://crates.io/crates/wolfhsm-src) for full
configuration details.

## Features

| Feature | Description |
|---|---|
| `she` | SHE (Secure Hardware Extension) — propagates to `wolfhsm-src` |

## References

- [wolfHSM repository](https://github.com/wolfSSL/wolfHSM)
- [wolfHSM documentation](https://www.wolfssl.com/documentation/manuals/wolfhsm/)
- [wolfssl-rs workspace](https://github.com/wolfSSL/wolfssl-rs)

## 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](https://www.gnu.org/licenses/gpl-3.0.html).
For proprietary or commercial use, a commercial license is available from
[wolfSSL Inc.](https://www.wolfssl.com/license/)