Add ML-KEM and ML-DSA support

.github/workflows/wolfssl-versions-pqc.yml

@@ -0,0 +1,141 @@
+name: wolfSSL Versions (PQC)
+
+# Backward-compatibility matrix for ML-KEM and ML-DSA. Mirrors wolfTPM's
+# wolfssl-versions-pqc.yml pattern: a discover-versions job dynamically
+# resolves the latest -stable wolfSSL tag and decides if it is past the PQC
+# floor, then the build job runs three rows: pre-PQC floor, dynamically
+# resolved latest -stable, and master.
+#
+# PQC_FLOOR is v5.9.1-stable: the wc_MlDsaKey_* / wc_dilithium_sign_ctx_msg
+# API that wolfProvider's PQC code depends on lands post-v5.9.1-stable
+# (wolfSSL PR #10436), so v5.9.2-stable+ is the first PQC-eligible release.
+# Older wolfSSL versions skip the PQC code paths via settings.h gating and
+# only verify the no-symbol path still builds.
+
+on:
+  push:
+    branches: [ 'master', 'main', 'release/**' ]
+  pull_request:
+    branches: [ '*' ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  discover-versions:
+    name: Resolve wolfSSL version matrix
+    runs-on: ubuntu-22.04
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+      latest-stable: ${{ steps.set-matrix.outputs.latest-stable }}
+    steps:
+      - name: Resolve latest -stable wolfSSL tag
+        id: set-matrix
+        run: |
+          set -euo pipefail
+          LATEST=$(git ls-remote --tags --refs \
+              https://github.com/wolfSSL/wolfssl.git 'v*-stable' \
+              | awk -F/ '{print $NF}' | sort -V | tail -n 1)
+          if [ -z "${LATEST:-}" ]; then
+            echo "::error::Could not resolve latest wolfSSL -stable tag"
+            exit 1
+          fi
+          echo "Latest stable wolfSSL: $LATEST"
+          echo "latest-stable=$LATEST" >> "$GITHUB_OUTPUT"
+          # Enable PQC when $LATEST is strictly newer than v5.9.1-stable
+          # (i.e. v5.9.2-stable, v5.10+, v6+, ...). Anything at or before
+          # the floor lacks the wc_MlDsaKey_* / wc_dilithium_sign_ctx_msg
+          # API and stays on the no-symbol path.
+          PQC_FLOOR="v5.9.1-stable"
+          if [ "$(printf '%s\n%s\n' "$PQC_FLOOR" "$LATEST" \
+                  | sort -V | tail -n1)" != "$PQC_FLOOR" ]; then
+            LATEST_PQC_ELIGIBLE=true
+          else
+            LATEST_PQC_ELIGIBLE=false
+          fi
+          echo "latest-stable PQC eligible: $LATEST_PQC_ELIGIBLE"
+          MATRIX=$(jq -nc \
+              --arg latest "$LATEST" \
+              --argjson latest_pqc "$LATEST_PQC_ELIGIBLE" '{
+            include: [
+              {"name":"pre-PQC (v5.8.0-stable, PQC disabled)",
+               "wolfssl-ref":"v5.8.0-stable","pqc":false},
+              {"name":("latest stable (" + $latest + ", PQC " +
+                       (if $latest_pqc then "enabled" else "disabled" end) + ")"),
+               "wolfssl-ref":$latest,"pqc":$latest_pqc},
+              {"name":"master (PQC enabled)",
+               "wolfssl-ref":"master","pqc":true}
+            ]
+          }')
+          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+
+  pqc-build-test:
+    name: ${{ matrix.name }}
+    needs: discover-versions
+    runs-on: ubuntu-22.04
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover-versions.outputs.matrix) }}
+    steps:
+      - name: Checkout wolfProvider
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      # OpenSSL is pinned to 3.5.4 on every row so the cross-provider interop
+      # test can verify against the default provider's native ML-KEM/ML-DSA.
+      # OpenSSL 3.5 is the first release with native PQC support; older 3.x
+      # versions can build wolfProvider but the interop step would have
+      # nothing to compare against on the default-provider side.
+      - name: Build wolfProvider (PQC=${{ matrix.pqc }})
+        run: |
+          if [ "${{ matrix.pqc }}" = "true" ]; then
+            OPENSSL_TAG=openssl-3.5.4 \
+            WOLFSSL_TAG=${{ matrix.wolfssl-ref }} \
+              ./scripts/build-wolfprovider.sh --enable-pqc
+          else
+            OPENSSL_TAG=openssl-3.5.4 \
+            WOLFSSL_TAG=${{ matrix.wolfssl-ref }} \
+              ./scripts/build-wolfprovider.sh
+          fi
+
+      # On PQC-enabled rows the PQC tests must be present. We do NOT assert
+      # absence on the no-PQC rows because v5.9.x's --enable-all-crypto now
+      # auto-enables MLKEM/DILITHIUM, so the "latest stable" row will pick up
+      # PQC at the wolfSSL level even without --enable-pqc. wolfProvider
+      # auto-detects and compiles in the PQC code in that case, which is fine.
+      - name: Confirm PQC tests present on PQC-enabled rows
+        if: matrix.pqc == true
+        run: |
+          ./test/unit.test --list | grep -q 'test_mlkem_keygen' \
+            || { echo 'ERROR: PQC tests missing in PQC-enabled build'; \
+                 exit 1; }
+          ./test/unit.test --list | grep -q 'test_mldsa_sign_verify' \
+            || { echo 'ERROR: ML-DSA tests missing in PQC-enabled build'; \
+                 exit 1; }
+
+      # Three-way interop: wolfProvider <-> OpenSSL default <-> wolfSSL direct.
+      # Only runs on PQC-enabled rows; OpenSSL 3.5+ has native ML-KEM/ML-DSA
+      # in the default provider, so this proves wolfProvider's bytes are
+      # FIPS 203/204 standards-compliant against two reference implementations.
+      # Linux x86_64 OpenSSL installs to lib64 by default; LD_LIBRARY_PATH
+      # must include both lib and lib64 or the dynamic linker falls through
+      # to the system libcrypto/libssl (Ubuntu 22.04 ships 3.0.2, which has
+      # no ML-KEM/ML-DSA in the default provider).
+      - name: Three-way PQC interop validation
+        if: matrix.pqc == true
+        run: |
+          LD_LIBRARY_PATH="$(pwd)/wolfssl-install/lib:$(pwd)/openssl-install/lib:$(pwd)/openssl-install/lib64" \
+            ./test/pqc_interop.test
+
+      - name: Print errors on failure
+        if: ${{ failure() }}
+        run: |
+          if [ -f test-suite.log ]; then
+            cat test-suite.log
+          fi

