diff --git a/README.md b/README.md index 635a0048..4e3c46cd 100644 --- a/README.md +++ b/README.md @@ -79,9 +79,10 @@ Supported algorithms: | ML-KEM (key encapsulation) | FIPS 203 | ML-KEM-512 / 768 / 1024 | wolfTPM **officially supports the SealSQ QVault TPM**, the first shipping TPM 2.0 -with these v1.85 PQC algorithms in silicon. Build for it with `--enable-sealsq ---enable-pqc`. The same examples and wrapper API also run against the in-tree -fwTPM server for CI or when no hardware is present. See the +with these v1.85 PQC algorithms in silicon. See +[Hardware TPM: SealSQ QVault](#hardware-tpm-sealsq-qvault) for its hardware +build. The same PQC API also runs against the in-tree fwTPM server for CI or +when no hardware is present. See the [TPM2 Benchmarks](#tpm2-benchmarks) section for measured ML-DSA / ML-KEM performance on the QVault TPM. @@ -97,21 +98,45 @@ make sudo make install ``` -**wolfTPM**: +#### fwTPM (software TPM) ``` ./configure --enable-fwtpm --enable-pqc make ``` -`--enable-v185` turns on the full v1.85 build (`WOLFTPM_V185`): the PQC -algorithms plus the non-PQC v1.85 spec additions. `--enable-pqc` turns on -just the lean PQC subset (`WOLFTPM_PQC`) — ML-DSA / ML-KEM only — which is -smaller for deployments that do not need the rest of v1.85. If you omit both -but `--enable-fwtpm` is set and wolfCrypt has ML-DSA + ML-KEM available, -configure auto-detects and enables full v1.85. Pass `--disable-pqc` to opt +The fwTPM server uses the full v1.85 command set, so configure promotes +`--enable-pqc` to `--enable-v185`. If you omit both flags and wolfCrypt has +ML-DSA + ML-KEM, configure auto-enables v1.85. Pass `--disable-pqc` to opt out explicitly. +#### Hardware TPM: SealSQ QVault + +SealSQ QVault is the hardware TPM currently supported for v1.85 PQC: + +``` +./configure --enable-sealsq --enable-pqc +make +``` + +On Linux, add `--enable-devtpm` to use the kernel TPM driver. For examples +that pass transient handles between processes, also add +`CFLAGS='-DTPM2_LINUX_DEV="/dev/tpm0"'`: the default `/dev/tpmrm0` virtualizes +and discards those handles when a process closes the device. Keep the inner +double quotes literal inside the single-quoted `CFLAGS` value. See +[docs/DEVTPM.md](docs/DEVTPM.md) for device permissions and details. + +`--enable-pqc` builds the lean ML-DSA / ML-KEM subset (`WOLFTPM_PQC`) for +hardware. Use `--enable-v185` (`WOLFTPM_V185`) for the full v1.85 command set. + +Non-SHA-1 TPM examples include: + +``` +./examples/pqc/pqc_ctrl --caps --algs +./examples/pqc/pqc_ctrl --mldsa=65 --mlkem=768 +./examples/wrap/hash "wolfTPM" -sha256 +``` + #### Trimming the PQC footprint To compile only the operations you call (smaller binary, no malloc needed), @@ -146,6 +171,8 @@ fwTPM always builds the full v1.85 spec surface, so the trims apply on top of make check ``` +`make check` runs the fwTPM tests, including PQC coverage. + See [examples/pqc/README.md](examples/pqc/README.md) for per-example details — the `pqc_ctrl` control center (every PQC operation plus board control in one CLI, with `pqc_ctrl.sh` running the full command set), @@ -197,7 +224,9 @@ There is also an Ephemeral hierarchy (`TPM_RH_NULL`), which can be used to creat ### Platform Configuration Registers (PCRs) -Contains hash digests for SHA-1 and SHA-256 with an index 0-23. These hash digests can be extended to prove the integrity of a boot sequence (secure boot). +PCRs hold hash digests at indices 0-23 in banks supported and allocated by the +TPM. They can be extended to prove the integrity of a boot sequence (secure +boot). ### Terminology diff --git a/configure.ac b/configure.ac index 1cfe06c8..f0b9510a 100644 --- a/configure.ac +++ b/configure.ac @@ -980,11 +980,11 @@ then # directly, so older wolfSSL that # only ships is not supported here. AC_CHECK_DECL([wc_MlDsaKey_Init], [], - [AC_MSG_ERROR([--enable-v185/--enable-pqc requires wolfSSL built with --enable-mldsa (or alias --enable-dilithium) and --enable-experimental, ships post-v5.9.1-stable])], + [AC_MSG_ERROR([--enable-v185/--enable-pqc requires wolfSSL built with --enable-mldsa (or alias --enable-dilithium), ships post-v5.9.1-stable])], [[#include #include ]]) AC_CHECK_DECL([wc_MlKemKey_Init], [], - [AC_MSG_ERROR([--enable-v185/--enable-pqc requires wolfSSL >= v5.8.0-stable built with --enable-mlkem --enable-experimental])], + [AC_MSG_ERROR([--enable-v185/--enable-pqc requires wolfSSL >= v5.8.0-stable built with --enable-mlkem])], [[#include #include ]]) diff --git a/examples/pqc/README.md b/examples/pqc/README.md index e9c5546e..77381452 100644 --- a/examples/pqc/README.md +++ b/examples/pqc/README.md @@ -3,10 +3,10 @@ Examples exercising the ML-DSA / ML-KEM post-quantum additions from TCG TPM 2.0 Library Specification v1.85, wrapped by `wolfTPM2_*` API calls. -These examples run on the SealSQ QVault TPM — the first shipping TPM 2.0 with -v1.85 post-quantum (ML-DSA / ML-KEM) algorithms in silicon — over SPI, and on -the in-tree fwTPM server for CI or when no hardware is present. Build for the -SealSQ part with `--enable-sealsq --enable-pqc`; see +These examples run on the in-tree fwTPM server for CI or when no hardware is +present. They also run on the SealSQ QVault TPM, which implements v1.85 +ML-DSA / ML-KEM in silicon, over SPI or the Linux TPM device. See +[Hardware TPM: SealSQ QVault](#hardware-tpm-sealsq-qvault) for its build and [docs/FWTPM.md](../../docs/FWTPM.md#tpm-20-v185-post-quantum-support) for the fwTPM PQC reference. @@ -16,7 +16,7 @@ fwTPM PQC reference. ``` ./configure --enable-wolftpm --enable-mldsa --enable-mlkem \ - --enable-tls-mlkem-standalone --enable-experimental \ + --enable-tls-mlkem-standalone \ --enable-harden --enable-keygen --enable-certgen make sudo make install @@ -30,24 +30,26 @@ groups; without it wolfSSL only offers the hybrid groups and `--enable-wolftpm` provides the crypto callback and private-key-id support the TLS server uses. -**wolfTPM**: +### fwTPM (software TPM) ``` ./configure --enable-fwtpm --enable-pqc make ``` -`--enable-pqc` is an alias for `--enable-v185`. If you omit both but -`--enable-fwtpm` is set and wolfCrypt has ML-DSA + ML-KEM, -configure auto-enables PQC. +The fwTPM server needs the full v1.85 command set, so configure promotes +`--enable-pqc` to `--enable-v185`. If you omit both flags and wolfCrypt has +ML-DSA + ML-KEM, configure auto-enables v1.85. -## Run the test suite +#### Run the test suite ``` make check ``` -Runs the full suite, including all PQC coverage: +With the fwTPM build above, this runs the software-TPM suite, including PQC +coverage: + - `tests/fwtpm_unit.test` — 30+ in-process PQC handler tests - `tests/unit.test` — PQC wrapper tests over the mssim socket (ML-DSA Sign/Verify Sequence, ML-KEM Encap/Decap, EncryptSecret MLKEM, etc.) @@ -61,9 +63,37 @@ for faster targeted iteration: ./tests/pqc_mssim_e2e.sh # PQC E2E only (fastest PQC-focused check) ``` +### Hardware TPM: SealSQ QVault + +SealSQ QVault is the hardware TPM currently supported for v1.85 PQC: + +``` +./configure --enable-sealsq --enable-pqc +make +``` + +On Linux, add `--enable-devtpm` to use the kernel TPM driver. For examples +that pass transient handles between processes, also add +`CFLAGS='-DTPM2_LINUX_DEV="/dev/tpm0"'`: the default `/dev/tpmrm0` virtualizes +and discards those handles when a process closes the device. Keep the inner +double quotes literal inside the single-quoted `CFLAGS` value. See +[docs/DEVTPM.md](../../docs/DEVTPM.md) for details and permissions. + +Non-SHA-1 TPM examples include: + +``` +./examples/pqc/pqc_ctrl --caps --algs +./examples/pqc/pqc_ctrl --mldsa=65 --mlkem=768 +./examples/wrap/hash "wolfTPM" -sha256 +``` + +`./examples/pqc/pqc_ctrl.sh` runs the full PQC command set when the device +supports all parameter sets. + ## Individual examples -All examples expect a running `fwtpm_server` on `127.0.0.1:2321`: +With an fwTPM build, start `fwtpm_server` on `127.0.0.1:2321` before running +the examples below. A SealSQ build uses its configured hardware transport. ``` ./src/fwtpm/fwtpm_server --clear & @@ -196,9 +226,10 @@ by loading it back: ./examples/keygen/keyload keyblob.bin ``` -A successful load prints `Loaded key to 0x80000000`. The full 18-way +A successful load prints a transient key handle. The full 18-way matrix (three variants x three parameter sets) is exercised by -`examples/run_examples.sh` when v1.85 is detected in `config.h`. +`examples/run_examples.sh` when v1.85 is detected in `config.h`; that generic +suite also covers non-PQC operations with their own TPM requirements. ### PQC keys for parameter encryption @@ -255,8 +286,7 @@ against a software CA. Requires a wolfSSL that routes `wc_MlDsaKey_SignCtx` to the crypto callback for device keys (private key in the TPM). That landed upstream, so master or any -later release works. No shipping TPM implements TCG v1.85 PQC yet, so this runs -against the in-tree fwTPM. +later release works. The commands below start the in-tree fwTPM for this demo. Demo scope: the identity key is an unauthenticated deterministic TPM primary (empty auth), reproducible by both `gen_pqc_certs` and the server from the owner