wolftpm-sys 0.3.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
121
122
123
124

# wolftpm-sys

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

Most users should depend on the higher-level [`wolftpm`](../wolftpm)
crate instead. Use `wolftpm-sys` directly only if you need a wolfTPM C
API symbol that is not yet wrapped by `wolftpm`.

## Why

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

- The bindgen output can be regenerated (by bumping
  [`wolftpm-src`](../wolftpm-src)) without forcing a breaking-change
  version bump on [`wolftpm`](../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.

## Usage

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

```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
[`wolftpm`](../wolftpm).

### Build prerequisites

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

See [`wolftpm-src`](../wolftpm-src) for full configuration details.

## How it works

`build.rs` performs three steps:

1. **Read build metadata** — reads `DEP_WOLFCRYPT_SYS_*` from
   [`wolfcrypt-sys`](../wolfcrypt-sys) (wolfSSL include paths, vendored
   flag, lib dirs) and `DEP_WOLFTPM_SRC_*` from
   [`wolftpm-src`](../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` `include!`s the generated `bindings.rs` with the standard set
of `#[allow]` attributes for bindgen output, exposes the `tpm_rc`
helper module, and conditionally exposes `swtpm` (a shared
`init_swtpm` helper used by both `wolftpm::Device::open_swtpm` and
`wolftpm-tss::WolfTpmSwtpm::connect`).

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 does not 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`](../wolftpm) exposes them.

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

## References

- [wolftpm](../wolftpm) — safe Rust API; use this unless you have a specific reason not to
- [wolftpm-src](../wolftpm-src) — vendored wolfTPM source build
- [wolftpm-tss](../wolftpm-tss) — tpm-rs TSS backend that consumes these bindings
- [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/)
- [workspace README](../README.md)

## Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

wolfTPM is copyright wolfSSL Inc. and its contributors.

## License

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

The underlying wolfTPM C library is also dual-licensed under
GPL-3.0-or-later with a commercial option available from
[wolfSSL Inc.](https://www.wolfssl.com/license/)