wolftpm-sys 0.2.0

Auto-generated Rust FFI bindings to wolfTPM
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
119
120

# wolftpm-sys

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

Most users should depend on the higher-level [`wolftpm`](https://crates.io/crates/wolftpm)
crate instead.  Use `wolftpm-sys` directly only if you need access to wolfTPM
C API symbols that are not yet wrapped by `wolftpm`.

## What

`wolftpm-sys` exposes the wolfTPM C API directly as `unsafe` Rust functions
and types.  The bindings cover:

- **Core TPM2 structures** — `TPM2B_*`, `TPMA_*`, `TPMS_*`, `TPMT_*`,
  `TPML_*`, `TPMU_*`, and the full set of TPM 2.0 algorithm and command
  constants from the TCG specification
- **wolfTPM2 wrapper types** — `WOLFTPM2_DEV`, `WOLFTPM2_KEY`,
  `WOLFTPM2_HASH`, `WOLFTPM2_NV`, `WOLFTPM2_SESSION`, `WOLFTPM2_CAPS`
- **wolfTPM2 wrapper functions** — the complete `wolfTPM2_*` high-level API
  (init, key generation, signing, ECDH, PCR, NV storage, sessions,
  attestation, sealing, firmware upgrade, and more)
- **Low-level TPM2 command API** — `TPM2_*` functions for direct command
  construction when the wrapper doesn't cover a use case

The wolfSSL key-import/export helpers (`wolfTPM2_RsaKey_To_Device` etc.) are
excluded from the current bindings (`WOLFTPM2_NO_WOLFCRYPT`).  They will be
added in a future version once the safe Rust wrapper in `wolftpm` exposes them.

## Why

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

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

## How it works

`build.rs` performs three steps:

1. **Read build metadata** — reads `DEP_WOLFCRYPT_SYS_*` from `wolfcrypt-sys`
   (wolfSSL include paths, vendored flag, lib dirs) and `DEP_WOLFTPM_SRC_*`
   from `wolftpm-src` (wolfTPM include path and compiled library location).
2. **Emit link directives** — instructs `rustc` to search for `libwolftpm.a`
   in the `wolftpm-src` output directory and to link it, followed by the
   wolfSSL library.
3. **Run bindgen** — generates `bindings.rs` in `OUT_DIR` from `wrapper.h`,
   which includes `<wolftpm/tpm2.h>` and `<wolftpm/tpm2_wrap.h>`.  The
   allowlist captures `wolfTPM2_*` functions and `WOLFTPM2_*` / `TPM2_*` /
   `TPM*` types and constants; wolfSSL internals are excluded via
   `-DWOLFTPM2_NO_WOLFCRYPT`.

`lib.rs` simply `include!`s the generated `bindings.rs` with the standard
set of `#[allow]` attributes for bindgen output.

## How to use

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

```rust
use wolftpm_sys::*;

unsafe {
    let mut dev: WOLFTPM2_DEV = core::mem::zeroed();
    let rc = wolfTPM2_Init(&mut dev, None, core::ptr::null_mut());
    assert_eq!(rc, 0);
    wolfTPM2_Cleanup(&mut dev);
}
```

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

## Build requirements

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

See [`wolftpm-src`](https://crates.io/crates/wolftpm-src) for full
configuration details.

## Features

| Feature | Description |
|---|---|
| `linux-dev` | Linux `/dev/tpm0` kernel driver transport — propagates to `wolftpm-src` |
| `swtpm` | Software TPM socket transport — propagates to `wolftpm-src` |

## References

- [wolfTPM repository](https://github.com/wolfSSL/wolfTPM)
- [wolfTPM API documentation](https://wolfssl.github.io/wolfTPM/)
- [TCG TPM2 Part 3: Commands](https://trustedcomputinggroup.org/resource/tpm-library-specification/)
- [wolfssl-rs workspace](https://github.com/wolfSSL/wolfssl-rs)

## Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

wolfTPM 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/)