From 2f30f91c4636cc98e724a10339b26c538b7ea2ec Mon Sep 17 00:00:00 2001 From: aidan garske Date: Fri, 15 May 2026 12:42:48 -0700 Subject: [PATCH] Add wolfSPDM wiki documentation Add wiki pages covering setup, configuration, API usage, attestation, supported operations, project structure, and testing. Update the README links and remove repository-local CLAUDE.md guidance. --- CLAUDE.md | 109 -------------------------- README.md | 46 ++++++++--- docs/wiki/API-Reference.md | 78 ++++++++++++++++++ docs/wiki/Attestation-Notes.md | 57 ++++++++++++++ docs/wiki/Configuration-and-Macros.md | 52 ++++++++++++ docs/wiki/Getting-Started.md | 82 +++++++++++++++++++ docs/wiki/Home.md | 57 ++++++++++++++ docs/wiki/Project-Structure.md | 44 +++++++++++ docs/wiki/Supported-Operations.md | 45 +++++++++++ docs/wiki/Testing-and-CI.md | 47 +++++++++++ docs/wiki/_Sidebar.md | 10 +++ 11 files changed, 506 insertions(+), 121 deletions(-) delete mode 100644 CLAUDE.md create mode 100644 docs/wiki/API-Reference.md create mode 100644 docs/wiki/Attestation-Notes.md create mode 100644 docs/wiki/Configuration-and-Macros.md create mode 100644 docs/wiki/Getting-Started.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Project-Structure.md create mode 100644 docs/wiki/Supported-Operations.md create mode 100644 docs/wiki/Testing-and-CI.md create mode 100644 docs/wiki/_Sidebar.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 790b14a..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,109 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -wolfSPDM is a lightweight SPDM 1.2/1.3/1.4 requester (initiator) implementation using wolfCrypt for cryptographic operations. It provides authenticated and encrypted communication with SPDM responders per DMTF DSP0274/DSP0277 specifications, tested against the DMTF spdm-emu emulator. - -**Key characteristics:** -- Standard SPDM 1.2 / 1.3 / 1.4 negotiation -- Algorithm Set B only: ECDSA P-384, ECDHE P-384, SHA-384, AES-256-GCM, HKDF-SHA384 -- Zero-malloc by default (static memory ~28KB context), optional `--enable-dynamic-mem` for heap allocation -- Requester-only - pair with any SPDM responder (e.g. spdm-emu) - -## Build Commands - -```bash -./autogen.sh # Generate configure script -./configure --with-wolfssl=/usr/local # Configure (adjust wolfSSL path as needed) -make # Build library -make check # Run unit tests -sudo make install # Install library -``` - -**Configure options:** -- `--enable-debug` - Debug output with -g -O0 (default: -O2) -- `--enable-dynamic-mem` - Use heap allocation for WOLFSPDM_CTX (default: static/zero-malloc) -- `--with-wolfssl=PATH` - wolfSSL installation path - -## Testing - -**Unit tests:** -```bash -make check # Runs test/unit_test -./test/unit_test # Run directly -``` - -**Integration test (requires DMTF spdm-emu):** -```bash -export SPDM_EMU_PATH=../spdm-emu/build/bin -./examples/spdm_test.sh # Runs 18 tests (6 scenarios x SPDM 1.2/1.3/1.4) -``` - -The script starts/stops `spdm_responder_emu` per test and runs session -establishment, signed measurements, unsigned measurements, challenge -authentication, heartbeat, and key update. - -## Architecture - -### Source Organization -``` -src/ # Core implementation - spdm_context.c # Context lifecycle (New/Init/Free) - spdm_msg.c # Message building/parsing - spdm_crypto.c # ECC operations - spdm_kdf.c # HKDF key derivation - spdm_transcript.c # Transcript buffer for TH1/TH2 - spdm_secured.c # AES-256-GCM encryption/decryption - spdm_session.c # Session management - spdm_internal.h # Internal declarations - -wolfspdm/ # Public API headers - spdm.h # Main API - spdm_types.h # Protocol constants - spdm_error.h # Error codes - -examples/ - spdm_demo.c # CLI demo: --emu/--meas/--challenge/--heartbeat/--key-update - spdm_test.sh # Integration test driver (runs 18 tests against spdm-emu) - -test/ - unit_test.c # Unit tests - test_spdm.c # Smoke test (single session against emu) -``` - -### Protocol State Machine -``` -INIT -> VERSION -> CAPS -> ALGO -> DIGESTS -> CERT -> KEY_EX -> FINISH -> CONNECTED -> MEASURED -``` - -### Key Patterns - -**Return codes:** 0 = success, negative = error (see `spdm_error.h`) - -**Buffer pattern:** Output size is input capacity and output actual size: -```c -int func(..., byte* buf, word32* bufSz); -``` - -**Transport abstraction:** I/O callback handles all transport: -```c -typedef int (*WOLFSPDM_IO_CB)(WOLFSPDM_CTX* ctx, - const byte* txBuf, word32 txSz, - byte* rxBuf, word32* rxSz, - void* userCtx); -``` - -**Memory:** Zero-malloc by default (static context via `wolfSPDM_InitStatic()`). With `--enable-dynamic-mem`, uses XMALLOC/XFREE macros (wolfCrypt convention) for heap allocation via `wolfSPDM_New()`. Fixed-size internal buffers (4KB max message/cert/transcript). - -### Cryptographic Constants -- Hash: 48 bytes (SHA-384) -- ECC key: 48 bytes, point: 96 bytes, signature: 96 bytes (P-384) -- AEAD: 32-byte key, 12-byte IV, 16-byte tag (AES-256-GCM) - -## Dependencies - -wolfSSL/wolfCrypt configured with: `--enable-wolftpm --enable-ecc --enable-sha384 --enable-aesgcm --enable-hkdf --enable-sp` - -**Build order:** wolfSSL (install) -> wolfSPDM (build). `WOLFSPDM_CTX_STATIC_SIZE` depends on wolfSSL internal struct sizes (`ecc_key`, `wc_Sha384`, `WC_RNG`), so wolfSPDM must be rebuilt whenever wolfSSL config changes. diff --git a/README.md b/README.md index e36de1b..881aef2 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,19 @@ export SPDM_EMU_PATH=../spdm-emu/build/bin 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). +## Relationship to wolfTPM's SPDM + +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: + +| | wolfSPDM | wolfTPM `src/spdm/` | +|---|---|---| +| Role | Requester only | Requester + responder | +| Scope | Pure standard SPDM 1.2 / 1.3 / 1.4 | Same, plus PSK / TCG / Nuvoton / Nations vendor bindings | +| Target | Embedded / spdm-emu / generic SPDM peer | TPM hardware (Nuvoton, NS350) | +| Footprint | ~32 KB context, zero-malloc (default static mode) | Lightweight embedded footprint; size depends on TPM stack, target, and build configuration | + +Either library can be used standalone; they aren't link-time compatible. + ## CI / Testing Runs on every push and PR: @@ -114,18 +127,27 @@ Runs on every push and PR: - **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 - **Skoll review**: wolfSSL deep-review pipeline, pre-merge security and code review -## Relationship to wolfTPM's SPDM - -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: - -| | wolfSPDM | wolfTPM `src/spdm/` | -|---|---|---| -| Role | Requester only | Requester + responder | -| Scope | Pure standard SPDM 1.2 / 1.3 / 1.4 | Same, plus PSK / TCG / Nuvoton / Nations vendor bindings | -| Target | Embedded / spdm-emu / generic SPDM peer | TPM hardware (Nuvoton, NS350) | -| Footprint | ~32 KB context, zero-malloc | Larger; includes TPM stack | - -Either library can be used standalone; they aren't link-time compatible. + + + + + + + + + + +## Documentation + +Full documentation is available in the Wiki: + +- [Getting Started](https://github.com/aidangarske/wolfSPDM/wiki/Getting-Started): Build instructions, prerequisites, memory modes, and first connection steps +- [Supported Operations](https://github.com/aidangarske/wolfSPDM/wiki/Supported-Operations): SPDM operation coverage and API mapping +- [API Reference](https://github.com/aidangarske/wolfSPDM/wiki/API-Reference): Public function groups and common error-code references +- [Configuration and Macros](https://github.com/aidangarske/wolfSPDM/wiki/Configuration-and-Macros): Configure flags and compile-time feature controls +- [Testing and CI](https://github.com/aidangarske/wolfSPDM/wiki/Testing-and-CI): Unit tests, emulator integration tests, and CI workflow coverage +- [Project Structure](https://github.com/aidangarske/wolfSPDM/wiki/Project-Structure): Source layout and module responsibilities +- [Attestation Notes](https://github.com/aidangarske/wolfSPDM/wiki/Attestation-Notes): Measurement and challenge attestation behavior ## License diff --git a/docs/wiki/API-Reference.md b/docs/wiki/API-Reference.md new file mode 100644 index 0000000..85f2c11 --- /dev/null +++ b/docs/wiki/API-Reference.md @@ -0,0 +1,78 @@ +# API Reference + +Public APIs are declared in `wolfspdm/spdm.h`. + +All APIs return `WOLFSPDM_SUCCESS` (`0`) on success unless documented otherwise; failures are negative error codes from `wolfspdm/spdm_error.h`. + +## Context and lifecycle + +- `wolfSPDM_Init` +- `wolfSPDM_InitStatic` +- `wolfSPDM_GetCtxSize` +- `wolfSPDM_Free` +- `wolfSPDM_New` *(only when built with `WOLFSPDM_DYNAMIC_MEMORY`)* + +## Configuration + +- `wolfSPDM_SetIO` +- `wolfSPDM_SetMaxVersion` +- `wolfSPDM_SetRequesterSessionId` +- `wolfSPDM_AllowUntrustedCerts` +- `wolfSPDM_SetTrustedCAs` +- `wolfSPDM_SetDebug` + +## Session establishment and state + +- `wolfSPDM_Connect` +- `wolfSPDM_IsConnected` +- `wolfSPDM_Disconnect` +- `wolfSPDM_GetSessionId` +- `wolfSPDM_GetNegotiatedVersion` +- `wolfSPDM_GetVersion_Negotiated` *(legacy compatibility symbol)* +- `wolfSPDM_GetLastPeerError` + +## Fine-grained handshake + +- `wolfSPDM_GetVersion` +- `wolfSPDM_GetCapabilities` +- `wolfSPDM_NegotiateAlgorithms` +- `wolfSPDM_GetDigests` +- `wolfSPDM_GetCertificate` +- `wolfSPDM_KeyExchange` +- `wolfSPDM_Finish` + +## Secured messaging + +- `wolfSPDM_SecuredExchange` +- `wolfSPDM_SendData` *(not in `WOLFSPDM_LEAN`)* +- `wolfSPDM_ReceiveData` *(not in `WOLFSPDM_LEAN`)* +- `wolfSPDM_EncryptMessage` *(not in `WOLFSPDM_LEAN`)* +- `wolfSPDM_DecryptMessage` *(not in `WOLFSPDM_LEAN`)* + +## Attestation + +- `wolfSPDM_GetMeasurements` *(not with `NO_WOLFSPDM_MEAS`)* +- `wolfSPDM_GetMeasurementCount` *(not with `NO_WOLFSPDM_MEAS`)* +- `wolfSPDM_GetMeasurementBlock` *(not with `NO_WOLFSPDM_MEAS`)* +- `wolfSPDM_Challenge` *(not with `NO_WOLFSPDM_CHALLENGE`)* + +## Session maintenance + +- `wolfSPDM_Heartbeat` +- `wolfSPDM_KeyUpdate` + +## Error utilities + +- `wolfSPDM_GetErrorString` + +## Common error codes + +Examples: +- `WOLFSPDM_E_INVALID_ARG` +- `WOLFSPDM_E_BAD_STATE` +- `WOLFSPDM_E_NOT_CONNECTED` +- `WOLFSPDM_E_IO_FAIL` +- `WOLFSPDM_E_PEER_ERROR` +- `WOLFSPDM_E_MEAS_SIG_FAIL` +- `WOLFSPDM_E_CHALLENGE` +- `WOLFSPDM_E_KEY_UPDATE` diff --git a/docs/wiki/Attestation-Notes.md b/docs/wiki/Attestation-Notes.md new file mode 100644 index 0000000..d6bd32f --- /dev/null +++ b/docs/wiki/Attestation-Notes.md @@ -0,0 +1,57 @@ +# Attestation Notes + +wolfSPDM supports SPDM attestation through both measurement retrieval and challenge authentication. + +## Measurement attestation (`GET_MEASUREMENTS`) + +Primary API: + +```c +int wolfSPDM_GetMeasurements(WOLFSPDM_CTX* ctx, byte measOperation, + int requestSignature); +``` + +Behavior: +- `requestSignature=1`: requests signed measurements; verifies signature when verification support is compiled in +- `requestSignature=0`: retrieves unsigned measurements (informational) + +Result access: +- `wolfSPDM_GetMeasurementCount` +- `wolfSPDM_GetMeasurementBlock` + +Relevant return codes: +- `WOLFSPDM_SUCCESS` +- `WOLFSPDM_E_MEAS_NOT_VERIFIED` +- `WOLFSPDM_E_MEAS_SIG_FAIL` +- `WOLFSPDM_E_MEASUREMENT` + +## Sessionless challenge attestation (`CHALLENGE_AUTH`) + +Primary API: + +```c +int wolfSPDM_Challenge(WOLFSPDM_CTX* ctx, int slotId, byte measHashType); +``` + +Typical prerequisite state: +- Version/capabilities/algorithms negotiated +- Digest and cert chain retrieved + +## Trust anchor handling + +Load trusted CA material with: + +```c +int wolfSPDM_SetTrustedCAs(WOLFSPDM_CTX* ctx, const byte* derCerts, + word32 derCertsSz); +``` + +`wolfSPDM_SetTrustedCAs` currently accepts a single DER certificate buffer for root-hash matching. + +## Feature toggles + +- `NO_WOLFSPDM_MEAS` disables measurements +- `NO_WOLFSPDM_MEAS_VERIFY` disables measurement signature verification +- `NO_WOLFSPDM_CHALLENGE` disables challenge API + +For deeper measurement details and test examples, see `docs/ATTESTATION.md`. diff --git a/docs/wiki/Configuration-and-Macros.md b/docs/wiki/Configuration-and-Macros.md new file mode 100644 index 0000000..baa31df --- /dev/null +++ b/docs/wiki/Configuration-and-Macros.md @@ -0,0 +1,52 @@ +# Configuration and Macros + +## Configure-time options + +From `configure.ac`: + +| Option | Default | Effect | +|--------|---------|--------| +| `--with-wolfssl=PATH` | system paths | Adds wolfSSL include/library search paths | +| `--enable-debug` | off | Defines `WOLFSPDM_DEBUG`, builds with `-g -O0` | +| `--enable-dynamic-mem` | off | Defines `WOLFSPDM_DYNAMIC_MEMORY` and enables `wolfSPDM_New` | + +## Public feature macros + +Defined in `wolfspdm/spdm.h` depending on build flags: + +- `WOLFSPDM_HAS_MEASUREMENTS` *(not defined if `NO_WOLFSPDM_MEAS`)* +- `WOLFSPDM_HAS_CHALLENGE` *(not defined if `NO_WOLFSPDM_CHALLENGE`)* +- `WOLFSPDM_HAS_HEARTBEAT` +- `WOLFSPDM_HAS_KEY_UPDATE` + +## Size and protocol constants + +From `wolfspdm/spdm.h` and `wolfspdm/spdm_types.h`: + +- `WOLFSPDM_CTX_STATIC_SIZE` = `32768` +- `WOLFSPDM_MAX_MSG_SIZE` = `4096` +- `WOLFSPDM_MAX_CERT_CHAIN` = `4096` +- `WOLFSPDM_MAX_TRANSCRIPT` = `4096` + +Version constants: +- `SPDM_VERSION_12`, `SPDM_VERSION_13`, `SPDM_VERSION_14` + +Measurement constants (when enabled): +- `SPDM_MEAS_OPERATION_ALL` +- `SPDM_MEAS_SUMMARY_HASH_NONE`, `_TCB`, `_ALL` + +## Common compile-time feature toggles + +These are used in source-level conditional compilation: + +| Macro | Effect | +|-------|--------| +| `NO_WOLFSPDM_MEAS` | Removes measurement APIs and related fields/code | +| `NO_WOLFSPDM_MEAS_VERIFY` | Keeps retrieval path but disables measurement signature verification | +| `NO_WOLFSPDM_CHALLENGE` | Removes challenge-attestation API/code | +| `WOLFSPDM_LEAN` | Excludes selected convenience secured-message helpers | + +## Notes + +- `wolfspdm/options.h` is auto-generated from `config.h` during build/install. +- API availability should be detected using feature macros rather than hard-coded assumptions. diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md new file mode 100644 index 0000000..cb69701 --- /dev/null +++ b/docs/wiki/Getting-Started.md @@ -0,0 +1,82 @@ +# Getting Started + +## Prerequisites + +wolfSPDM depends on wolfSSL/wolfCrypt with SPDM-required algorithms enabled. + +Minimum validated wolfSSL version: **v5.8.0-stable**. + +Example wolfSSL build: + +```bash +git clone https://github.com/wolfSSL/wolfssl.git +cd wolfssl +./autogen.sh +./configure --enable-wolftpm --enable-ecc --enable-sha384 \ + --enable-aesgcm --enable-hkdf --enable-sp +make +sudo make install +sudo ldconfig +``` + +## Build wolfSPDM + +```bash +./autogen.sh +./configure --with-wolfssl=/usr/local +make +make check +``` + +### Configure options + +| Option | Description | +|--------|-------------| +| `--with-wolfssl=PATH` | Path to wolfSSL headers/libs | +| `--enable-debug` | Enables debug build flags and `WOLFSPDM_DEBUG` | +| `--enable-dynamic-mem` | Enables heap-allocated context APIs (`wolfSPDM_New`) | + +## Memory modes + +### Static mode (default) + +Zero-malloc operation with caller-managed context memory: + +```c +byte spdmBuf[WOLFSPDM_CTX_STATIC_SIZE]; +WOLFSPDM_CTX* ctx = (WOLFSPDM_CTX*)spdmBuf; +wolfSPDM_InitStatic(ctx, sizeof(spdmBuf)); +``` + +`WOLFSPDM_CTX_STATIC_SIZE` is 32768 bytes. + +### Dynamic mode (optional) + +Enable with `--enable-dynamic-mem`, then: + +```c +WOLFSPDM_CTX* ctx = wolfSPDM_New(); +``` + +## Minimal connection flow + +1. Initialize context (`wolfSPDM_Init` or `wolfSPDM_InitStatic`) +2. Register transport callback with `wolfSPDM_SetIO` +3. Optionally set trust root with `wolfSPDM_SetTrustedCAs` +4. Establish session with `wolfSPDM_Connect` +5. Exchange secured data using `wolfSPDM_SecuredExchange` (or send/receive helpers) +6. End session with `wolfSPDM_Disconnect` +7. Cleanup via `wolfSPDM_Free` + +## Transport callback contract + +All transport is caller-owned through: + +```c +typedef int (*WOLFSPDM_IO_CB)(WOLFSPDM_CTX* ctx, + const byte* txBuf, word32 txSz, + byte* rxBuf, word32* rxSz, + void* userCtx); +``` + +The callback sends raw SPDM/SPDM-secured records and returns the responder message. diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..b95e52c --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,57 @@ +# wolfSPDM Documentation + +Welcome to the wolfSPDM wiki. This documentation covers wolfSPDM, a lightweight requester-only SPDM implementation for embedded systems and constrained environments. + +## What is wolfSPDM? + +wolfSPDM is a C library implementing: +- **SPDM 1.2 / 1.3 / 1.4** ([DMTF DSP0274](https://www.dmtf.org/sites/default/files/standards/documents/DSP0274_1.4.0.pdf)) +- **Secured Messages over MCTP** ([DMTF DSP0277](https://www.dmtf.org/sites/default/files/standards/documents/DSP0277_1.2.0.pdf)) + +It uses [wolfSSL / wolfCrypt](https://www.wolfssl.com/) as its crypto backend and is tested end-to-end against the DMTF [spdm-emu](https://github.com/DMTF/spdm-emu) responder emulator. + +## Key Features + +| Feature | Description | +|---------|-------------| +| Requester-only SPDM stack | Purpose-built initiator implementation | +| SPDM 1.2/1.3/1.4 | Standards-based negotiation and session setup | +| Fixed Algorithm Set B | ECDSA P-384, ECDHE P-384, SHA-384, AES-256-GCM, HKDF-SHA384 | +| Zero-malloc by default | Static context (`WOLFSPDM_CTX_STATIC_SIZE`, 32 KB) | +| Optional dynamic context | `--enable-dynamic-mem` enables `wolfSPDM_New()` | +| Attestation operations | Signed/unsigned `GET_MEASUREMENTS`, sessionless `CHALLENGE_AUTH` | +| Session operations | `HEARTBEAT`, `KEY_UPDATE`, secured app data transfer | +| CI + security coverage | Multi-compiler, static analysis, CodeQL, Valgrind, spdm-emu integration | + +## Documentation + +| Page | Description | +|------|-------------| +| [[Getting Started]] | Dependencies, build, install, and first connection flow | +| [[Supported Operations]] | Supported SPDM flows and operation/API mapping | +| [[API Reference]] | Public API grouped by lifecycle and purpose | +| [[Configuration and Macros]] | Configure flags and compile-time feature controls | +| [[Testing and CI]] | Unit tests, emulator tests, and CI workflow coverage | +| [[Project Structure]] | Repository layout and module responsibilities | +| [[Attestation Notes]] | Measurement and challenge attestation details | + +## Protocol Session Flow + +The primary session establishment sequence is: + +`GET_VERSION -> GET_CAPABILITIES -> NEGOTIATE_ALGORITHMS -> GET_DIGESTS -> GET_CERTIFICATE -> KEY_EXCHANGE -> FINISH` + +After `FINISH`, secured messaging and maintenance operations are available. + +## Quick Links + +- [GitHub Repository](https://github.com/aidangarske/wolfSPDM) +- [README](https://github.com/aidangarske/wolfSPDM/blob/main/README.md) +- [DMTF DSP0274 (SPDM)](https://www.dmtf.org/sites/default/files/standards/documents/DSP0274_1.4.0.pdf) +- [DMTF DSP0277 (Secured Messages)](https://www.dmtf.org/sites/default/files/standards/documents/DSP0277_1.2.0.pdf) +- [wolfSSL Website](https://www.wolfssl.com/) + +## License + +wolfSPDM is free software licensed under GPLv3. +For commercial licensing and support, contact [wolfSSL](https://www.wolfssl.com/contact/). diff --git a/docs/wiki/Project-Structure.md b/docs/wiki/Project-Structure.md new file mode 100644 index 0000000..59f1e00 --- /dev/null +++ b/docs/wiki/Project-Structure.md @@ -0,0 +1,44 @@ +# Project Structure + +## Top-level layout + +| Path | Purpose | +|------|---------| +| `src/` | Core protocol, crypto glue, transcript, secured messaging, and session logic | +| `wolfspdm/` | Public headers (`spdm.h`, `spdm_types.h`, `spdm_error.h`) | +| `examples/` | Demo client and emulator integration script | +| `test/` | Unit tests and emulator smoke test | +| `docs/` | Project documentation (including attestation notes) | +| `.github/workflows/` | CI workflows | + +## Core source modules + +| File | Responsibility | +|------|----------------| +| `src/spdm_context.c` | Context init/free lifecycle and state setup | +| `src/spdm_msg.c` | SPDM message construction and parsing | +| `src/spdm_crypto.c` | Cryptographic helper operations | +| `src/spdm_kdf.c` | HKDF-based key derivation | +| `src/spdm_transcript.c` | Transcript management (TH computations) | +| `src/spdm_secured.c` | Secured message protection (AES-256-GCM) | +| `src/spdm_session.c` | Handshake/session flow and higher-level operations | +| `src/spdm_internal.h` | Internal types, constants, and internal APIs | + +## Public API surface + +| Header | Content | +|--------|---------| +| `wolfspdm/spdm.h` | Main public API and feature macros | +| `wolfspdm/spdm_types.h` | SPDM protocol constants and algorithm identifiers | +| `wolfspdm/spdm_error.h` | Error code enum and error-string helper | + +## Build/test assets + +| File | Purpose | +|------|---------| +| `configure.ac` | Autotools configure logic and options | +| `Makefile.am` | Library, test, and example build targets | +| `examples/spdm_demo.c` | CLI demo for session/measurement/challenge/heartbeat/key update | +| `examples/spdm_test.sh` | 18-case emulator integration driver | +| `test/unit_test.c` | Unit test coverage | +| `test/test_spdm.c` | SPDM smoke-test utility | diff --git a/docs/wiki/Supported-Operations.md b/docs/wiki/Supported-Operations.md new file mode 100644 index 0000000..1409aeb --- /dev/null +++ b/docs/wiki/Supported-Operations.md @@ -0,0 +1,45 @@ +# Supported Operations + +wolfSPDM implements requester-side SPDM operations for session establishment, secure data exchange, attestation, and session maintenance. + +## Operation coverage + +| Operation | SPDM area | wolfSPDM API | +|----------|-----------|--------------| +| Version negotiation | GET_VERSION | `wolfSPDM_GetVersion` | +| Capability negotiation | GET_CAPABILITIES | `wolfSPDM_GetCapabilities` | +| Algorithm negotiation | NEGOTIATE_ALGORITHMS | `wolfSPDM_NegotiateAlgorithms` | +| Certificate digest retrieval | GET_DIGESTS | `wolfSPDM_GetDigests` | +| Certificate chain retrieval | GET_CERTIFICATE | `wolfSPDM_GetCertificate` | +| Session key exchange | KEY_EXCHANGE | `wolfSPDM_KeyExchange` | +| Session finalization | FINISH | `wolfSPDM_Finish` | +| One-shot full connect | Full handshake | `wolfSPDM_Connect` | +| Secured app exchange | Secured messages | `wolfSPDM_SecuredExchange` | +| App send/receive helpers | Secured messages | `wolfSPDM_SendData`, `wolfSPDM_ReceiveData` | +| Measurements (signed/unsigned) | GET_MEASUREMENTS | `wolfSPDM_GetMeasurements` | +| Measurement block access | Measurement parsing | `wolfSPDM_GetMeasurementCount`, `wolfSPDM_GetMeasurementBlock` | +| Sessionless challenge auth | CHALLENGE / CHALLENGE_AUTH | `wolfSPDM_Challenge` | +| Keep-alive | HEARTBEAT | `wolfSPDM_Heartbeat` | +| Session key rotation | KEY_UPDATE | `wolfSPDM_KeyUpdate` | + +## Supported protocol versions + +- SPDM 1.2 (`0x12`) +- SPDM 1.3 (`0x13`) +- SPDM 1.4 (`0x14`) + +Maximum negotiated version can be capped with `wolfSPDM_SetMaxVersion`. + +## Fixed cryptographic profile (Algorithm Set B) + +- Hash: SHA-384 +- Asymmetric signature: ECDSA P-384 +- DHE: secp384r1 +- AEAD: AES-256-GCM +- Key schedule: SPDM key schedule + HKDF-SHA384 + +## Notable implementation scope + +- Requester-only implementation (no responder role) +- Designed for standards-based SPDM peers and DMTF spdm-emu +- Trust anchor support via `wolfSPDM_SetTrustedCAs` (single DER CA cert buffer) diff --git a/docs/wiki/Testing-and-CI.md b/docs/wiki/Testing-and-CI.md new file mode 100644 index 0000000..7681657 --- /dev/null +++ b/docs/wiki/Testing-and-CI.md @@ -0,0 +1,47 @@ +# Testing and CI + +## Local tests + +### Unit tests + +```bash +make check +./test/unit_test +``` + +### Integration test with DMTF spdm-emu + +```bash +export SPDM_EMU_PATH=../spdm-emu/build/bin +./examples/spdm_test.sh +``` + +`spdm_test.sh` runs 18 scenarios: +- Session +- Signed measurements +- Unsigned measurements +- Challenge +- Heartbeat +- Key update + +Across SPDM versions 1.2, 1.3, and 1.4. + +## CI workflow coverage + +Documented workflows include: + +- Build and Test (OS/config matrix) +- Multiple Compilers (GCC 11-13, Clang 14-17) +- Compiler Warnings (`-Werror`, pedantic/conversion/shadow checks) +- Static Analysis (cppcheck + scan-build) +- Memory Check (Valgrind) +- Empty Brace Scope Scan +- CodeQL Security +- Codespell +- SPDM Emulator Test (integration matrix on x64 + aarch64) + +See `.github/workflows/README.md` for workflow inventory details. + +## Validation caveat + +Building/tests require a compatible wolfSSL installation and may fail if `--with-wolfssl` is not provided or wolfSSL is absent from default search paths. diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 0000000..d3f3ddd --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,10 @@ +### Documentation + +- [[Home]] +- [[Getting Started]] +- [[Supported Operations]] +- [[API Reference]] +- [[Configuration and Macros]] +- [[Testing and CI]] +- [[Project Structure]] +- [[Attestation Notes]]