ChangeLog.md

@@ -7,6 +7,7 @@ PR stands for Pull Request, and PR <NUMBER> references a GitHub pull request
 number where the code change was added.
 
 ## New Feature Additions
+* Add ML-KEM (FIPS 203) and ML-DSA (FIPS 204) post-quantum algorithm support via `--enable-pqc` (PR 399)
 * Add OpenSSL FIPS baseline process implementation (PR 357)
 * Add seed-src handling for wolfProvider (PR 350)
 * Add EC public key auto derivation from private key (PR 338)

README.md

@@ -73,6 +73,13 @@ Information on how to configure, build, and test wolfProvider can be found here:
 * X25519, X448 (key exchange)
 * Ed25519, Ed448 (signatures)
 
+### Post-Quantum (NIST FIPS 203 / 204)
+Requires wolfSSL master (post-v5.9.1-stable) and OpenSSL 3.5+ for native
+default-provider interop. Opt in with `./scripts/build-wolfprovider.sh --enable-pqc`.
+
+* ML-KEM (FIPS 203): ML-KEM-512, ML-KEM-768, ML-KEM-1024 (key encapsulation)
+* ML-DSA (FIPS 204): ML-DSA-44, ML-DSA-65, ML-DSA-87 (signatures, pure mode with empty context per FIPS 204 sec 5.2)
+
 
 ## Support
 

