Skip to content

Commit abef2c4

Browse files
aidangarskeaidangarske
authored
Merge pull request #8 from aidangarske/add-wiki-page-for-wolfspdm
Add wolfSPDM wiki documentation
2 parents d3d9c50 + 2f30f91 commit abef2c4

11 files changed

Lines changed: 506 additions & 121 deletions

‎CLAUDE.md‎

Lines changed: 0 additions & 109 deletions
This file was deleted.

‎README.md‎

Lines changed: 34 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,19 @@ export SPDM_EMU_PATH=../spdm-emu/build/bin
101101

102102
The driver starts/stops `spdm_responder_emu` per test and runs six scenarios — Session, Signed Measurements, Unsigned Measurements, Challenge, Heartbeat, Key Update — across SPDM 1.2, 1.3, and 1.4 (18 tests total).
103103

104+
## Relationship to wolfTPM's SPDM
105+
106+
wolfTPM ships its own SPDM implementation in `src/spdm/` for hardware-backed responders (Nuvoton NPCT75x, NSING NS350) with PSK / TCG-binding extensions. **wolfSPDM is a separate implementation** focused on the standard DSP0274 / DSP0277 requester for embedded use with `spdm-emu` and any standards-compliant peer. The two share heritage and are both designed for lightweight embedded use, with different deployment targets:
107+
108+
| | wolfSPDM | wolfTPM `src/spdm/` |
109+
|---|---|---|
110+
| Role | Requester only | Requester + responder |
111+
| Scope | Pure standard SPDM 1.2 / 1.3 / 1.4 | Same, plus PSK / TCG / Nuvoton / Nations vendor bindings |
112+
| Target | Embedded / spdm-emu / generic SPDM peer | TPM hardware (Nuvoton, NS350) |
113+
| Footprint | ~32 KB context, zero-malloc (default static mode) | Lightweight embedded footprint; size depends on TPM stack, target, and build configuration |
114+
115+
Either library can be used standalone; they aren't link-time compatible.
116+
104117
## CI / Testing
105118

106119
Runs on every push and PR:
@@ -114,18 +127,27 @@ Runs on every push and PR:
114127
- **SPDM Emulator Integration**: 18-test matrix (6 scenarios x SPDM 1.2 / 1.3 / 1.4) across ubuntu-22.04 x64, ubuntu-24.04 x64, and ubuntu-24.04-arm aarch64
115128
- **Skoll review**: wolfSSL deep-review pipeline, pre-merge security and code review
116129

