From cbad37e79c7029dcee3a97a12a0dfb5e5e1f471f Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Wed, 29 Jul 2026 12:43:36 -0700
Subject: [PATCH 1/9] Document the wolfProvider post-quantum build options and
 defines

---
 wolfProvider/src-ja/chapter03.md |   7 +
 wolfProvider/src/chapter03.md    | 277 +++++++++++++++++++++++++++++++
 2 files changed, 284 insertions(+)

diff --git a/wolfProvider/src-ja/chapter03.md b/wolfProvider/src-ja/chapter03.md
index 4196745e..bc129258 100644
--- a/wolfProvider/src-ja/chapter03.md
+++ b/wolfProvider/src-ja/chapter03.md
@@ -261,6 +261,10 @@ wolfProviderを静的エンジンとして使用するには`--static`を付け
 | --enable-usersettings | **無効** | user_settings.h を使用し、MakefileのCFLAGSを使用しない |
 | --enable-dynamic | 有効 | wolfProviderをダイナミックプロバイダーとしてロードできるようにする |
 | --enable-singlethreaded | **無効** | wolfProviderをシングルスレッド環境で使用する |
+| --enable-pqc | **無効** | ポスト量子アルゴリズム (ML-KEM、ML-DSA、SLH-DSA) をすべて有効にする |
+| --enable-mlkem | **無効** | ML-KEM (FIPS 203) のみを有効にする |
+| --enable-mldsa | **無効** | ML-DSA (FIPS 204) のみを有効にする |
+| --enable-slhdsa | **無効** | SLH-DSA (FIPS 205) のみを有効にする |
 | | | | |
 | --with-openssl=DIR | | リンクするOpenSSLのインストール場所。設定されていない場合は、システムのデフォルトのライブラリとインクルードパスが使用されます。 |
 | --with-wolfssl=DIR | | リンクするwolfSSLのインストール場所。設定されていない場合は、システムのデフォルトのライブラリとインクルードパスが使用されます。 |
@@ -304,6 +308,8 @@ wolfProviderは、お客様がwolfProviderのビルド方法を設定できる
 | WP_HAVE_KRB5KDF | Kerberos 5 鍵導出関数を有効化 |
 | WP_HAVE_MD5 | MD5 ハッシュアルゴリズムを有効化 |
 | WP_HAVE_MD5_SHA1 | MD5+SHA1 の組み合わせを有効化 |
+| WP_HAVE_MLDSA | ML-DSA (FIPS 204) ポスト量子署名を有効化 |
+| WP_HAVE_MLKEM | ML-KEM (FIPS 203) ポスト量子鍵カプセル化を有効化 |
 | WP_HAVE_PBE | パスワードベースの暗号化を有効化 |
 | WP_HAVE_RANDOM | 乱数生成を有効化 |
 | WP_HAVE_RSA | RSA 暗号化と署名を有効化 |
@@ -320,6 +326,7 @@ wolfProviderは、お客様がwolfProviderのビルド方法を設定できる
 | WP_HAVE_SHA512_224 | SHA512/224 ハッシュアルゴリズムを有効化 |
 | WP_HAVE_SHA512_256 | SHA512/256 ハッシュアルゴリズムを有効化 |
 | WP_HAVE_SHAKE_256 | SHAKE256 拡張出力関数を有効化 |
+| WP_HAVE_SLHDSA | SLH-DSA (FIPS 205) ポスト量子署名を有効化 |
 | WP_HAVE_TLS1_PRF | TLS1 擬似乱数関数を有効化 |
 | WP_HAVE_X25519 | X25519 楕円曲線を有効化 |
 | WP_HAVE_X448 | X448 楕円曲線を有効化 |
diff --git a/wolfProvider/src/chapter03.md b/wolfProvider/src/chapter03.md
index b9d8d450..63a7bcf1 100644
--- a/wolfProvider/src/chapter03.md
+++ b/wolfProvider/src/chapter03.md
@@ -212,10 +212,284 @@ By default, wolfProvider only builds a shared library, with building of a static
 | --enable-usersettings | **Disabled** | Use your own user_settings.h and do not add Makefile CFLAGS |
 | --enable-dynamic | **Enabled** | Enable loading wolfProvider as a dynamic provider |
 | --enable-singlethreaded | **Disabled** | Enable wolfProvider single threaded |
+| --enable-pqc | **Disabled** | Enable all post-quantum algorithms: ML-KEM, ML-DSA and SLH-DSA |
+| --enable-mlkem | **Disabled** | Enable ML-KEM (FIPS 203) only |
+| --enable-mldsa | **Disabled** | Enable ML-DSA (FIPS 204) only |
+| --enable-slhdsa | **Disabled** | Enable SLH-DSA (FIPS 205) only |
 | | | |
 | --with-openssl=DIR |   | OpenSSL installation location to link against. If not set, use the system default library and include paths. |
 | --with-wolfssl=DIR |   | wolfSSL installation location to link against. If not set, use the system default library and include paths. |
 