debian/install-wolfssl.sh

@@ -40,6 +40,7 @@ install_wolfssl_from_git() {
     local debug_mode="$3"
     local reinstall_mode="$4"
     local no_install="$5"
+    local pqc_mode="$6"
     local main_branch="master"
 
     # If no working directory specified, create one using mktemp
@@ -173,6 +174,11 @@ AC_CONFIG_FILES([debian/rules],[chmod +x debian/rules])' configure.ac
         echo "Debug mode enabled"
     fi
 
+    if [ "$pqc_mode" = "true" ]; then
+        configure_opts="$configure_opts --enable-mlkem --enable-mldsa"
+        echo "PQC (ML-KEM/ML-DSA) enabled"
+    fi
+
     ./configure $configure_opts \
         CFLAGS="-DWOLFSSL_OLD_OID_SUM \
             -DWOLFSSL_PUBLIC_ASN \
@@ -220,6 +226,7 @@ main() {
     local debug_mode="false"
     local reinstall_mode="false"
     local no_install="false"
+    local pqc_mode="false"
 
     # Parse command line arguments
     while [[ $# -gt 0 ]]; do
@@ -233,6 +240,7 @@ main() {
                 echo "  -d, --debug          Enable debug build mode (adds --enable-debug)"
                 echo "  -r, --reinstall      Force reinstall even if packages are already installed"
                 echo "  -n, --no-install     Build only, do not install packages"
+                echo "  --enable-pqc         Enable ML-KEM and ML-DSA (FIPS 203/204)"
                 echo "  -h, --help           Show this help message"
                 echo ""
                 echo "Arguments:"
@@ -264,6 +272,10 @@ main() {
                 no_install="true"
                 shift
                 ;;
+            --enable-pqc)
+                pqc_mode="true"
+                shift
+                ;;
             -*)
                 echo "Unknown option: $1" >&2
                 echo "Use --help for usage information" >&2
@@ -300,7 +312,7 @@ main() {
         echo "Building wolfSSL master branch"
     fi
 
-    install_wolfssl_from_git "$work_dir" "$git_tag" "$debug_mode" "$reinstall_mode" "$no_install"
+    install_wolfssl_from_git "$work_dir" "$git_tag" "$debug_mode" "$reinstall_mode" "$no_install" "$pqc_mode"
 
     echo "WolfSSL installation completed successfully"
 }

docs/INTEGRATION_GUIDE.md

@@ -30,6 +30,7 @@ This retrieves dependencies (OpenSSL and wolfSSL) and compiles them as necessary
 | `--openssl-dir=/path` | Use existing OpenSSL installation |
 | `--replace-default` | Make wolfProvider the default provider |
 | `--enable-replace-default-testing` | Enable unit testing with replace-default |
+| `--enable-pqc` | Enable ML-KEM and ML-DSA post-quantum algorithms (adds `--enable-mlkem --enable-mldsa` to wolfSSL). Requires wolfSSL post-v5.9.1-stable. |
 
 **Examples:**
 
@@ -82,6 +83,7 @@ sudo make install
 | `--enable-pwdbased` | PKCS#12 support |
 | `--enable-hmac-copy` | Faster repeated HMAC with same key (wolfSSL 5.7.8+) |
 | `--enable-sp=yes,asm --enable-sp-math-all` | SP Integer maths |
+| `--enable-mlkem --enable-mldsa` | ML-KEM and ML-DSA post-quantum algorithms (wolfSSL post-v5.9.1-stable). The `build-wolfprovider.sh --enable-pqc` flag sets these automatically. |
 
 **Optional CPPFLAGS:**
 
@@ -151,6 +153,58 @@ This makes replace default mode useful for testing scenarios where you want to e
 
 ---
 
+## Post-Quantum Cryptography (ML-KEM and ML-DSA)
+
+wolfProvider supports NIST's post-quantum algorithms via the wolfSSL backend:
+
+| Algorithm | Standard | Parameter Sets |
+|-----------|----------|----------------|
+| ML-KEM (key encapsulation) | FIPS 203 | ML-KEM-512, ML-KEM-768, ML-KEM-1024 |
+| ML-DSA (digital signature)  | FIPS 204 | ML-DSA-44, ML-DSA-65, ML-DSA-87 |
+
+ML-DSA uses pure mode with an empty context string (FIPS 204 sec 5.2, Algorithm 22), interoperable with OpenSSL 3.5+'s native ML-DSA.
+
+### Requirements
+
+- **wolfSSL**: post-v5.9.1-stable (i.e. v5.9.2-stable or master). v5.9.1-stable defines `HAVE_DILITHIUM` and exposes `wc_dilithium_sign_ctx_msg` (the older name for the FIPS 204 pure-mode signer) but does not yet ship the canonical `WOLFSSL_HAVE_MLDSA` macro, `<wolfssl/wolfcrypt/wc_mldsa.h>` header, or `wc_MlDsaKey_SignCtx` alias that wolfProvider gates on.
+- **OpenSSL**: any 3.x. OpenSSL 3.5+ is required only for cross-provider interop against its native ML-KEM/ML-DSA implementations.
+
+### Building with PQC
+
+```bash
+./scripts/build-wolfprovider.sh --enable-pqc
+```
+
+This adds `--enable-mlkem --enable-mldsa` to the wolfSSL configure step. wolfProvider auto-detects the resulting `WOLFSSL_HAVE_MLKEM` / `WOLFSSL_HAVE_MLDSA` macros via `include/wolfprovider/settings.h` (gated on `__has_include` of `<wolfssl/wolfcrypt/wc_mlkem.h>` / `<wolfssl/wolfcrypt/wc_mldsa.h>`) and registers the six PQC algorithms.
+
+### Usage Example
+
+```bash
+# Generate an ML-DSA-65 key with wolfProvider
+OPENSSL_CONF=provider.conf openssl genpkey -algorithm ML-DSA-65 -out key.pem
+
+# Sign and verify with ML-DSA-65
+OPENSSL_CONF=provider.conf openssl pkeyutl -sign -inkey key.pem -in msg.bin -out sig.bin
+OPENSSL_CONF=provider.conf openssl pkeyutl -verify -pubin -inkey pub.pem -sigfile sig.bin -in msg.bin
+```
+
+The OpenSSL CLI can also enumerate available algorithms:
+
+```bash
+OPENSSL_CONF=provider.conf openssl list -kem-algorithms -provider libwolfprov
+OPENSSL_CONF=provider.conf openssl list -signature-algorithms -provider libwolfprov
+```
+
+### Validation
+
+A standalone three-way interop validator (`test/pqc_interop.test`) cross-checks every ML-KEM / ML-DSA combination against:
+- OpenSSL 3.5+'s native default provider
+- wolfSSL's `wc_*` APIs directly (no provider abstraction)
+
+This proves wolfProvider's raw-key, ciphertext, and signature bytes are FIPS 203 / 204 standards-compliant. The CI workflow `.github/workflows/wolfssl-versions-pqc.yml` runs this validator on every PR, plus a backward-compatibility build against pre-PQC wolfSSL to verify the no-symbol path still builds cleanly.
+
+---
+
 ## Testing
 
 ### Unit Tests

include/wolfprovider/alg_funcs.h

@@ -170,6 +170,16 @@ typedef void (*DFUNC)(void);
 #define WP_NAMES_DH             "DH"
 #define WP_NAMES_DHX            "DHX"
 
+/* ML-KEM names (NIST FIPS 203). */
+#define WP_NAMES_ML_KEM_512     "ML-KEM-512"
+#define WP_NAMES_ML_KEM_768     "ML-KEM-768"
+#define WP_NAMES_ML_KEM_1024    "ML-KEM-1024"
+
+/* ML-DSA names (NIST FIPS 204). */
+#define WP_NAMES_ML_DSA_44      "ML-DSA-44"
+#define WP_NAMES_ML_DSA_65      "ML-DSA-65"
+#define WP_NAMES_ML_DSA_87      "ML-DSA-87"
+
 /* DRBG names. */
 #define WP_NAMES_SEED_SRC       "SEED-SRC"
 #define WP_NAMES_CTR_DRBG       "CTR-DRBG"
@@ -222,6 +232,27 @@ void wp_ecx_free(wp_Ecx* ecx);
 void* wp_ecx_get_key(wp_Ecx* ecx);
 wolfSSL_Mutex* wp_ecx_get_mutex(wp_Ecx* ecx);
 
+/* Internal ML-KEM types and functions. */
+typedef struct wp_MlKem wp_MlKem;
+typedef struct wp_MlKemData wp_MlKemData;
+
+int wp_mlkem_up_ref(wp_MlKem* mlkem);
+void wp_mlkem_free(wp_MlKem* mlkem);
+void* wp_mlkem_get_key(wp_MlKem* mlkem);
+const wp_MlKemData* wp_mlkem_get_data(const wp_MlKem* mlkem);
+word32 wp_mlkem_data_ct_size(const wp_MlKemData* data);
+/* ML-KEM shared secret size is a FIPS 203 constant (32 bytes) independent
+ * of the parameter set. */
+#define WP_MLKEM_SS_SIZE 32
+
+/* Internal ML-DSA types and functions. */
+typedef struct wp_MlDsa wp_MlDsa;
+
+int wp_mldsa_up_ref(wp_MlDsa* mldsa);
+void wp_mldsa_free(wp_MlDsa* mldsa);
+void* wp_mldsa_get_key(wp_MlDsa* mldsa);
+int wp_mldsa_get_sig_size(const wp_MlDsa* mldsa);
+
 /* Internal DH types and functions. */
 typedef struct wp_Dh wp_Dh;
 
@@ -325,12 +356,14 @@ extern const OSSL_DISPATCH wp_ed25519_signature_functions[];
 extern const OSSL_DISPATCH wp_ed448_signature_functions[];
 extern const OSSL_DISPATCH wp_hmac_signature_functions[];
 extern const OSSL_DISPATCH wp_cmac_signature_functions[];
+extern const OSSL_DISPATCH wp_mldsa_signature_functions[];
 
 /* Asymmetric cipher implementations. */
 extern const OSSL_DISPATCH wp_rsa_asym_cipher_functions[];
 
 /* KEM implementations. */
 extern const OSSL_DISPATCH wp_rsa_asym_kem_functions[];
+extern const OSSL_DISPATCH wp_mlkem_asym_kem_functions[];
 
 /* Key Management implementations. */
 extern const OSSL_DISPATCH wp_rsa_keymgmt_functions[];
@@ -344,6 +377,12 @@ extern const OSSL_DISPATCH wp_dh_keymgmt_functions[];
 extern const OSSL_DISPATCH wp_hmac_keymgmt_functions[];
 extern const OSSL_DISPATCH wp_cmac_keymgmt_functions[];
 extern const OSSL_DISPATCH wp_kdf_keymgmt_functions[];
+extern const OSSL_DISPATCH wp_mlkem512_keymgmt_functions[];
+extern const OSSL_DISPATCH wp_mlkem768_keymgmt_functions[];
+extern const OSSL_DISPATCH wp_mlkem1024_keymgmt_functions[];
+extern const OSSL_DISPATCH wp_mldsa44_keymgmt_functions[];
+extern const OSSL_DISPATCH wp_mldsa65_keymgmt_functions[];
+extern const OSSL_DISPATCH wp_mldsa87_keymgmt_functions[];
 
 /* Key exchange implementations. */
 extern const OSSL_DISPATCH wp_ecdh_keyexch_functions[];