117-
## Relationship to wolfTPM's SPDM
118-
119-
wolfTPM ships its own SPDM implementation in `src/spdm/` for hardware-backed responders (Nuvoton NPCT75x, NSING NS350) with PSK / TCG-binding extensions. **wolfSPDM is a separate implementation** focused on the standard DSP0274 / DSP0277 requester for embedded use with `spdm-emu` and any standards-compliant peer. The two share heritage but solve different problems:
120-
121-
| | wolfSPDM | wolfTPM `src/spdm/` |
122-
|---|---|---|
123-
| Role | Requester only | Requester + responder |
124-
| Scope | Pure standard SPDM 1.2 / 1.3 / 1.4 | Same, plus PSK / TCG / Nuvoton / Nations vendor bindings |
125-
| Target | Embedded / spdm-emu / generic SPDM peer | TPM hardware (Nuvoton, NS350) |
126-
| Footprint | ~32 KB context, zero-malloc | Larger; includes TPM stack |
127-
128-
Either library can be used standalone; they aren't link-time compatible.
130+
<a href="https://github.com/aidangarske/wolfSPDM/actions">
131+
<img src="https://img.shields.io/github/actions/workflow/status/aidangarske/wolfSPDM/build-test.yml?label=CI&logo=github">
132+
</a>
133+
<a href="https://github.com/wolfssl/skoll">
134+
<img src="https://img.shields.io/badge/skoll-passed-blue">
135+
</a>
136+
<a href="https://github.com/wolfssl/fenrir">
137+
<img src="https://img.shields.io/badge/fenrir-passed-blueviolet">
138+
</a>
139+
140+
## Documentation
141+
142+
Full documentation is available in the Wiki:
143+
144+
- [Getting Started](https://github.com/aidangarske/wolfSPDM/wiki/Getting-Started): Build instructions, prerequisites, memory modes, and first connection steps
145+
- [Supported Operations](https://github.com/aidangarske/wolfSPDM/wiki/Supported-Operations): SPDM operation coverage and API mapping
146+
- [API Reference](https://github.com/aidangarske/wolfSPDM/wiki/API-Reference): Public function groups and common error-code references
147+
- [Configuration and Macros](https://github.com/aidangarske/wolfSPDM/wiki/Configuration-and-Macros): Configure flags and compile-time feature controls
148+
- [Testing and CI](https://github.com/aidangarske/wolfSPDM/wiki/Testing-and-CI): Unit tests, emulator integration tests, and CI workflow coverage
149+
- [Project Structure](https://github.com/aidangarske/wolfSPDM/wiki/Project-Structure): Source layout and module responsibilities
150+
- [Attestation Notes](https://github.com/aidangarske/wolfSPDM/wiki/Attestation-Notes): Measurement and challenge attestation behavior
129151

130152
## License
131153

‎docs/wiki/API-Reference.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# API Reference
2+
3+
Public APIs are declared in `wolfspdm/spdm.h`.
4+
5+
All APIs return `WOLFSPDM_SUCCESS` (`0`) on success unless documented otherwise; failures are negative error codes from `wolfspdm/spdm_error.h`.
6+
7+
## Context and lifecycle
8+
9+
- `wolfSPDM_Init`
10+
- `wolfSPDM_InitStatic`
11+
- `wolfSPDM_GetCtxSize`
12+
- `wolfSPDM_Free`
13+
- `wolfSPDM_New` *(only when built with `WOLFSPDM_DYNAMIC_MEMORY`)*
14+
15+
## Configuration
16+
17+
- `wolfSPDM_SetIO`
18+
- `wolfSPDM_SetMaxVersion`
19+
- `wolfSPDM_SetRequesterSessionId`
20+
- `wolfSPDM_AllowUntrustedCerts`
21+
- `wolfSPDM_SetTrustedCAs`
22+
- `wolfSPDM_SetDebug`
23+
24+
## Session establishment and state
25+
26+
- `wolfSPDM_Connect`
27+
- `wolfSPDM_IsConnected`
28+
- `wolfSPDM_Disconnect`
29+
- `wolfSPDM_GetSessionId`
30+
- `wolfSPDM_GetNegotiatedVersion`
31+
- `wolfSPDM_GetVersion_Negotiated` *(legacy compatibility symbol)*
32+
- `wolfSPDM_GetLastPeerError`
33+
34+
## Fine-grained handshake
35+
36+
- `wolfSPDM_GetVersion`
37+
- `wolfSPDM_GetCapabilities`
38+
- `wolfSPDM_NegotiateAlgorithms`
39+
- `wolfSPDM_GetDigests`
40+
- `wolfSPDM_GetCertificate`
41+
- `wolfSPDM_KeyExchange`
42+
- `wolfSPDM_Finish`
43+
44+
## Secured messaging
45+
46+
- `wolfSPDM_SecuredExchange`
47+
- `wolfSPDM_SendData` *(not in `WOLFSPDM_LEAN`)*
48+
- `wolfSPDM_ReceiveData` *(not in `WOLFSPDM_LEAN`)*
49+
- `wolfSPDM_EncryptMessage` *(not in `WOLFSPDM_LEAN`)*
50+
- `wolfSPDM_DecryptMessage` *(not in `WOLFSPDM_LEAN`)*
51+
52+
## Attestation
53+
54+
- `wolfSPDM_GetMeasurements` *(not with `NO_WOLFSPDM_MEAS`)*
55+
- `wolfSPDM_GetMeasurementCount` *(not with `NO_WOLFSPDM_MEAS`)*
56+
- `wolfSPDM_GetMeasurementBlock` *(not with `NO_WOLFSPDM_MEAS`)*
57+
- `wolfSPDM_Challenge` *(not with `NO_WOLFSPDM_CHALLENGE`)*
58+
59+
## Session maintenance
60+
61+
- `wolfSPDM_Heartbeat`
62+
- `wolfSPDM_KeyUpdate`
63+
64+
## Error utilities
65+
66+
- `wolfSPDM_GetErrorString`
67+
68+
## Common error codes
69+
70+
Examples:
71+
- `WOLFSPDM_E_INVALID_ARG`
72+
- `WOLFSPDM_E_BAD_STATE`
73+
- `WOLFSPDM_E_NOT_CONNECTED`
74+
- `WOLFSPDM_E_IO_FAIL`
75+
- `WOLFSPDM_E_PEER_ERROR`
76+
- `WOLFSPDM_E_MEAS_SIG_FAIL`
77+
- `WOLFSPDM_E_CHALLENGE`
78+
- `WOLFSPDM_E_KEY_UPDATE`

‎docs/wiki/Attestation-Notes.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Attestation Notes
2+
3+
wolfSPDM supports SPDM attestation through both measurement retrieval and challenge authentication.
4+
5+
## Measurement attestation (`GET_MEASUREMENTS`)
6+
7+
Primary API:
8+
9+
```c
10+
int wolfSPDM_GetMeasurements(WOLFSPDM_CTX* ctx, byte measOperation,
11+
int requestSignature);
12+
```
13+
14+
Behavior:
15+
- `requestSignature=1`: requests signed measurements; verifies signature when verification support is compiled in
16+
- `requestSignature=0`: retrieves unsigned measurements (informational)
17+
18+
Result access:
19+
- `wolfSPDM_GetMeasurementCount`
20+
- `wolfSPDM_GetMeasurementBlock`
21+
22+
Relevant return codes:
23+
- `WOLFSPDM_SUCCESS`
24+
- `WOLFSPDM_E_MEAS_NOT_VERIFIED`
25+
- `WOLFSPDM_E_MEAS_SIG_FAIL`
26+
- `WOLFSPDM_E_MEASUREMENT`
27+
28+
## Sessionless challenge attestation (`CHALLENGE_AUTH`)
29+
30+
Primary API:
31+
32+
```c
33+
int wolfSPDM_Challenge(WOLFSPDM_CTX* ctx, int slotId, byte measHashType);
34+
```
35+
36+
Typical prerequisite state:
37+
- Version/capabilities/algorithms negotiated
38+
- Digest and cert chain retrieved
39+
40+
## Trust anchor handling
41+
42+
Load trusted CA material with:
43+
44+
```c
45+
int wolfSPDM_SetTrustedCAs(WOLFSPDM_CTX* ctx, const byte* derCerts,
46+
word32 derCertsSz);
47+
```
48+
49+
`wolfSPDM_SetTrustedCAs` currently accepts a single DER certificate buffer for root-hash matching.
50+
51+
## Feature toggles
52+
53+
- `NO_WOLFSPDM_MEAS` disables measurements
54+
- `NO_WOLFSPDM_MEAS_VERIFY` disables measurement signature verification
55+
- `NO_WOLFSPDM_CHALLENGE` disables challenge API
56+
57+
For deeper measurement details and test examples, see `docs/ATTESTATION.md`.

‎docs/wiki/Configuration-and-Macros.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Configuration and Macros
2+
3+
## Configure-time options
4+
5+
From `configure.ac`:
6+
7+
| Option | Default | Effect |
8+
|--------|---------|--------|
9+
| `--with-wolfssl=PATH` | system paths | Adds wolfSSL include/library search paths |
10+
| `--enable-debug` | off | Defines `WOLFSPDM_DEBUG`, builds with `-g -O0` |
11+
| `--enable-dynamic-mem` | off | Defines `WOLFSPDM_DYNAMIC_MEMORY` and enables `wolfSPDM_New` |
12+
13+
## Public feature macros
14+
15+
Defined in `wolfspdm/spdm.h` depending on build flags:
16+
17+
- `WOLFSPDM_HAS_MEASUREMENTS` *(not defined if `NO_WOLFSPDM_MEAS`)*
18+
- `WOLFSPDM_HAS_CHALLENGE` *(not defined if `NO_WOLFSPDM_CHALLENGE`)*
19+
- `WOLFSPDM_HAS_HEARTBEAT`
20+
- `WOLFSPDM_HAS_KEY_UPDATE`
21+
22+
## Size and protocol constants
23+
24+
From `wolfspdm/spdm.h` and `wolfspdm/spdm_types.h`:
25+
26+
- `WOLFSPDM_CTX_STATIC_SIZE` = `32768`
27+
- `WOLFSPDM_MAX_MSG_SIZE` = `4096`
28+
- `WOLFSPDM_MAX_CERT_CHAIN` = `4096`
29+
- `WOLFSPDM_MAX_TRANSCRIPT` = `4096`
30+
31+
Version constants:
32+
- `SPDM_VERSION_12`, `SPDM_VERSION_13`, `SPDM_VERSION_14`
33+
34+
Measurement constants (when enabled):
35+
- `SPDM_MEAS_OPERATION_ALL`
36+
- `SPDM_MEAS_SUMMARY_HASH_NONE`, `_TCB`, `_ALL`
37+
38+
## Common compile-time feature toggles
39+
40+
These are used in source-level conditional compilation:
41+
42+
| Macro | Effect |
43+
|-------|--------|
44+
| `NO_WOLFSPDM_MEAS` | Removes measurement APIs and related fields/code |
45+
| `NO_WOLFSPDM_MEAS_VERIFY` | Keeps retrieval path but disables measurement signature verification |
46+
| `NO_WOLFSPDM_CHALLENGE` | Removes challenge-attestation API/code |
47+
| `WOLFSPDM_LEAN` | Excludes selected convenience secured-message helpers |
48+
49+
## Notes
50+
51+
- `wolfspdm/options.h` is auto-generated from `config.h` during build/install.
52+
- API availability should be detected using feature macros rather than hard-coded assumptions.

0 commit comments

Comments
 (0)