+## Post-Quantum Cryptography
+
+wolfProvider supports the NIST post-quantum standards through the OpenSSL 3
+EVP interface. PQC support is opt-in so applications that do not need these
+algorithms are unaffected.
+
+### Requirements
+
+- wolfSSL v5.9.2-stable or later
+- OpenSSL 3.6 or later
+- A wolfSSL build with the required PQC algorithms enabled
+
+The packaged Debian build is not currently available with PQC because its
+system OpenSSL is older than OpenSSL 3.6.
+
+### Supported Algorithms
+
+| Algorithm | Standard | Supported Parameter Sets |
+| :-------- | :------- | :----------------------- |
+| ML-KEM | FIPS 203 | ML-KEM-512, ML-KEM-768, ML-KEM-1024 |
+| ML-DSA | FIPS 204 | ML-DSA-44, ML-DSA-65, ML-DSA-87 |
+| SLH-DSA with SHA-2 | FIPS 205 | SLH-DSA-SHA2-128s, SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, SLH-DSA-SHA2-192f, SLH-DSA-SHA2-256s, SLH-DSA-SHA2-256f |
+| SLH-DSA with SHAKE | FIPS 205 | SLH-DSA-SHAKE-128s, SLH-DSA-SHAKE-128f, SLH-DSA-SHAKE-192s, SLH-DSA-SHAKE-192f, SLH-DSA-SHAKE-256s, SLH-DSA-SHAKE-256f |
+
+ML-KEM supports key generation, encapsulation, decapsulation, raw key
+import/export, and public/private key encoding. ML-DSA supports key generation,
+pure and pre-hash signing, verification, context strings, and key encoding.
+SLH-DSA supports key generation, pure signing, verification, context strings,
+and key encoding.
+
+### Provider Architecture
+
+Applications use the standard OpenSSL 3 EVP interfaces. wolfProvider registers
+OpenSSL key management implementations for each parameter set, a KEM
+implementation for ML-KEM, and signature implementations for ML-DSA and
+SLH-DSA. The provider translates those operations to the corresponding
+wolfCrypt APIs and keeps the wolfCrypt key object inside the OpenSSL
+`EVP_PKEY`.
+
+| Family | OpenSSL Interfaces | Main Operations |
+| :----- | :----------------- | :-------------- |
+| ML-KEM | `EVP_PKEY`, `EVP_PKEY_CTX`, KEM | Key generation, encapsulation, decapsulation, key import/export |
+| ML-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure and pre-hash sign/verify, key import/export |
+| SLH-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure sign/verify, key import/export |
+
+Keys support raw public and private key parameters as well as DER and PEM
+encoding. Public keys use SubjectPublicKeyInfo and private keys use PKCS#8.
+Encrypted PKCS#8 private key output is also supported. The signature
+implementations expose the algorithm identifiers needed for X.509 certificate
+and request operations.
+
+### Sizes and Security Categories
+
+ML-KEM always produces a 32-byte shared secret:
+
+| Parameter Set | NIST Category | Public Key | Private Key | Ciphertext |
+| :------------ | :------------ | ---------: | ----------: | ---------: |
+| ML-KEM-512 | 1 | 800 bytes | 1,632 bytes | 768 bytes |
+| ML-KEM-768 | 3 | 1,184 bytes | 2,400 bytes | 1,088 bytes |
+| ML-KEM-1024 | 5 | 1,568 bytes | 3,168 bytes | 1,568 bytes |
+
+ML-DSA signatures and keys have fixed sizes for each parameter set:
+
+| Parameter Set | NIST Category | Public Key | Private Key | Signature |
+| :------------ | :------------ | ---------: | ----------: | --------: |
+| ML-DSA-44 | 2 | 1,312 bytes | 2,560 bytes | 2,420 bytes |
+| ML-DSA-65 | 3 | 1,952 bytes | 4,032 bytes | 3,309 bytes |
+| ML-DSA-87 | 5 | 2,592 bytes | 4,896 bytes | 4,627 bytes |
+
+For SLH-DSA, SHA-2 and SHAKE parameter sets at the same level have the same
+sizes. The `s` variants favor smaller signatures, while the `f` variants favor
+faster signing:
+
+| Parameter Sets | NIST Category | Public Key | Private Key | Signature |
+| :------------- | :------------ | ---------: | ----------: | --------: |
+| 128s | 1 | 32 bytes | 64 bytes | 7,856 bytes |
+| 128f | 1 | 32 bytes | 64 bytes | 17,088 bytes |
+| 192s | 3 | 48 bytes | 96 bytes | 16,224 bytes |
+| 192f | 3 | 48 bytes | 96 bytes | 35,664 bytes |
+| 256s | 5 | 64 bytes | 128 bytes | 29,792 bytes |
+| 256f | 5 | 64 bytes | 128 bytes | 49,856 bytes |
+
+### Signing and Generation Parameters
+
+ML-DSA and SLH-DSA accept the OpenSSL signature context-string parameter, with
+the FIPS 204 and FIPS 205 maximum of 255 bytes. Both support deterministic and
+randomized signing through OpenSSL signature parameters. ML-DSA additionally
+supports HashML-DSA pre-hash signing and external representative input.
+
+The key generation implementations accept the OpenSSL ML-KEM, ML-DSA, and
+SLH-DSA seed parameters. These deterministic paths are used by known-answer
+and ACVP testing. Normal application key generation and randomized signing use
+wolfCrypt's random number generator.
+
+OpenSSL presents one-shot and streaming digest-sign entry points to
+applications. wolfProvider incrementally hashes HashML-DSA input. Pure ML-DSA
+and SLH-DSA require the complete message; SLH-DSA therefore buffers streaming
+input and enforces a 64 MiB message limit.
+
+### Platform Optimizations
+
+wolfProvider calls the native wolfCrypt implementations, so it benefits from
+the optimized code selected by the wolfSSL build without requiring a separate
+provider-specific acceleration layer. Available wolfCrypt PQC speedups include
+x86-64 vectorized implementations and assembly paths for ARM32, AArch64,
+ARMv7-M, and ARMv7E-M. Optimized SHA-3 and SHAKE operations also accelerate
+the Keccak work used by ML-KEM and ML-DSA.
+
+The exact path is compiler, processor, and wolfSSL configuration dependent.
+Applications should use the wolfCrypt benchmark on the target system to
+confirm which implementation was selected and measure the relevant parameter
+sets. See the wolfSSL
+[PQC documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/appendix09.html)
+and [ML-KEM acceleration overview](https://www.wolfssl.com/accelerated-kyber-ml-kem/)
+for configuration and benchmark details.
+
+### Building
+
+The build script can configure OpenSSL, wolfSSL, and wolfProvider together:
+
+```sh
+./scripts/build-wolfprovider.sh --enable-pqc
+```
+
+`--enable-pqc` enables all three algorithm families. Each family can also be
+selected independently:
+
+```sh
+./scripts/build-wolfprovider.sh --enable-mlkem
+./scripts/build-wolfprovider.sh --enable-mldsa
+./scripts/build-wolfprovider.sh --enable-slhdsa
+```
+
+For a manual build, configure wolfSSL with the matching algorithm options,
+then configure wolfProvider:
+
+```sh
+# Add the required options to the normal wolfSSL configuration.
+./configure --enable-mlkem --enable-mldsa --enable-slhdsa
+make
+sudo make install
+
+# Configure wolfProvider against OpenSSL 3.6 or later.
+./configure --enable-pqc \
+    --with-openssl=/path/to/openssl \
+    --with-wolfssl=/path/to/wolfssl
+make
+sudo make install
+```
+
+PQC code is not compiled unless `--enable-pqc` or an individual PQC option is
+passed to wolfProvider, even when wolfSSL has the algorithms enabled.
+
+### Loading the Provider
+
+Set the provider module and configuration paths to the wolfProvider
+installation:
+
+```sh
+export OPENSSL_MODULES=/path/to/wolfprovider/lib
+export OPENSSL_CONF=/path/to/wolfProvider/provider.conf
+```
+
+Confirm that the expected algorithms are provided by `libwolfprov`:
+
+```sh
+openssl list -kem-algorithms -provider libwolfprov
+openssl list -signature-algorithms -provider libwolfprov
+```
+
+### OpenSSL EVP Example
+
+The maintained
+[`examples/pqc_openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/pqc_openssl_example.c)
+program demonstrates all three algorithm families through the OpenSSL EVP API:
+
+- ML-KEM-768 key generation, encapsulation, and decapsulation
+- ML-DSA-65 key generation, signing, and verification
+- SLH-DSA-SHA2-128f key generation, signing, and verification
+
+The example is built and run by `make check` when wolfProvider is configured
+with any PQC family. Compile-time guards run only the enabled families, so the
+same source also demonstrates ML-KEM-only, ML-DSA-only, and SLH-DSA-only
+builds. After building, it can also be run directly from the wolfProvider root:
+
+```sh
+./examples/pqc_openssl_example
+```
+
+The companion
+[`examples/openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/openssl_example.c)
+shows basic provider loading, build information, and self-test handling.
+
+ML-DSA supports pure ML-DSA and HashML-DSA through OpenSSL's digest-sign
+interface. SLH-DSA is a pure signature algorithm and does not accept a
+separate digest name. Its streaming interface buffers the complete message
+and limits it to 64 MiB.
+
+### Build Macros
+
+The configure options add the corresponding request macros:
+
+| Configure Option | wolfProvider Request Macro | wolfSSL Capability Macro |
+| :--------------- | :------------------------- | :----------------------- |
+| `--enable-mlkem` | `WOLFPROV_HAVE_MLKEM` | `WOLFSSL_HAVE_MLKEM` |
+| `--enable-mldsa` | `WOLFPROV_HAVE_MLDSA` | `WOLFSSL_HAVE_MLDSA` |
+| `--enable-slhdsa` | `WOLFPROV_HAVE_SLHDSA` | `WOLFSSL_HAVE_SLHDSA` |
+
+`--enable-pqc` enables all three request macros. After configuration validates
+the wolfSSL capabilities, wolfProvider uses `WP_HAVE_MLKEM`,
+`WP_HAVE_MLDSA`, and `WP_HAVE_SLHDSA` internally to compile and register the
+available implementations.
+
+### TLS 1.3
+
+wolfProvider advertises these ML-KEM TLS groups:
+
+- MLKEM512
+- MLKEM768
+- MLKEM1024
+- X25519MLKEM768
+- SecP256r1MLKEM768
+- SecP384r1MLKEM1024
+
+It also advertises the `mldsa44`, `mldsa65`, and `mldsa87` TLS 1.3 signature
+schemes. SLH-DSA is supported through EVP but is not advertised as a TLS
+signature scheme.
+
+### Validation
+
+The wolfCrypt Post Quantum v7.0.0 implementation has NIST CAVP algorithm
+validation under
+[certificate A8437](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/details?validation=41047).
+The certificate covers ML-KEM key generation, encapsulation, and
+decapsulation; ML-DSA key generation, signature generation, and signature
+verification; and SLH-DSA key generation, signature generation, and signature
+verification. It also covers the prerequisite SHA, SHAKE, HMAC, and DRBG
+implementations identified by the NIST record.
+
+This validation applies to the identified wolfCrypt version and operating
+environment. A wolfProvider application must use the corresponding validated
+wolfCrypt distribution and follow its security policy when a validated
+deployment is required.
+
+CAVP validates the algorithm implementations. It is distinct from validation
+of a complete cryptographic module under FIPS 140-3, so using an open source or
+FIPS-ready wolfSSL build does not by itself create a FIPS-validated
+application.
+
+PQC has several independent test layers:
+
+- Unit and example tests cover key generation, import/export, encoding,
+  encapsulation, decapsulation, signing, verification, malformed inputs, and
+  X.509 operations where applicable.
+- OpenSSL EVP known-answer tests run the ML-KEM, ML-DSA, and SLH-DSA vector
+  files against wolfProvider.
+- The PQC interoperability test compares wolfProvider with OpenSSL's default
+  provider and the direct wolfSSL APIs. It also tests ML-KEM and hybrid TLS
+  groups plus ML-DSA certificate authentication.
+- The nginx OSP workflow tests ML-KEM and hybrid TLS 1.3 key exchange with
+  ML-DSA authentication.
+- The pinned libacvp OSP workflow runs its complete unit suite and exercises
+  its OpenSSL ACVP handlers for ML-KEM, ML-DSA, and SLH-DSA.
+
+The version, nginx, and libacvp matrices cover wolfSSL master and the latest
+eligible stable release. OSP tests run in replace-default and non-replace
+modes, with normal and forced-failure cases. PQC KAT and version coverage runs
+for pull requests, while the longer OSP integration workflows are
+label-selected and run nightly.
+
 ## Build Defines
 
 wolfProvider exposes several preprocessor defines that allow users to configure how wolfProvider is built. These are described in the table below.
@@ -254,6 +528,8 @@ wolfProvider exposes several preprocessor defines that allow users to configure
 | WP_HAVE_KRB5KDF | Kerberos 5 Key Derivation Function support |
 | WP_HAVE_MD5 | MD5 hash algorithm support |
 | WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support |
+| WP_HAVE_MLDSA | ML-DSA (FIPS 204) post-quantum signature support |
+| WP_HAVE_MLKEM | ML-KEM (FIPS 203) post-quantum key encapsulation support |
 | WP_HAVE_PBE | Password-Based Encryption support |
 | WP_HAVE_RANDOM | Random number generation support |
 | WP_HAVE_RSA | RSA encryption and signature support |
@@ -270,6 +546,7 @@ wolfProvider exposes several preprocessor defines that allow users to configure
 | WP_HAVE_SHA512_224 | SHA512/224 hash algorithm support |
 | WP_HAVE_SHA512_256 | SHA512/256 hash algorithm support |
 | WP_HAVE_SHAKE_256 | SHAKE256 extendable output function support |
+| WP_HAVE_SLHDSA | SLH-DSA (FIPS 205) post-quantum signature support |
 | WP_HAVE_TLS1_PRF | TLS1 Pseudo-Random Function support |
 | WP_HAVE_X25519 | X25519 elliptic curve support |
 | WP_HAVE_X448 | X448 elliptic curve support |

From cbfd2bab2982088f83faeb67d85fea5357b72413 Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Fri, 31 Jul 2026 15:00:36 -0700
Subject: [PATCH 2/9] Document LMS support and PQC validation

---
 wolfProvider/src/chapter03.md | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/wolfProvider/src/chapter03.md b/wolfProvider/src/chapter03.md
index 63a7bcf1..aea591e9 100644
--- a/wolfProvider/src/chapter03.md
+++ b/wolfProvider/src/chapter03.md
@@ -212,10 +212,11 @@ By default, wolfProvider only builds a shared library, with building of a static
 | --enable-usersettings | **Disabled** | Use your own user_settings.h and do not add Makefile CFLAGS |
 | --enable-dynamic | **Enabled** | Enable loading wolfProvider as a dynamic provider |
 | --enable-singlethreaded | **Disabled** | Enable wolfProvider single threaded |
-| --enable-pqc | **Disabled** | Enable all post-quantum algorithms: ML-KEM, ML-DSA and SLH-DSA |
+| --enable-pqc | **Disabled** | Enable ML-KEM and ML-DSA (FIPS 203/204) |
 | --enable-mlkem | **Disabled** | Enable ML-KEM (FIPS 203) only |
 | --enable-mldsa | **Disabled** | Enable ML-DSA (FIPS 204) only |
 | --enable-slhdsa | **Disabled** | Enable SLH-DSA (FIPS 205) only |
+| --enable-lms | **Disabled** | Enable LMS verification only (requires OpenSSL 3.6+) |
 | | | |
 | --with-openssl=DIR |   | OpenSSL installation location to link against. If not set, use the system default library and include paths. |
 | --with-wolfssl=DIR |   | wolfSSL installation location to link against. If not set, use the system default library and include paths. |
@@ -243,12 +244,15 @@ system OpenSSL is older than OpenSSL 3.6.
 | ML-DSA | FIPS 204 | ML-DSA-44, ML-DSA-65, ML-DSA-87 |
 | SLH-DSA with SHA-2 | FIPS 205 | SLH-DSA-SHA2-128s, SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, SLH-DSA-SHA2-192f, SLH-DSA-SHA2-256s, SLH-DSA-SHA2-256f |
 | SLH-DSA with SHAKE | FIPS 205 | SLH-DSA-SHAKE-128s, SLH-DSA-SHAKE-128f, SLH-DSA-SHAKE-192s, SLH-DSA-SHAKE-192f, SLH-DSA-SHAKE-256s, SLH-DSA-SHAKE-256f |
+| LMS | RFC 8554 / NIST SP 800-208 | LMS and LMOTS public-key verification |
 
 ML-KEM supports key generation, encapsulation, decapsulation, raw key
 import/export, and public/private key encoding. ML-DSA supports key generation,
 pure and pre-hash signing, verification, context strings, and key encoding.
 SLH-DSA supports key generation, pure signing, verification, context strings,
-and key encoding.
+and key encoding. LMS supports public-key import and one-shot signature
+verification; private-key import, signing, and key generation are not exposed
+because OpenSSL 3.6 provides LMS as a verification-only interface.
 
 ### Provider Architecture
 
@@ -264,6 +268,7 @@ wolfCrypt APIs and keeps the wolfCrypt key object inside the OpenSSL
 | ML-KEM | `EVP_PKEY`, `EVP_PKEY_CTX`, KEM | Key generation, encapsulation, decapsulation, key import/export |
 | ML-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure and pre-hash sign/verify, key import/export |
 | SLH-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure sign/verify, key import/export |
+| LMS | `EVP_PKEY`, `EVP_MD_CTX`, signature | Public-key import/export and one-shot verification |
 
 Keys support raw public and private key parameters as well as DER and PEM
 encoding. Public keys use SubjectPublicKeyInfo and private keys use PKCS#8.
@@ -427,11 +432,12 @@ The configure options add the corresponding request macros:
 | `--enable-mlkem` | `WOLFPROV_HAVE_MLKEM` | `WOLFSSL_HAVE_MLKEM` |
 | `--enable-mldsa` | `WOLFPROV_HAVE_MLDSA` | `WOLFSSL_HAVE_MLDSA` |
 | `--enable-slhdsa` | `WOLFPROV_HAVE_SLHDSA` | `WOLFSSL_HAVE_SLHDSA` |
+| `--enable-lms` | `WOLFPROV_HAVE_LMS` | `WOLFSSL_HAVE_LMS` |
 
-`--enable-pqc` enables all three request macros. After configuration validates
-the wolfSSL capabilities, wolfProvider uses `WP_HAVE_MLKEM`,
-`WP_HAVE_MLDSA`, and `WP_HAVE_SLHDSA` internally to compile and register the
-available implementations.
+`--enable-pqc` enables ML-KEM and ML-DSA. SLH-DSA and LMS are enabled separately
+with `--enable-slhdsa` and `--enable-lms`. After configuration validates the wolfSSL capabilities,
+wolfProvider uses `WP_HAVE_MLKEM`, `WP_HAVE_MLDSA`, `WP_HAVE_SLHDSA`, and
+`WP_HAVE_LMS` internally to compile and register the available implementations.
 
 ### TLS 1.3
 
@@ -453,7 +459,8 @@ signature scheme.
 The wolfCrypt Post Quantum v7.0.0 implementation has NIST CAVP algorithm
 validation under
 [certificate A8437](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/details?validation=41047).
-The certificate covers ML-KEM key generation, encapsulation, and
+The certificate covers LMS signature verification; ML-KEM key generation,
+encapsulation, and
 decapsulation; ML-DSA key generation, signature generation, and signature
 verification; and SLH-DSA key generation, signature generation, and signature
 verification. It also covers the prerequisite SHA, SHAKE, HMAC, and DRBG
@@ -474,8 +481,8 @@ PQC has several independent test layers:
 - Unit and example tests cover key generation, import/export, encoding,
   encapsulation, decapsulation, signing, verification, malformed inputs, and
   X.509 operations where applicable.
-- OpenSSL EVP known-answer tests run the ML-KEM, ML-DSA, and SLH-DSA vector
-  files against wolfProvider.
+- OpenSSL EVP known-answer tests run the ML-KEM, ML-DSA, SLH-DSA, and LMS vector
+  files against wolfProvider. The LMS vector contains 320 verification cases.
 - The PQC interoperability test compares wolfProvider with OpenSSL's default
   provider and the direct wolfSSL APIs. It also tests ML-KEM and hybrid TLS
   groups plus ML-DSA certificate authentication.

From 32cf5464776722811de93f6ba152894b0cbb7c39 Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Fri, 31 Jul 2026 15:10:11 -0700
Subject: [PATCH 3/9] Move PQC guidance into a dedicated chapter

---
 wolfProvider/mkdocs.yml       |   1 +
 wolfProvider/src/chapter03.md | 340 +---------------------------------
 wolfProvider/src/chapter11.md | 340 ++++++++++++++++++++++++++++++++++
 3 files changed, 342 insertions(+), 339 deletions(-)
 create mode 100644 wolfProvider/src/chapter11.md

diff --git a/wolfProvider/mkdocs.yml b/wolfProvider/mkdocs.yml
index b2813886..5b217135 100644
--- a/wolfProvider/mkdocs.yml
+++ b/wolfProvider/mkdocs.yml
@@ -14,6 +14,7 @@ nav:
     - "8. wolfProvider Design": chapter08.md
     - "9. Notes on Open Source Integration": chapter09.md
     - "10. Support and OpenSSL Version Adding": chapter10.md
+    - "11. Post-Quantum Cryptography": chapter11.md
 theme:
   name: null
   custom_dir: ../mkdocs-material/material
diff --git a/wolfProvider/src/chapter03.md b/wolfProvider/src/chapter03.md
index aea591e9..0622d158 100644
--- a/wolfProvider/src/chapter03.md
+++ b/wolfProvider/src/chapter03.md
@@ -216,345 +216,7 @@ By default, wolfProvider only builds a shared library, with building of a static
 | --enable-mlkem | **Disabled** | Enable ML-KEM (FIPS 203) only |
 | --enable-mldsa | **Disabled** | Enable ML-DSA (FIPS 204) only |
 | --enable-slhdsa | **Disabled** | Enable SLH-DSA (FIPS 205) only |
-| --enable-lms | **Disabled** | Enable LMS verification only (requires OpenSSL 3.6+) |
+| --enable-lms | **Disabled** | Enable LMS verification only |
 | | | |
 | --with-openssl=DIR |   | OpenSSL installation location to link against. If not set, use the system default library and include paths. |
 | --with-wolfssl=DIR |   | wolfSSL installation location to link against. If not set, use the system default library and include paths. |
-
-## Post-Quantum Cryptography
-
-wolfProvider supports the NIST post-quantum standards through the OpenSSL 3
-EVP interface. PQC support is opt-in so applications that do not need these
-algorithms are unaffected.
-
-### Requirements
-
-- wolfSSL v5.9.2-stable or later
-- OpenSSL 3.6 or later
-- A wolfSSL build with the required PQC algorithms enabled
-
-The packaged Debian build is not currently available with PQC because its
-system OpenSSL is older than OpenSSL 3.6.
-
-### Supported Algorithms
-
-| Algorithm | Standard | Supported Parameter Sets |
-| :-------- | :------- | :----------------------- |
-| ML-KEM | FIPS 203 | ML-KEM-512, ML-KEM-768, ML-KEM-1024 |
-| ML-DSA | FIPS 204 | ML-DSA-44, ML-DSA-65, ML-DSA-87 |
-| SLH-DSA with SHA-2 | FIPS 205 | SLH-DSA-SHA2-128s, SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, SLH-DSA-SHA2-192f, SLH-DSA-SHA2-256s, SLH-DSA-SHA2-256f |
-| SLH-DSA with SHAKE | FIPS 205 | SLH-DSA-SHAKE-128s, SLH-DSA-SHAKE-128f, SLH-DSA-SHAKE-192s, SLH-DSA-SHAKE-192f, SLH-DSA-SHAKE-256s, SLH-DSA-SHAKE-256f |
-| LMS | RFC 8554 / NIST SP 800-208 | LMS and LMOTS public-key verification |
-
-ML-KEM supports key generation, encapsulation, decapsulation, raw key
-import/export, and public/private key encoding. ML-DSA supports key generation,
-pure and pre-hash signing, verification, context strings, and key encoding.
-SLH-DSA supports key generation, pure signing, verification, context strings,
-and key encoding. LMS supports public-key import and one-shot signature
-verification; private-key import, signing, and key generation are not exposed
-because OpenSSL 3.6 provides LMS as a verification-only interface.
-
-### Provider Architecture
-
-Applications use the standard OpenSSL 3 EVP interfaces. wolfProvider registers
-OpenSSL key management implementations for each parameter set, a KEM
-implementation for ML-KEM, and signature implementations for ML-DSA and
-SLH-DSA. The provider translates those operations to the corresponding
-wolfCrypt APIs and keeps the wolfCrypt key object inside the OpenSSL
-`EVP_PKEY`.
-
-| Family | OpenSSL Interfaces | Main Operations |
-| :----- | :----------------- | :-------------- |
-| ML-KEM | `EVP_PKEY`, `EVP_PKEY_CTX`, KEM | Key generation, encapsulation, decapsulation, key import/export |
-| ML-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure and pre-hash sign/verify, key import/export |
-| SLH-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure sign/verify, key import/export |
-| LMS | `EVP_PKEY`, `EVP_MD_CTX`, signature | Public-key import/export and one-shot verification |
-
-Keys support raw public and private key parameters as well as DER and PEM
-encoding. Public keys use SubjectPublicKeyInfo and private keys use PKCS#8.
-Encrypted PKCS#8 private key output is also supported. The signature
-implementations expose the algorithm identifiers needed for X.509 certificate
-and request operations.
-
-### Sizes and Security Categories
-
-ML-KEM always produces a 32-byte shared secret:
-
-| Parameter Set | NIST Category | Public Key | Private Key | Ciphertext |
-| :------------ | :------------ | ---------: | ----------: | ---------: |
-| ML-KEM-512 | 1 | 800 bytes | 1,632 bytes | 768 bytes |
-| ML-KEM-768 | 3 | 1,184 bytes | 2,400 bytes | 1,088 bytes |
-| ML-KEM-1024 | 5 | 1,568 bytes | 3,168 bytes | 1,568 bytes |
-
-ML-DSA signatures and keys have fixed sizes for each parameter set:
-
-| Parameter Set | NIST Category | Public Key | Private Key | Signature |
-| :------------ | :------------ | ---------: | ----------: | --------: |
-| ML-DSA-44 | 2 | 1,312 bytes | 2,560 bytes | 2,420 bytes |
-| ML-DSA-65 | 3 | 1,952 bytes | 4,032 bytes | 3,309 bytes |
-| ML-DSA-87 | 5 | 2,592 bytes | 4,896 bytes | 4,627 bytes |
-
-For SLH-DSA, SHA-2 and SHAKE parameter sets at the same level have the same
-sizes. The `s` variants favor smaller signatures, while the `f` variants favor
-faster signing:
-
-| Parameter Sets | NIST Category | Public Key | Private Key | Signature |
-| :------------- | :------------ | ---------: | ----------: | --------: |
-| 128s | 1 | 32 bytes | 64 bytes | 7,856 bytes |
-| 128f | 1 | 32 bytes | 64 bytes | 17,088 bytes |
-| 192s | 3 | 48 bytes | 96 bytes | 16,224 bytes |
-| 192f | 3 | 48 bytes | 96 bytes | 35,664 bytes |
-| 256s | 5 | 64 bytes | 128 bytes | 29,792 bytes |
-| 256f | 5 | 64 bytes | 128 bytes | 49,856 bytes |
-
-### Signing and Generation Parameters
-
-ML-DSA and SLH-DSA accept the OpenSSL signature context-string parameter, with
-the FIPS 204 and FIPS 205 maximum of 255 bytes. Both support deterministic and
-randomized signing through OpenSSL signature parameters. ML-DSA additionally
-supports HashML-DSA pre-hash signing and external representative input.
-
-The key generation implementations accept the OpenSSL ML-KEM, ML-DSA, and
-SLH-DSA seed parameters. These deterministic paths are used by known-answer
-and ACVP testing. Normal application key generation and randomized signing use
-wolfCrypt's random number generator.
-
-OpenSSL presents one-shot and streaming digest-sign entry points to
-applications. wolfProvider incrementally hashes HashML-DSA input. Pure ML-DSA
-and SLH-DSA require the complete message; SLH-DSA therefore buffers streaming
-input and enforces a 64 MiB message limit.
-
-### Platform Optimizations
-
-wolfProvider calls the native wolfCrypt implementations, so it benefits from
-the optimized code selected by the wolfSSL build without requiring a separate
-provider-specific acceleration layer. Available wolfCrypt PQC speedups include
-x86-64 vectorized implementations and assembly paths for ARM32, AArch64,
-ARMv7-M, and ARMv7E-M. Optimized SHA-3 and SHAKE operations also accelerate
-the Keccak work used by ML-KEM and ML-DSA.
-
-The exact path is compiler, processor, and wolfSSL configuration dependent.
-Applications should use the wolfCrypt benchmark on the target system to
-confirm which implementation was selected and measure the relevant parameter
-sets. See the wolfSSL
-[PQC documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/appendix09.html)
-and [ML-KEM acceleration overview](https://www.wolfssl.com/accelerated-kyber-ml-kem/)
-for configuration and benchmark details.
-
-### Building
-
-The build script can configure OpenSSL, wolfSSL, and wolfProvider together:
-
-```sh
-./scripts/build-wolfprovider.sh --enable-pqc
-```
-
-`--enable-pqc` enables all three algorithm families. Each family can also be
-selected independently:
-
-```sh
-./scripts/build-wolfprovider.sh --enable-mlkem
-./scripts/build-wolfprovider.sh --enable-mldsa
-./scripts/build-wolfprovider.sh --enable-slhdsa
-```
-
-For a manual build, configure wolfSSL with the matching algorithm options,
-then configure wolfProvider:
-
-```sh
-# Add the required options to the normal wolfSSL configuration.
-./configure --enable-mlkem --enable-mldsa --enable-slhdsa
-make
-sudo make install
-
-# Configure wolfProvider against OpenSSL 3.6 or later.
-./configure --enable-pqc \
-    --with-openssl=/path/to/openssl \
-    --with-wolfssl=/path/to/wolfssl
-make
-sudo make install
-```
-
-PQC code is not compiled unless `--enable-pqc` or an individual PQC option is
-passed to wolfProvider, even when wolfSSL has the algorithms enabled.
-
-### Loading the Provider
-
-Set the provider module and configuration paths to the wolfProvider
-installation:
-
-```sh
-export OPENSSL_MODULES=/path/to/wolfprovider/lib
-export OPENSSL_CONF=/path/to/wolfProvider/provider.conf
-```
-
-Confirm that the expected algorithms are provided by `libwolfprov`:
-
-```sh
-openssl list -kem-algorithms -provider libwolfprov
-openssl list -signature-algorithms -provider libwolfprov
-```
-
-### OpenSSL EVP Example
-
-The maintained
-[`examples/pqc_openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/pqc_openssl_example.c)
-program demonstrates all three algorithm families through the OpenSSL EVP API:
-
-- ML-KEM-768 key generation, encapsulation, and decapsulation
-- ML-DSA-65 key generation, signing, and verification
-- SLH-DSA-SHA2-128f key generation, signing, and verification
-
-The example is built and run by `make check` when wolfProvider is configured
-with any PQC family. Compile-time guards run only the enabled families, so the
-same source also demonstrates ML-KEM-only, ML-DSA-only, and SLH-DSA-only
-builds. After building, it can also be run directly from the wolfProvider root:
-
-```sh
-./examples/pqc_openssl_example
-```
-
-The companion
-[`examples/openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/openssl_example.c)
-shows basic provider loading, build information, and self-test handling.
-
-ML-DSA supports pure ML-DSA and HashML-DSA through OpenSSL's digest-sign
-interface. SLH-DSA is a pure signature algorithm and does not accept a
-separate digest name. Its streaming interface buffers the complete message
-and limits it to 64 MiB.
-
-### Build Macros
-
-The configure options add the corresponding request macros:
-
-| Configure Option | wolfProvider Request Macro | wolfSSL Capability Macro |
-| :--------------- | :------------------------- | :----------------------- |
-| `--enable-mlkem` | `WOLFPROV_HAVE_MLKEM` | `WOLFSSL_HAVE_MLKEM` |
-| `--enable-mldsa` | `WOLFPROV_HAVE_MLDSA` | `WOLFSSL_HAVE_MLDSA` |
-| `--enable-slhdsa` | `WOLFPROV_HAVE_SLHDSA` | `WOLFSSL_HAVE_SLHDSA` |
-| `--enable-lms` | `WOLFPROV_HAVE_LMS` | `WOLFSSL_HAVE_LMS` |
-
-`--enable-pqc` enables ML-KEM and ML-DSA. SLH-DSA and LMS are enabled separately
-with `--enable-slhdsa` and `--enable-lms`. After configuration validates the wolfSSL capabilities,
-wolfProvider uses `WP_HAVE_MLKEM`, `WP_HAVE_MLDSA`, `WP_HAVE_SLHDSA`, and
-`WP_HAVE_LMS` internally to compile and register the available implementations.
-
-### TLS 1.3
-
-wolfProvider advertises these ML-KEM TLS groups:
-
-- MLKEM512
-- MLKEM768
-- MLKEM1024
-- X25519MLKEM768
-- SecP256r1MLKEM768
-- SecP384r1MLKEM1024
-
-It also advertises the `mldsa44`, `mldsa65`, and `mldsa87` TLS 1.3 signature
-schemes. SLH-DSA is supported through EVP but is not advertised as a TLS
-signature scheme.
-
-### Validation
-
-The wolfCrypt Post Quantum v7.0.0 implementation has NIST CAVP algorithm
-validation under
-[certificate A8437](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/details?validation=41047).
-The certificate covers LMS signature verification; ML-KEM key generation,
-encapsulation, and
-decapsulation; ML-DSA key generation, signature generation, and signature
-verification; and SLH-DSA key generation, signature generation, and signature
-verification. It also covers the prerequisite SHA, SHAKE, HMAC, and DRBG
-implementations identified by the NIST record.
-
-This validation applies to the identified wolfCrypt version and operating
-environment. A wolfProvider application must use the corresponding validated
-wolfCrypt distribution and follow its security policy when a validated
-deployment is required.
-
-CAVP validates the algorithm implementations. It is distinct from validation
-of a complete cryptographic module under FIPS 140-3, so using an open source or
-FIPS-ready wolfSSL build does not by itself create a FIPS-validated
-application.
-
-PQC has several independent test layers:
-
-- Unit and example tests cover key generation, import/export, encoding,
-  encapsulation, decapsulation, signing, verification, malformed inputs, and
-  X.509 operations where applicable.
-- OpenSSL EVP known-answer tests run the ML-KEM, ML-DSA, SLH-DSA, and LMS vector
-  files against wolfProvider. The LMS vector contains 320 verification cases.
-- The PQC interoperability test compares wolfProvider with OpenSSL's default
-  provider and the direct wolfSSL APIs. It also tests ML-KEM and hybrid TLS
-  groups plus ML-DSA certificate authentication.
-- The nginx OSP workflow tests ML-KEM and hybrid TLS 1.3 key exchange with
-  ML-DSA authentication.
-- The pinned libacvp OSP workflow runs its complete unit suite and exercises
-  its OpenSSL ACVP handlers for ML-KEM, ML-DSA, and SLH-DSA.
-
-The version, nginx, and libacvp matrices cover wolfSSL master and the latest
-eligible stable release. OSP tests run in replace-default and non-replace
-modes, with normal and forced-failure cases. PQC KAT and version coverage runs
-for pull requests, while the longer OSP integration workflows are
-label-selected and run nightly.
-
-## Build Defines
-
-wolfProvider exposes several preprocessor defines that allow users to configure how wolfProvider is built. These are described in the table below.
-
-| Define                           | Description |
-| :------------------------------- | :----------------------------- |
-| WOLFPROVIDER_USER_SETTINGS | Read user-specified defines from user_settings.h. |
-| WOLFPROV_DEBUG | Output debug information |
-| WP_CHECK_FORCE_FAIL | Force failure checking for testing purposes |
-| WP_ALLOW_NON_FIPS | Allow certain non-FIPS algorithms in FIPS mode |
-| WP_HAVE_AESCCM | AES encryption in CCM (Counter with CBC-MAC) mode |
-| WP_HAVE_AESCFB | AES encryption in CFB (Cipher Feedback) mode |
-| WP_HAVE_AESCBC | AES encryption in CBC (Cipher Block Chaining) mode |
-| WP_HAVE_AESCTR | AES encryption in CTR (Counter) mode |
-| WP_HAVE_AESCTS | AES encryption in CTS (Ciphertext Stealing) mode |
-| WP_HAVE_AESECB | AES encryption in ECB (Electronic Codebook) mode |
-| WP_HAVE_AESGCM | AES encryption in GCM (Galois/Counter Mode) mode |
-| WP_HAVE_CMAC | CMAC (Cipher-based Message Authentication Code) support |
-| WP_HAVE_DES3CBC | Triple DES encryption in CBC mode |
-| WP_HAVE_DH | Diffie-Hellman key exchange support |
-| WP_HAVE_DIGEST | General digest/hash algorithm support |
-| WP_HAVE_ECC | General Elliptic Curve Cryptography support |
-| WP_HAVE_EC_P192 | P-192 elliptic curve support |
-| WP_HAVE_EC_P224 | P-224 elliptic curve support |
-| WP_HAVE_EC_P256 | P-256 elliptic curve support |
-| WP_HAVE_EC_P384 | P-384 elliptic curve support |
-| WP_HAVE_EC_P521 | P-521 elliptic curve support |
-| WP_HAVE_ECDH | ECDH (Elliptic Curve Diffie-Hellman) key exchange support |
-| WP_HAVE_ECDSA | ECDSA (Elliptic Curve Digital Signature Algorithm) support |
-| WP_HAVE_ECKEYGEN | Elliptic curve key generation support |
-| WP_HAVE_ED25519 | Ed25519 elliptic curve signature support |
-| WP_HAVE_ED448 | Ed448 elliptic curve signature support |
-| WP_HAVE_GMAC | GMAC (Galois/Counter Mode Authentication) support |
-| WP_HAVE_HKDF | HKDF (HMAC-based Key Derivation Function) support |
-| WP_HAVE_HMAC | HMAC (Hash-based Message Authentication Code) support |
-| WP_HAVE_KRB5KDF | Kerberos 5 Key Derivation Function support |
-| WP_HAVE_MD5 | MD5 hash algorithm support |
-| WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support |
-| WP_HAVE_MLDSA | ML-DSA (FIPS 204) post-quantum signature support |
-| WP_HAVE_MLKEM | ML-KEM (FIPS 203) post-quantum key encapsulation support |
-| WP_HAVE_PBE | Password-Based Encryption support |
-| WP_HAVE_RANDOM | Random number generation support |
-| WP_HAVE_RSA | RSA encryption and signature support |
-| WP_HAVE_SHA1 | SHA1 hash algorithm support |
-| WP_HAVE_SHA224 | SHA224 hash algorithm support |
-| WP_HAVE_SHA256 | SHA256 hash algorithm support |
-| WP_HAVE_SHA384 | SHA384 hash algorithm support |
-| WP_HAVE_SHA3 | SHA3 family hash algorithm support |
-| WP_HAVE_SHA3_224 | SHA3-224 hash algorithm support |
-| WP_HAVE_SHA3_256 | SHA3-256 hash algorithm support |
-| WP_HAVE_SHA3_384 | SHA3-384 hash algorithm support |
-| WP_HAVE_SHA3_512 | SHA3-512 hash algorithm support |
-| WP_HAVE_SHA512 | SHA512 hash algorithm support |
-| WP_HAVE_SHA512_224 | SHA512/224 hash algorithm support |
-| WP_HAVE_SHA512_256 | SHA512/256 hash algorithm support |
-| WP_HAVE_SHAKE_256 | SHAKE256 extendable output function support |
-| WP_HAVE_SLHDSA | SLH-DSA (FIPS 205) post-quantum signature support |
-| WP_HAVE_TLS1_PRF | TLS1 Pseudo-Random Function support |
-| WP_HAVE_X25519 | X25519 elliptic curve support |
-| WP_HAVE_X448 | X448 elliptic curve support |
-| WP_RSA_PSS_ENCODING | RSA-PSS (Probabilistic Signature Scheme) encoding support |
diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md
new file mode 100644
index 00000000..8c7696d7
--- /dev/null
+++ b/wolfProvider/src/chapter11.md
@@ -0,0 +1,340 @@
+# Post-Quantum Cryptography
+
+
+## Post-Quantum Cryptography
+
+wolfProvider supports the NIST post-quantum standards through the OpenSSL 3
+EVP interface. PQC support is opt-in so applications that do not need these
+algorithms are unaffected.
+
+### Requirements
+
+- wolfSSL v5.9.2-stable or later
+- OpenSSL 3.6 or later
+- A wolfSSL build with the required PQC algorithms enabled
+
+The packaged Debian build is not currently available with PQC because its
+system OpenSSL is older than OpenSSL 3.6.
+
+### Supported Algorithms
+
+| Algorithm | Standard | Supported Parameter Sets |
+| :-------- | :------- | :----------------------- |
+| ML-KEM | FIPS 203 | ML-KEM-512, ML-KEM-768, ML-KEM-1024 |
+| ML-DSA | FIPS 204 | ML-DSA-44, ML-DSA-65, ML-DSA-87 |
+| SLH-DSA with SHA-2 | FIPS 205 | SLH-DSA-SHA2-128s, SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, SLH-DSA-SHA2-192f, SLH-DSA-SHA2-256s, SLH-DSA-SHA2-256f |
+| SLH-DSA with SHAKE | FIPS 205 | SLH-DSA-SHAKE-128s, SLH-DSA-SHAKE-128f, SLH-DSA-SHAKE-192s, SLH-DSA-SHAKE-192f, SLH-DSA-SHAKE-256s, SLH-DSA-SHAKE-256f |
+| LMS | RFC 8554 / NIST SP 800-208 | LMS and LMOTS public-key verification |
+
+ML-KEM supports key generation, encapsulation, decapsulation, raw key
+import/export, and public/private key encoding. ML-DSA supports key generation,
+pure and pre-hash signing, verification, context strings, and key encoding.
+SLH-DSA supports key generation, pure signing, verification, context strings,
+and key encoding. LMS supports public-key import and one-shot signature
+verification; private-key import, signing, and key generation are not exposed
+because OpenSSL 3.6 provides LMS as a verification-only interface.
+
+### Provider Architecture
+
+Applications use the standard OpenSSL 3 EVP interfaces. wolfProvider registers
+OpenSSL key management implementations for each parameter set, a KEM
+implementation for ML-KEM, and signature implementations for ML-DSA and
+SLH-DSA. The provider translates those operations to the corresponding
+wolfCrypt APIs and keeps the wolfCrypt key object inside the OpenSSL
+`EVP_PKEY`.
+
+| Family | OpenSSL Interfaces | Main Operations |
+| :----- | :----------------- | :-------------- |
+| ML-KEM | `EVP_PKEY`, `EVP_PKEY_CTX`, KEM | Key generation, encapsulation, decapsulation, key import/export |
+| ML-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure and pre-hash sign/verify, key import/export |
+| SLH-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure sign/verify, key import/export |
+| LMS | `EVP_PKEY`, `EVP_MD_CTX`, signature | Public-key import/export and one-shot verification |
+
+Keys support raw public and private key parameters as well as DER and PEM
+encoding. Public keys use SubjectPublicKeyInfo and private keys use PKCS#8.
+Encrypted PKCS#8 private key output is also supported. The signature
+implementations expose the algorithm identifiers needed for X.509 certificate
+and request operations.
+
+### Sizes and Security Categories
+
+ML-KEM always produces a 32-byte shared secret:
+
+| Parameter Set | NIST Category | Public Key | Private Key | Ciphertext |
+| :------------ | :------------ | ---------: | ----------: | ---------: |
+| ML-KEM-512 | 1 | 800 bytes | 1,632 bytes | 768 bytes |
+| ML-KEM-768 | 3 | 1,184 bytes | 2,400 bytes | 1,088 bytes |
+| ML-KEM-1024 | 5 | 1,568 bytes | 3,168 bytes | 1,568 bytes |
+
+ML-DSA signatures and keys have fixed sizes for each parameter set:
+
+| Parameter Set | NIST Category | Public Key | Private Key | Signature |
+| :------------ | :------------ | ---------: | ----------: | --------: |
+| ML-DSA-44 | 2 | 1,312 bytes | 2,560 bytes | 2,420 bytes |
+| ML-DSA-65 | 3 | 1,952 bytes | 4,032 bytes | 3,309 bytes |
+| ML-DSA-87 | 5 | 2,592 bytes | 4,896 bytes | 4,627 bytes |
+
+For SLH-DSA, SHA-2 and SHAKE parameter sets at the same level have the same
+sizes. The `s` variants favor smaller signatures, while the `f` variants favor
+faster signing:
+
+| Parameter Sets | NIST Category | Public Key | Private Key | Signature |
+| :------------- | :------------ | ---------: | ----------: | --------: |
+| 128s | 1 | 32 bytes | 64 bytes | 7,856 bytes |
+| 128f | 1 | 32 bytes | 64 bytes | 17,088 bytes |
+| 192s | 3 | 48 bytes | 96 bytes | 16,224 bytes |
+| 192f | 3 | 48 bytes | 96 bytes | 35,664 bytes |
+| 256s | 5 | 64 bytes | 128 bytes | 29,792 bytes |
+| 256f | 5 | 64 bytes | 128 bytes | 49,856 bytes |
+
+### Signing and Generation Parameters
+
+ML-DSA and SLH-DSA accept the OpenSSL signature context-string parameter, with
+the FIPS 204 and FIPS 205 maximum of 255 bytes. Both support deterministic and
+randomized signing through OpenSSL signature parameters. ML-DSA additionally
+supports HashML-DSA pre-hash signing and external representative input.
+
+The key generation implementations accept the OpenSSL ML-KEM, ML-DSA, and
+SLH-DSA seed parameters. These deterministic paths are used by known-answer
+and ACVP testing. Normal application key generation and randomized signing use
+wolfCrypt's random number generator.
+
+OpenSSL presents one-shot and streaming digest-sign entry points to
+applications. wolfProvider incrementally hashes HashML-DSA input. Pure ML-DSA
+and SLH-DSA require the complete message; SLH-DSA therefore buffers streaming
+input and enforces a 64 MiB message limit.
+
+### Platform Optimizations
+
+wolfProvider calls the native wolfCrypt implementations, so it benefits from
+the optimized code selected by the wolfSSL build without requiring a separate
+provider-specific acceleration layer. Available wolfCrypt PQC speedups include
+x86-64 vectorized implementations and assembly paths for ARM32, AArch64,
+ARMv7-M, and ARMv7E-M. Optimized SHA-3 and SHAKE operations also accelerate
+the Keccak work used by ML-KEM and ML-DSA.
+
+The exact path is compiler, processor, and wolfSSL configuration dependent.
+Applications should use the wolfCrypt benchmark on the target system to
+confirm which implementation was selected and measure the relevant parameter
+sets. See the wolfSSL
+[PQC documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/appendix09.html)
+and [ML-KEM acceleration overview](https://www.wolfssl.com/accelerated-kyber-ml-kem/)
+for configuration and benchmark details.
+
+### Building
+
+The build script can configure OpenSSL, wolfSSL, and wolfProvider together:
+
+```sh
+./scripts/build-wolfprovider.sh --enable-pqc
+```
+
+`--enable-pqc` enables all three algorithm families. Each family can also be
+selected independently:
+
+```sh
+./scripts/build-wolfprovider.sh --enable-mlkem
+./scripts/build-wolfprovider.sh --enable-mldsa
+./scripts/build-wolfprovider.sh --enable-slhdsa
+```
+
+For a manual build, configure wolfSSL with the matching algorithm options,
+then configure wolfProvider:
+
+```sh
+# Add the required options to the normal wolfSSL configuration.
+./configure --enable-mlkem --enable-mldsa --enable-slhdsa
+make
+sudo make install
+
+# Configure wolfProvider against OpenSSL 3.6 or later.
+./configure --enable-pqc \
+    --with-openssl=/path/to/openssl \
+    --with-wolfssl=/path/to/wolfssl
+make
+sudo make install
+```
+
+PQC code is not compiled unless `--enable-pqc` or an individual PQC option is
+passed to wolfProvider, even when wolfSSL has the algorithms enabled.
+
+### Loading the Provider
+
+Set the provider module and configuration paths to the wolfProvider
+installation:
+
+```sh
+export OPENSSL_MODULES=/path/to/wolfprovider/lib
+export OPENSSL_CONF=/path/to/wolfProvider/provider.conf
+```
+
+Confirm that the expected algorithms are provided by `libwolfprov`:
+
+```sh
+openssl list -kem-algorithms -provider libwolfprov
+openssl list -signature-algorithms -provider libwolfprov
+```
+
+### OpenSSL EVP Example
+
+The maintained
+[`examples/pqc_openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/pqc_openssl_example.c)
+program demonstrates all three algorithm families through the OpenSSL EVP API:
+
+- ML-KEM-768 key generation, encapsulation, and decapsulation
+- ML-DSA-65 key generation, signing, and verification
+- SLH-DSA-SHA2-128f key generation, signing, and verification
+
+The example is built and run by `make check` when wolfProvider is configured
+with any PQC family. Compile-time guards run only the enabled families, so the
+same source also demonstrates ML-KEM-only, ML-DSA-only, and SLH-DSA-only
+builds. After building, it can also be run directly from the wolfProvider root:
+
+```sh
+./examples/pqc_openssl_example
+```
+
+The companion
+[`examples/openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/openssl_example.c)
+shows basic provider loading, build information, and self-test handling.
+
+ML-DSA supports pure ML-DSA and HashML-DSA through OpenSSL's digest-sign
+interface. SLH-DSA is a pure signature algorithm and does not accept a
+separate digest name. Its streaming interface buffers the complete message
+and limits it to 64 MiB.
+
+### Build Macros
+
+The configure options add the corresponding request macros:
+
+| Configure Option | wolfProvider Request Macro | wolfSSL Capability Macro |
+| :--------------- | :------------------------- | :----------------------- |
+| `--enable-mlkem` | `WOLFPROV_HAVE_MLKEM` | `WOLFSSL_HAVE_MLKEM` |
+| `--enable-mldsa` | `WOLFPROV_HAVE_MLDSA` | `WOLFSSL_HAVE_MLDSA` |
+| `--enable-slhdsa` | `WOLFPROV_HAVE_SLHDSA` | `WOLFSSL_HAVE_SLHDSA` |
+| `--enable-lms` | `WOLFPROV_HAVE_LMS` | `WOLFSSL_HAVE_LMS` |
+
+`--enable-pqc` enables ML-KEM and ML-DSA. SLH-DSA and LMS are enabled separately
+with `--enable-slhdsa` and `--enable-lms`. After configuration validates the wolfSSL capabilities,
+wolfProvider uses `WP_HAVE_MLKEM`, `WP_HAVE_MLDSA`, `WP_HAVE_SLHDSA`, and
+`WP_HAVE_LMS` internally to compile and register the available implementations.
+
+### TLS 1.3
+
+wolfProvider advertises these ML-KEM TLS groups:
+
+- MLKEM512
+- MLKEM768
+- MLKEM1024
+- X25519MLKEM768
+- SecP256r1MLKEM768
+- SecP384r1MLKEM1024
+
+It also advertises the `mldsa44`, `mldsa65`, and `mldsa87` TLS 1.3 signature
+schemes. SLH-DSA is supported through EVP but is not advertised as a TLS
+signature scheme.
+
+### Validation
+
+The wolfCrypt Post Quantum v7.0.0 implementation has NIST CAVP algorithm
+validation under
+[certificate A8437](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/details?validation=41047).
+The certificate covers LMS signature verification; ML-KEM key generation,
+encapsulation, and
+decapsulation; ML-DSA key generation, signature generation, and signature
+verification; and SLH-DSA key generation, signature generation, and signature
+verification. It also covers the prerequisite SHA, SHAKE, HMAC, and DRBG
+implementations identified by the NIST record.
+
+This validation applies to the identified wolfCrypt version and operating
+environment. A wolfProvider application must use the corresponding validated
+wolfCrypt distribution and follow its security policy when a validated
+deployment is required.
+
+CAVP validates the algorithm implementations. It is distinct from validation
+of a complete cryptographic module under FIPS 140-3, so using an open source or
+FIPS-ready wolfSSL build does not by itself create a FIPS-validated
+application.
+
+PQC has several independent test layers:
+
+- Unit and example tests cover key generation, import/export, encoding,
+  encapsulation, decapsulation, signing, verification, malformed inputs, and
+  X.509 operations where applicable.
+- OpenSSL EVP known-answer tests run the ML-KEM, ML-DSA, SLH-DSA, and LMS vector
+  files against wolfProvider. The LMS vector contains 320 verification cases.
+- The PQC interoperability test compares wolfProvider with OpenSSL's default
+  provider and the direct wolfSSL APIs. It also tests ML-KEM and hybrid TLS
+  groups plus ML-DSA certificate authentication.
+- The nginx OSP workflow tests ML-KEM and hybrid TLS 1.3 key exchange with
+  ML-DSA authentication.
+- The pinned libacvp OSP workflow runs its complete unit suite and exercises
+  its OpenSSL ACVP handlers for ML-KEM, ML-DSA, and SLH-DSA.
+
+The version, nginx, and libacvp matrices cover wolfSSL master and the latest
+eligible stable release. OSP tests run in replace-default and non-replace
+modes, with normal and forced-failure cases. PQC KAT and version coverage runs
+for pull requests, while the longer OSP integration workflows are
+label-selected and run nightly.
+
+## Build Defines
+
+wolfProvider exposes several preprocessor defines that allow users to configure how wolfProvider is built. These are described in the table below.
+
+| Define                           | Description |
+| :------------------------------- | :----------------------------- |
+| WOLFPROVIDER_USER_SETTINGS | Read user-specified defines from user_settings.h. |
+| WOLFPROV_DEBUG | Output debug information |
+| WP_CHECK_FORCE_FAIL | Force failure checking for testing purposes |
+| WP_ALLOW_NON_FIPS | Allow certain non-FIPS algorithms in FIPS mode |
+| WP_HAVE_AESCCM | AES encryption in CCM (Counter with CBC-MAC) mode |
+| WP_HAVE_AESCFB | AES encryption in CFB (Cipher Feedback) mode |
+| WP_HAVE_AESCBC | AES encryption in CBC (Cipher Block Chaining) mode |
+| WP_HAVE_AESCTR | AES encryption in CTR (Counter) mode |
+| WP_HAVE_AESCTS | AES encryption in CTS (Ciphertext Stealing) mode |
+| WP_HAVE_AESECB | AES encryption in ECB (Electronic Codebook) mode |
+| WP_HAVE_AESGCM | AES encryption in GCM (Galois/Counter Mode) mode |
+| WP_HAVE_CMAC | CMAC (Cipher-based Message Authentication Code) support |
+| WP_HAVE_DES3CBC | Triple DES encryption in CBC mode |
+| WP_HAVE_DH | Diffie-Hellman key exchange support |
+| WP_HAVE_DIGEST | General digest/hash algorithm support |
+| WP_HAVE_ECC | General Elliptic Curve Cryptography support |
+| WP_HAVE_EC_P192 | P-192 elliptic curve support |
+| WP_HAVE_EC_P224 | P-224 elliptic curve support |
+| WP_HAVE_EC_P256 | P-256 elliptic curve support |
+| WP_HAVE_EC_P384 | P-384 elliptic curve support |
+| WP_HAVE_EC_P521 | P-521 elliptic curve support |
+| WP_HAVE_ECDH | ECDH (Elliptic Curve Diffie-Hellman) key exchange support |
+| WP_HAVE_ECDSA | ECDSA (Elliptic Curve Digital Signature Algorithm) support |
+| WP_HAVE_ECKEYGEN | Elliptic curve key generation support |
+| WP_HAVE_ED25519 | Ed25519 elliptic curve signature support |
+| WP_HAVE_ED448 | Ed448 elliptic curve signature support |
+| WP_HAVE_GMAC | GMAC (Galois/Counter Mode Authentication) support |
+| WP_HAVE_HKDF | HKDF (HMAC-based Key Derivation Function) support |
+| WP_HAVE_HMAC | HMAC (Hash-based Message Authentication Code) support |
+| WP_HAVE_KRB5KDF | Kerberos 5 Key Derivation Function support |
+| WP_HAVE_MD5 | MD5 hash algorithm support |
+| WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support |
+| WP_HAVE_MLDSA | ML-DSA (FIPS 204) post-quantum signature support |
+| WP_HAVE_MLKEM | ML-KEM (FIPS 203) post-quantum key encapsulation support |
+| WP_HAVE_PBE | Password-Based Encryption support |
+| WP_HAVE_RANDOM | Random number generation support |
+| WP_HAVE_RSA | RSA encryption and signature support |
+| WP_HAVE_SHA1 | SHA1 hash algorithm support |
+| WP_HAVE_SHA224 | SHA224 hash algorithm support |
+| WP_HAVE_SHA256 | SHA256 hash algorithm support |
+| WP_HAVE_SHA384 | SHA384 hash algorithm support |
+| WP_HAVE_SHA3 | SHA3 family hash algorithm support |
+| WP_HAVE_SHA3_224 | SHA3-224 hash algorithm support |
+| WP_HAVE_SHA3_256 | SHA3-256 hash algorithm support |
+| WP_HAVE_SHA3_384 | SHA3-384 hash algorithm support |
+| WP_HAVE_SHA3_512 | SHA3-512 hash algorithm support |
+| WP_HAVE_SHA512 | SHA512 hash algorithm support |
+| WP_HAVE_SHA512_224 | SHA512/224 hash algorithm support |
+| WP_HAVE_SHA512_256 | SHA512/256 hash algorithm support |
+| WP_HAVE_SHAKE_256 | SHAKE256 extendable output function support |
+| WP_HAVE_SLHDSA | SLH-DSA (FIPS 205) post-quantum signature support |
+| WP_HAVE_TLS1_PRF | TLS1 Pseudo-Random Function support |
+| WP_HAVE_X25519 | X25519 elliptic curve support |
+| WP_HAVE_X448 | X448 elliptic curve support |
+| WP_RSA_PSS_ENCODING | RSA-PSS (Probabilistic Signature Scheme) encoding support |

From 87dc1c0e86203ad1228d3c9aaa0e8ff7ca985181 Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Fri, 31 Jul 2026 15:13:29 -0700
Subject: [PATCH 4/9] Document replace-default PQC deployment

---
 wolfProvider/src/chapter11.md | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md
index 8c7696d7..8abb78c5 100644
--- a/wolfProvider/src/chapter11.md
+++ b/wolfProvider/src/chapter11.md
@@ -1,6 +1,5 @@
 # Post-Quantum Cryptography
 
-
 ## Post-Quantum Cryptography
 
 wolfProvider supports the NIST post-quantum standards through the OpenSSL 3
@@ -143,12 +142,12 @@ then configure wolfProvider:
 
 ```sh
 # Add the required options to the normal wolfSSL configuration.
-./configure --enable-mlkem --enable-mldsa --enable-slhdsa
+./configure --enable-mlkem --enable-mldsa --enable-slhdsa --enable-lms
 make
 sudo make install
 
 # Configure wolfProvider against OpenSSL 3.6 or later.
-./configure --enable-pqc \
+./configure --enable-pqc --enable-slhdsa --enable-lms \
     --with-openssl=/path/to/openssl \
     --with-wolfssl=/path/to/wolfssl
 make
@@ -158,10 +157,24 @@ sudo make install
 PQC code is not compiled unless `--enable-pqc` or an individual PQC option is
 passed to wolfProvider, even when wolfSSL has the algorithms enabled.
 
-### Loading the Provider
+### Using wolfProvider
+
+For production deployments, the recommended configuration is replace-default
+mode. It makes wolfProvider the OpenSSL default and prevents operations from
+silently falling back to OpenSSL's built-in provider:
+
+```sh
+./scripts/build-wolfprovider.sh --replace-default \
+    --enable-pqc --enable-slhdsa --enable-lms
+```
+
+Applications may also load wolfProvider as a normal provider. This mode is
+useful for interoperability and migration, but it does not guarantee that
+every operation is handled by wolfProvider: OpenSSL can select its default
+provider when wolfProvider does not implement an operation or when the
+configuration is not applied.
 
-Set the provider module and configuration paths to the wolfProvider
-installation:
+Set the provider module and configuration paths for this optional mode:
 
 ```sh
 export OPENSSL_MODULES=/path/to/wolfprovider/lib

From 4398515ebb60faba499691d6b3611c8b218ac497 Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Fri, 31 Jul 2026 15:14:57 -0700
Subject: [PATCH 5/9] Link current wolfProvider PQC references

---
 wolfProvider/src/chapter11.md | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md
index 8abb78c5..638f8d80 100644
--- a/wolfProvider/src/chapter11.md
+++ b/wolfProvider/src/chapter11.md
@@ -207,15 +207,6 @@ builds. After building, it can also be run directly from the wolfProvider root:
 ./examples/pqc_openssl_example
 ```
 
-The companion
-[`examples/openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/openssl_example.c)
-shows basic provider loading, build information, and self-test handling.
-
-ML-DSA supports pure ML-DSA and HashML-DSA through OpenSSL's digest-sign
-interface. SLH-DSA is a pure signature algorithm and does not accept a
-separate digest name. Its streaming interface buffers the complete message
-and limits it to 64 MiB.
-
 ### Build Macros
 
 The configure options add the corresponding request macros:
@@ -290,6 +281,24 @@ modes, with normal and forced-failure cases. PQC KAT and version coverage runs
 for pull requests, while the longer OSP integration workflows are
 label-selected and run nightly.
 
+## Further Reading
+
+For the current deployment model and complete build guidance, see the
+[wolfProvider README](https://github.com/wolfSSL/wolfProvider/blob/master/README.md)
+and the [wolfProvider Integration Guide](https://github.com/wolfSSL/wolfProvider/blob/master/docs/INTEGRATION_GUIDE.md).
+The integration guide covers replace-default builds, provider configuration,
+testing, and troubleshooting. For validated deployments, use the
+[FIPS Integration Guide](https://github.com/wolfSSL/wolfProvider/blob/master/docs/FIPS_INTEGRATION_GUIDE.md),
+which explains the replace-default requirements and security-policy considerations.
+
+The repository's
+[replace-default build workflow](https://github.com/wolfSSL/wolfProvider/blob/master/scripts/build-wolfprovider.sh),
+[provider configuration](https://github.com/wolfSSL/wolfProvider/blob/master/provider.conf),
+[PQC EVP example](https://github.com/wolfSSL/wolfProvider/blob/master/examples/pqc_openssl_example.c),
+and [PQC KAT runner](https://github.com/wolfSSL/wolfProvider/blob/master/scripts/test-pqc-kat.sh)
+are maintained alongside the implementation and provide the most current
+examples of supported options and validation.
+
 ## Build Defines
 
 wolfProvider exposes several preprocessor defines that allow users to configure how wolfProvider is built. These are described in the table below.

From 2d9a9e199a6faef51bb23cdee92df55f6c765c73 Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Fri, 31 Jul 2026 15:21:51 -0700
Subject: [PATCH 6/9] Clarify standard provider loading

---
 wolfProvider/src/chapter11.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md
index 638f8d80..9e6a5913 100644
--- a/wolfProvider/src/chapter11.md
+++ b/wolfProvider/src/chapter11.md
@@ -174,18 +174,30 @@ every operation is handled by wolfProvider: OpenSSL can select its default
 provider when wolfProvider does not implement an operation or when the
 configuration is not applied.
 
-Set the provider module and configuration paths for this optional mode:
+Use the repository's provider configuration to load wolfProvider. The
+configuration activates `libwolfprov`; point `OPENSSL_CONF` at that file:
 
 ```sh
-export OPENSSL_MODULES=/path/to/wolfprovider/lib
 export OPENSSL_CONF=/path/to/wolfProvider/provider.conf
 ```
 
-Confirm that the expected algorithms are provided by `libwolfprov`:
+If wolfProvider was installed outside OpenSSL's module search path, also set
+`OPENSSL_MODULES` to the directory containing `libwolfprov.so`:
+
+```sh
+export OPENSSL_MODULES=/path/to/wolfprovider/lib
+```
+
+Run commands with the configuration active. This verifies the algorithms
+advertised by the configured provider; it does not guarantee that unrelated
+operations cannot be selected from OpenSSL's default provider in standard
+provider mode:
 
 ```sh
-openssl list -kem-algorithms -provider libwolfprov
-openssl list -signature-algorithms -provider libwolfprov
+OPENSSL_CONF=/path/to/wolfProvider/provider.conf \
+    openssl list -kem-algorithms
+OPENSSL_CONF=/path/to/wolfProvider/provider.conf \
+    openssl list -signature-algorithms
 ```
 
 ### OpenSSL EVP Example

From 7934bd4fcfa4a01e0f31be6e71d81589e32fe6f3 Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Tue, 4 Aug 2026 16:27:42 -0700
Subject: [PATCH 7/9] Document wolfProvider LMS support

---
 wolfProvider/Makefile         |  3 +-
 wolfProvider/src/chapter11.md | 73 ++++++++++++++++++++++-------------
 2 files changed, 48 insertions(+), 28 deletions(-)

diff --git a/wolfProvider/Makefile b/wolfProvider/Makefile
index 0f47fc5b..0bc8ecf5 100644
--- a/wolfProvider/Makefile
+++ b/wolfProvider/Makefile
@@ -12,7 +12,8 @@ SOURCES = chapter01.md \
 		  chapter07.md \
 		  chapter08.md \
 		  chapter09.md \
-		  chapter10.md
+		  chapter10.md \
+		  chapter11.md
 
 ifeq ($(DOC_LANG),JA)
 	PDF = wolfProvider-Manual-jp.pdf
diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md
index 9e6a5913..12694cf7 100644
--- a/wolfProvider/src/chapter11.md
+++ b/wolfProvider/src/chapter11.md
@@ -1,12 +1,10 @@
 # Post-Quantum Cryptography
 
-## Post-Quantum Cryptography
-
 wolfProvider supports the NIST post-quantum standards through the OpenSSL 3
 EVP interface. PQC support is opt-in so applications that do not need these
 algorithms are unaffected.
 
-### Requirements
+## Requirements
 
 - wolfSSL v5.9.2-stable or later
 - OpenSSL 3.6 or later
@@ -15,7 +13,7 @@ algorithms are unaffected.
 The packaged Debian build is not currently available with PQC because its
 system OpenSSL is older than OpenSSL 3.6.
 
-### Supported Algorithms
+## Supported Algorithms
 
 | Algorithm | Standard | Supported Parameter Sets |
 | :-------- | :------- | :----------------------- |
@@ -31,9 +29,11 @@ pure and pre-hash signing, verification, context strings, and key encoding.
 SLH-DSA supports key generation, pure signing, verification, context strings,
 and key encoding. LMS supports public-key import and one-shot signature
 verification; private-key import, signing, and key generation are not exposed
-because OpenSSL 3.6 provides LMS as a verification-only interface.
+because OpenSSL 3.6 provides LMS as a verification-only interface. This also
+avoids exposing stateful private-key operations through an interface that
+cannot enforce LMS leaf-use state.
 
-### Provider Architecture
+## Provider Architecture
 
 Applications use the standard OpenSSL 3 EVP interfaces. wolfProvider registers
 OpenSSL key management implementations for each parameter set, a KEM
@@ -49,13 +49,20 @@ wolfCrypt APIs and keeps the wolfCrypt key object inside the OpenSSL
 | SLH-DSA | `EVP_PKEY`, `EVP_MD_CTX`, signature | Key generation, pure sign/verify, key import/export |
 | LMS | `EVP_PKEY`, `EVP_MD_CTX`, signature | Public-key import/export and one-shot verification |
 
-Keys support raw public and private key parameters as well as DER and PEM
-encoding. Public keys use SubjectPublicKeyInfo and private keys use PKCS#8.
-Encrypted PKCS#8 private key output is also supported. The signature
-implementations expose the algorithm identifiers needed for X.509 certificate
-and request operations.
+ML-KEM, ML-DSA, and SLH-DSA keys support raw public and private key parameters
+as well as DER and PEM encoding. Public keys use SubjectPublicKeyInfo and
+private keys use PKCS#8. Encrypted PKCS#8 private key output is also supported.
+The signature implementations expose the algorithm identifiers needed for
+X.509 certificate and request operations. LMS instead uses OpenSSL's raw XDR
+public-key representation and exposes no private key.
+
+OpenSSL's LMS provider contract represents one LMS tree rather than a general
+multi-level HSS hierarchy. Its raw public keys and signatures omit the
+four-byte HSS level-count field. wolfProvider adds the required single-level
+HSS wrapper only when calling wolfCrypt and removes it again at the OpenSSL
+boundary, preserving OpenSSL-compatible bytes for applications.
 
-### Sizes and Security Categories
+## Sizes and Security Categories
 
 ML-KEM always produces a 32-byte shared secret:
 
@@ -86,7 +93,7 @@ faster signing:
 | 256s | 5 | 64 bytes | 128 bytes | 29,792 bytes |
 | 256f | 5 | 64 bytes | 128 bytes | 49,856 bytes |
 
-### Signing and Generation Parameters
+## Signing and Generation Parameters
 
 ML-DSA and SLH-DSA accept the OpenSSL signature context-string parameter, with
 the FIPS 204 and FIPS 205 maximum of 255 bytes. Both support deterministic and
@@ -103,14 +110,15 @@ applications. wolfProvider incrementally hashes HashML-DSA input. Pure ML-DSA
 and SLH-DSA require the complete message; SLH-DSA therefore buffers streaming
 input and enforces a 64 MiB message limit.
 
-### Platform Optimizations
+## Platform Optimizations
 
 wolfProvider calls the native wolfCrypt implementations, so it benefits from
 the optimized code selected by the wolfSSL build without requiring a separate
 provider-specific acceleration layer. Available wolfCrypt PQC speedups include
 x86-64 vectorized implementations and assembly paths for ARM32, AArch64,
-ARMv7-M, and ARMv7E-M. Optimized SHA-3 and SHAKE operations also accelerate
-the Keccak work used by ML-KEM and ML-DSA.
+ARMv7-M, and ARMv7E-M. Optimized SHA-2, SHA-3, and SHAKE operations also
+accelerate the hash work used by ML-KEM, ML-DSA, SLH-DSA, and the configured
+LMS parameter families.
 
 The exact path is compiler, processor, and wolfSSL configuration dependent.
 Applications should use the wolfCrypt benchmark on the target system to
@@ -120,7 +128,7 @@ sets. See the wolfSSL
 and [ML-KEM acceleration overview](https://www.wolfssl.com/accelerated-kyber-ml-kem/)
 for configuration and benchmark details.
 
-### Building
+## Building
 
 The build script can configure OpenSSL, wolfSSL, and wolfProvider together:
 
@@ -128,13 +136,14 @@ The build script can configure OpenSSL, wolfSSL, and wolfProvider together:
 ./scripts/build-wolfprovider.sh --enable-pqc
 ```
 
-`--enable-pqc` enables all three algorithm families. Each family can also be
-selected independently:
+`--enable-pqc` enables ML-KEM and ML-DSA. SLH-DSA and LMS remain independent
+options, and each family can be selected separately:
 
 ```sh
 ./scripts/build-wolfprovider.sh --enable-mlkem
 ./scripts/build-wolfprovider.sh --enable-mldsa
 ./scripts/build-wolfprovider.sh --enable-slhdsa
+./scripts/build-wolfprovider.sh --enable-lms
 ```
 
 For a manual build, configure wolfSSL with the matching algorithm options,
@@ -157,7 +166,7 @@ sudo make install
 PQC code is not compiled unless `--enable-pqc` or an individual PQC option is
 passed to wolfProvider, even when wolfSSL has the algorithms enabled.
 
-### Using wolfProvider
+## Using wolfProvider
 
 For production deployments, the recommended configuration is replace-default
 mode. It makes wolfProvider the OpenSSL default and prevents operations from
@@ -200,11 +209,12 @@ OPENSSL_CONF=/path/to/wolfProvider/provider.conf \
     openssl list -signature-algorithms
 ```
 
-### OpenSSL EVP Example
+## OpenSSL EVP Example
 
 The maintained
 [`examples/pqc_openssl_example.c`](https://github.com/wolfSSL/wolfProvider/blob/master/examples/pqc_openssl_example.c)
-program demonstrates all three algorithm families through the OpenSSL EVP API:
+program demonstrates the three NIST FIPS 203 through FIPS 205 algorithm
+families through the OpenSSL EVP API:
 
 - ML-KEM-768 key generation, encapsulation, and decapsulation
 - ML-DSA-65 key generation, signing, and verification
@@ -219,7 +229,12 @@ builds. After building, it can also be run directly from the wolfProvider root:
 ./examples/pqc_openssl_example
 ```
 
-### Build Macros
+LMS is not part of this example because OpenSSL exposes only verification and
+a useful example would require a fixed public key and signature. The
+repository instead validates LMS with OpenSSL's 320 fixed verification vectors
+and focused provider unit tests.
+
+## Build Macros
 
 The configure options add the corresponding request macros:
 
@@ -235,7 +250,7 @@ with `--enable-slhdsa` and `--enable-lms`. After configuration validates the wol
 wolfProvider uses `WP_HAVE_MLKEM`, `WP_HAVE_MLDSA`, `WP_HAVE_SLHDSA`, and
 `WP_HAVE_LMS` internally to compile and register the available implementations.
 
-### TLS 1.3
+## TLS 1.3
 
 wolfProvider advertises these ML-KEM TLS groups:
 
@@ -250,7 +265,7 @@ It also advertises the `mldsa44`, `mldsa65`, and `mldsa87` TLS 1.3 signature
 schemes. SLH-DSA is supported through EVP but is not advertised as a TLS
 signature scheme.
 
-### Validation
+## Validation
 
 The wolfCrypt Post Quantum v7.0.0 implementation has NIST CAVP algorithm
 validation under
@@ -276,7 +291,9 @@ PQC has several independent test layers:
 
 - Unit and example tests cover key generation, import/export, encoding,
   encapsulation, decapsulation, signing, verification, malformed inputs, and
-  X.509 operations where applicable.
+  X.509 operations where applicable. LMS unit tests specifically cover raw
+  public-key import/export, XDR decoding, selection handling, malformed input,
+  and rejection of unsupported stateful operations.
 - OpenSSL EVP known-answer tests run the ML-KEM, ML-DSA, SLH-DSA, and LMS vector
   files against wolfProvider. The LMS vector contains 320 verification cases.
 - The PQC interoperability test compares wolfProvider with OpenSSL's default
@@ -291,7 +308,8 @@ The version, nginx, and libacvp matrices cover wolfSSL master and the latest
 eligible stable release. OSP tests run in replace-default and non-replace
 modes, with normal and forced-failure cases. PQC KAT and version coverage runs
 for pull requests, while the longer OSP integration workflows are
-label-selected and run nightly.
+label-selected and run nightly. The KAT matrix also includes an LMS-only row
+in addition to the combined PQC configurations.
 
 ## Further Reading
 
@@ -351,6 +369,7 @@ wolfProvider exposes several preprocessor defines that allow users to configure
 | WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support |
 | WP_HAVE_MLDSA | ML-DSA (FIPS 204) post-quantum signature support |
 | WP_HAVE_MLKEM | ML-KEM (FIPS 203) post-quantum key encapsulation support |
+| WP_HAVE_LMS | LMS (RFC 8554 / SP 800-208) verification support |
 | WP_HAVE_PBE | Password-Based Encryption support |
 | WP_HAVE_RANDOM | Random number generation support |
 | WP_HAVE_RSA | RSA encryption and signature support |

From 22c86ba8b3386a4a1fee20cac3d1810616a7043f Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Thu, 13 Aug 2026 17:22:29 -0700
Subject: [PATCH 8/9] Clarify LMS OpenSSL ABI limits and correct libacvp PQC
 coverage

---
 wolfProvider/src/chapter11.md | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md
index 12694cf7..43ec1823 100644
--- a/wolfProvider/src/chapter11.md
+++ b/wolfProvider/src/chapter11.md
@@ -28,10 +28,12 @@ import/export, and public/private key encoding. ML-DSA supports key generation,
 pure and pre-hash signing, verification, context strings, and key encoding.
 SLH-DSA supports key generation, pure signing, verification, context strings,
 and key encoding. LMS supports public-key import and one-shot signature
-verification; private-key import, signing, and key generation are not exposed
-because OpenSSL 3.6 provides LMS as a verification-only interface. This also
-avoids exposing stateful private-key operations through an interface that
-cannot enforce LMS leaf-use state.
+verification only. Private-key import, signing, and key generation are not
+exposed because OpenSSL 3.6's provider ABI defines LMS as verification-only: it
+advertises no signing, key-generation, or private-key import entry points for
+wolfProvider to implement, even though wolfCrypt itself supports them. This
+also avoids exposing stateful private-key operations through an interface that
+cannot enforce LMS leaf-use (one-time signature) state.
 
 ## Provider Architecture
 
@@ -151,7 +153,8 @@ then configure wolfProvider:
 
 ```sh
 # Add the required options to the normal wolfSSL configuration.
-./configure --enable-mlkem --enable-mldsa --enable-slhdsa --enable-lms
+./configure --enable-mlkem --enable-mldsa --enable-slhdsa \
+    --enable-lms=verify-only
 make
 sudo make install
 
@@ -166,6 +169,11 @@ sudo make install
 PQC code is not compiled unless `--enable-pqc` or an individual PQC option is
 passed to wolfProvider, even when wolfSSL has the algorithms enabled.
 
+Because wolfProvider only verifies LMS, build wolfSSL with
+`--enable-lms=verify-only` so LMS signing and key generation are left out of
+the build entirely rather than compiled and unused. The
+`build-wolfprovider.sh --enable-lms` flow already configures wolfSSL this way.
+
 ## Using wolfProvider
 
 For production deployments, the recommended configuration is replace-default
@@ -301,8 +309,10 @@ PQC has several independent test layers:
   groups plus ML-DSA certificate authentication.
 - The nginx OSP workflow tests ML-KEM and hybrid TLS 1.3 key exchange with
   ML-DSA authentication.
-- The pinned libacvp OSP workflow runs its complete unit suite and exercises
-  its OpenSSL ACVP handlers for ML-KEM, ML-DSA, and SLH-DSA.
+- The pinned libacvp (Cisco v2.3.1) OSP workflow builds wolfProvider with
+  `--enable-pqc`, runs its `APP_PQC_HANDLER` group, and then its complete unit
+  suite, exercising the OpenSSL ACVP handlers for ML-KEM and ML-DSA in both
+  replace-default and non-replace modes.
 
 The version, nginx, and libacvp matrices cover wolfSSL master and the latest
 eligible stable release. OSP tests run in replace-default and non-replace

From 135e3177c81c2e706a1d28ab3f29965f85de35b9 Mon Sep 17 00:00:00 2001
From: Aidan Garske <aidan@wolfssl.com>
Date: Thu, 13 Aug 2026 18:21:06 -0700
Subject: [PATCH 9/9] Fix Japanese manual build and document LMS in Japanese
 build tables

---
 wolfProvider/Makefile            | 5 +++--
 wolfProvider/src-ja/chapter03.md | 2 ++
 wolfProvider/src/chapter11.md    | 2 +-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/wolfProvider/Makefile b/wolfProvider/Makefile
index 0bc8ecf5..98c59b9e 100644
--- a/wolfProvider/Makefile
+++ b/wolfProvider/Makefile
@@ -12,13 +12,14 @@ SOURCES = chapter01.md \
 		  chapter07.md \
 		  chapter08.md \
 		  chapter09.md \
-		  chapter10.md \
-		  chapter11.md
+		  chapter10.md
 
 ifeq ($(DOC_LANG),JA)
 	PDF = wolfProvider-Manual-jp.pdf
 else
 	PDF = wolfProvider-Manual.pdf
+	# chapter11 (Post-Quantum) is English-only until it is translated.
+	SOURCES += chapter11.md
 endif
 
 .PHONY: html-prep
diff --git a/wolfProvider/src-ja/chapter03.md b/wolfProvider/src-ja/chapter03.md
index bc129258..3d058f54 100644
--- a/wolfProvider/src-ja/chapter03.md
+++ b/wolfProvider/src-ja/chapter03.md
@@ -265,6 +265,7 @@ wolfProviderを静的エンジンとして使用するには`--static`を付け
 | --enable-mlkem | **無効** | ML-KEM (FIPS 203) のみを有効にする |
 | --enable-mldsa | **無効** | ML-DSA (FIPS 204) のみを有効にする |
 | --enable-slhdsa | **無効** | SLH-DSA (FIPS 205) のみを有効にする |
+| --enable-lms | **無効** | LMS検証のみを有効にする |
 | | | | |
 | --with-openssl=DIR | | リンクするOpenSSLのインストール場所。設定されていない場合は、システムのデフォルトのライブラリとインクルードパスが使用されます。 |
 | --with-wolfssl=DIR | | リンクするwolfSSLのインストール場所。設定されていない場合は、システムのデフォルトのライブラリとインクルードパスが使用されます。 |
@@ -306,6 +307,7 @@ wolfProviderは、お客様がwolfProviderのビルド方法を設定できる
 | WP_HAVE_HKDF | HKDF (HMACベースの鍵導出関数) を有効化 |
 | WP_HAVE_HMAC | HMAC (ハッシュベースのメッセージ認証コード) を有効化 |
 | WP_HAVE_KRB5KDF | Kerberos 5 鍵導出関数を有効化 |
+| WP_HAVE_LMS | LMS (RFC 8554 / SP 800-208) 検証を有効化 |
 | WP_HAVE_MD5 | MD5 ハッシュアルゴリズムを有効化 |
 | WP_HAVE_MD5_SHA1 | MD5+SHA1 の組み合わせを有効化 |
 | WP_HAVE_MLDSA | ML-DSA (FIPS 204) ポスト量子署名を有効化 |
diff --git a/wolfProvider/src/chapter11.md b/wolfProvider/src/chapter11.md
index 43ec1823..daefd5ab 100644
--- a/wolfProvider/src/chapter11.md
+++ b/wolfProvider/src/chapter11.md
@@ -375,11 +375,11 @@ wolfProvider exposes several preprocessor defines that allow users to configure
 | WP_HAVE_HKDF | HKDF (HMAC-based Key Derivation Function) support |
 | WP_HAVE_HMAC | HMAC (Hash-based Message Authentication Code) support |
 | WP_HAVE_KRB5KDF | Kerberos 5 Key Derivation Function support |
+| WP_HAVE_LMS | LMS (RFC 8554 / SP 800-208) verification support |
 | WP_HAVE_MD5 | MD5 hash algorithm support |
 | WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support |
 | WP_HAVE_MLDSA | ML-DSA (FIPS 204) post-quantum signature support |
 | WP_HAVE_MLKEM | ML-KEM (FIPS 203) post-quantum key encapsulation support |
-| WP_HAVE_LMS | LMS (RFC 8554 / SP 800-208) verification support |
 | WP_HAVE_PBE | Password-Based Encryption support |
 | WP_HAVE_RANDOM | Random number generation support |
 | WP_HAVE_RSA | RSA encryption and signature support |