Rename Dilithium API to ML-DSA and make CI track latest wolfSSL stable

.github/workflows/_resolve-wolfssl.yml

@@ -0,0 +1,63 @@
+name: Resolve wolfSSL versions
+
+on:
+  workflow_call:
+    outputs:
+      matrix:
+        description: 'JSON matrix include of wolfSSL refs (master + latest -stable), each with a pqc flag'
+        value: ${{ jobs.resolve.outputs.matrix }}
+      refs:
+        description: 'JSON array of wolfSSL refs ([latest -stable, master]) for use as a matrix axis'
+        value: ${{ jobs.resolve.outputs.refs }}
+      latest-stable:
+        description: 'Latest wolfSSL v*-stable tag resolved at run time'
+        value: ${{ jobs.resolve.outputs.latest-stable }}
+      latest-pqc:
+        description: 'true when latest -stable is strictly newer than the v5.9.1 PQC floor'
+        value: ${{ jobs.resolve.outputs.latest-pqc }}
+
+permissions:
+  contents: read
+
+jobs:
+  resolve:
+    name: Resolve wolfSSL version matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+      refs: ${{ steps.set-matrix.outputs.refs }}
+      latest-stable: ${{ steps.set-matrix.outputs.latest-stable }}
+      latest-pqc: ${{ steps.set-matrix.outputs.latest-pqc }}
+    steps:
+      - name: Resolve latest -stable wolfSSL tag and PQC eligibility
+        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 from remote"
+            exit 1
+          fi
+          echo "Latest stable wolfSSL: $LATEST"
+          echo "latest-stable=$LATEST" >> "$GITHUB_OUTPUT"
+          # Enable PQC only when $LATEST is strictly newer than v5.9.1-stable.
+          # The wc_MlDsaKey API lands post-v5.9.1-stable; older stables only
+          # ship the legacy wc_dilithium_* API wolfCOSE no longer calls.
+          PQC_FLOOR="v5.9.1-stable"
+          if [ "$(printf '%s\n%s\n' "$PQC_FLOOR" "$LATEST" | sort -V | tail -n 1)" != "$PQC_FLOOR" ]; then
+            LATEST_PQC=true
+          else
+            LATEST_PQC=false
+          fi
+          echo "latest-stable PQC eligible: $LATEST_PQC"
+          echo "latest-pqc=$LATEST_PQC" >> "$GITHUB_OUTPUT"
+          MATRIX=$(jq -nc --arg latest "$LATEST" --argjson latest_pqc "$LATEST_PQC" '{
+            include: [
+              {"wolfssl-version":$latest,"wolfssl-ref":$latest,"pqc":$latest_pqc},
+              {"wolfssl-version":"master","wolfssl-ref":"master","pqc":true}
+            ]
+          }')
+          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+          REFS=$(jq -nc --arg latest "$LATEST" '[$latest, "master"]')
+          echo "refs=$REFS" >> "$GITHUB_OUTPUT"

.github/workflows/build-test.yml

@@ -12,13 +12,18 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  discover:
+    uses: ./.github/workflows/_resolve-wolfssl.yml
+
   build:
-    name: ${{ matrix.os }}
+    name: ${{ matrix.os }} (wolfSSL ${{ matrix.wolfssl-ref }})
+    needs: discover
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, ubuntu-22.04, macos-latest]
+        wolfssl-ref: ${{ fromJson(needs.discover.outputs.refs) }}
 
     steps:
     - uses: actions/checkout@v4
@@ -33,27 +38,38 @@ jobs:
       if: runner.os == 'macOS'
       run: brew install autoconf automake libtool
 
-    - name: Cache wolfSSL
+    - name: Cache wolfSSL (${{ matrix.wolfssl-ref }})
+      if: matrix.wolfssl-ref != 'master'
       id: cache-wolfssl
       uses: actions/cache@v4
       with:
         path: ~/wolfssl-install
-        key: wolfssl-${{ matrix.os }}-v3-full
+        key: wolfssl-${{ matrix.os }}-${{ matrix.wolfssl-ref }}-v4
 
-    - name: Build wolfSSL
-      if: steps.cache-wolfssl.outputs.cache-hit != 'true'
+    - name: Build wolfSSL (${{ matrix.wolfssl-ref }})
+      if: matrix.wolfssl-ref == 'master' || steps.cache-wolfssl.outputs.cache-hit != 'true'
       run: |
         cd ~
-        git clone --depth 1 https://github.com/wolfSSL/wolfssl.git
+        git clone --depth 1 --branch ${{ matrix.wolfssl-ref }} \
+            https://github.com/wolfSSL/wolfssl.git
         cd wolfssl
         ./autogen.sh
+        # PQC (ML-DSA wc_MlDsaKey) only exists on master or stable releases
+        # strictly newer than the v5.9.1 floor.
+        REF="${{ matrix.wolfssl-ref }}"
+        if [ "$REF" = "master" ] || \
+           [ "$(printf '%s\n%s\n' v5.9.1-stable "$REF" | sort -V | tail -n1)" != "v5.9.1-stable" ]; then
+          PQC_FLAGS="--enable-dilithium --enable-experimental"
+        else
+          PQC_FLAGS=""
+        fi
         ./configure --enable-ecc --enable-ed25519 --enable-ed448 \
                     --enable-curve25519 --enable-curve448 \
                     --enable-aesgcm --enable-aesccm \
                     --enable-sha384 --enable-sha512 \
                     --enable-keygen --enable-hkdf --enable-aeskeywrap \
                     --enable-chacha --enable-poly1305 \
-                    --enable-dilithium --enable-rsapss \
+                    $PQC_FLAGS --enable-rsapss \
                     --prefix=$HOME/wolfssl-install
         make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)
         make install
@@ -81,8 +97,12 @@ jobs:
                        LDFLAGS="-L$WOLFSSL_DIR/lib -lwolfssl"
 
   coverage:
-    name: Code Coverage
+    name: Code Coverage (wolfSSL ${{ matrix.wolfssl-version }})
+    needs: discover
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover.outputs.matrix) }}
 
     steps:
     - uses: actions/checkout@v4
@@ -92,27 +112,36 @@ jobs:
         sudo apt-get update
         sudo apt-get install -y autoconf automake libtool lcov
 
-    - name: Cache wolfSSL
+    - name: Cache wolfSSL (${{ matrix.wolfssl-version }})
+      if: matrix.wolfssl-version != 'master'
       id: cache-wolfssl
       uses: actions/cache@v4
       with:
         path: ~/wolfssl-install
-        key: wolfssl-ubuntu-latest-coverage-v3-full
+        key: wolfssl-coverage-${{ matrix.wolfssl-version }}-v4
 
-    - name: Build wolfSSL
-      if: steps.cache-wolfssl.outputs.cache-hit != 'true'
+    - name: Build wolfSSL (${{ matrix.wolfssl-version }})
+      if: matrix.wolfssl-version == 'master' || steps.cache-wolfssl.outputs.cache-hit != 'true'
+      env:
+        PQC: ${{ matrix.pqc }}
       run: |
         cd ~
-        git clone --depth 1 https://github.com/wolfSSL/wolfssl.git
+        git clone --depth 1 --branch ${{ matrix.wolfssl-ref }} \
+            https://github.com/wolfSSL/wolfssl.git
         cd wolfssl
         ./autogen.sh
+        if [ "$PQC" = "true" ]; then
+          PQC_FLAGS="--enable-dilithium --enable-experimental"
+        else
+          PQC_FLAGS=""
+        fi
         ./configure --enable-ecc --enable-ed25519 --enable-ed448 \
                     --enable-curve25519 --enable-curve448 \
                     --enable-aesgcm --enable-aesccm \
                     --enable-sha384 --enable-sha512 \
                     --enable-keygen --enable-hkdf --enable-aeskeywrap \
                     --enable-chacha --enable-poly1305 \
-                    --enable-dilithium --enable-rsapss \
+                    $PQC_FLAGS --enable-rsapss \
                     --prefix=$HOME/wolfssl-install
         make -j$(nproc)
         make install
@@ -149,6 +178,7 @@ jobs:
         echo "Coverage ${COVERAGE}% meets threshold of 75%"
 
     - name: Upload coverage report
+      if: matrix.wolfssl-version == 'master'
       uses: actions/upload-artifact@v4
       with:
         name: coverage-report

.github/workflows/cmdline-test.yml

@@ -0,0 +1,81 @@
+name: Command-Line Tool Test
+
+on:
+  push:
+    branches: [ 'master', 'main', 'release/**' ]
+  pull_request:
+    branches: [ '*' ]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  discover:
+    uses: ./.github/workflows/_resolve-wolfssl.yml
+
+  cmdline:
+    name: Command-line tool (wolfSSL ${{ matrix.wolfssl-version }})
+    needs: discover
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover.outputs.matrix) }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y autoconf automake libtool
+
+    - name: Cache wolfSSL (${{ matrix.wolfssl-version }})
+      if: matrix.wolfssl-version != 'master'
+      id: cache-wolfssl
+      uses: actions/cache@v4
+      with:
+        path: ~/wolfssl-install
+        key: wolfssl-clitest-${{ matrix.wolfssl-version }}-v3
+
+    - name: Build wolfSSL (${{ matrix.wolfssl-version }})
+      if: matrix.wolfssl-version == 'master' || steps.cache-wolfssl.outputs.cache-hit != 'true'
+      env:
+        PQC: ${{ matrix.pqc }}
+      run: |
+        cd ~
+        git clone --depth 1 --branch ${{ matrix.wolfssl-ref }} \
+            https://github.com/wolfSSL/wolfssl.git
+        cd wolfssl
+        ./autogen.sh
+        if [ "$PQC" = "true" ]; then
+          PQC_FLAGS="--enable-dilithium --enable-experimental"
+        else
+          PQC_FLAGS=""
+        fi
+        # Full algorithm set so the command-line tool test covers every path.
+        ./configure --enable-ecc --enable-ed25519 --enable-ed448 \
+                    --enable-curve25519 --enable-curve448 \
+                    --enable-aesgcm --enable-aesccm --enable-aescbc \
+                    --enable-sha384 --enable-sha512 \
+                    --enable-keygen --enable-hkdf --enable-aeskeywrap \
+                    --enable-chacha --enable-poly1305 \
+                    $PQC_FLAGS --enable-rsapss \
+                    --prefix=$HOME/wolfssl-install
+        make -j$(nproc)
+        make install
+
+    - name: Build wolfCOSE command-line tool
+      run: |
+        export WOLFSSL_DIR=$HOME/wolfssl-install
+        make tool CFLAGS="-std=c11 -Os -Wall -Wextra -Wpedantic -Wshadow -Wconversion -I./include -I$WOLFSSL_DIR/include" \
+                  LDFLAGS="-L$WOLFSSL_DIR/lib -lwolfssl"
+
+    - name: Run command-line tool test (all algorithms, all subcommands)
+      env:
+        EXPECT_PQC: ${{ matrix.pqc }}
+      run: |
+        export WOLFSSL_DIR=$HOME/wolfssl-install
+        export LD_LIBRARY_PATH=$WOLFSSL_DIR/lib
+        ./scripts/cmdline-test.sh ./tools/wolfcose_tool

.github/workflows/comprehensive-tests.yml

@@ -12,9 +12,16 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  discover:
+    uses: ./.github/workflows/_resolve-wolfssl.yml
+
   comprehensive:
-    name: Algorithm Matrix Tests
+    name: Algorithm Matrix Tests (wolfSSL ${{ matrix.wolfssl-version }})
+    needs: discover
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover.outputs.matrix) }}
 
     steps:
     - uses: actions/checkout@v4
@@ -24,25 +31,34 @@ jobs:
         sudo apt-get update
         sudo apt-get install -y autoconf automake libtool
 
-    - name: Cache wolfSSL
+    - name: Cache wolfSSL (${{ matrix.wolfssl-version }})
+      if: matrix.wolfssl-version != 'master'
       id: cache-wolfssl
       uses: actions/cache@v4
       with:
         path: ~/wolfssl-install
-        key: wolfssl-ubuntu-latest-comprehensive-v1
+        key: wolfssl-comprehensive-${{ matrix.wolfssl-version }}-v1
 
-    - name: Build wolfSSL
-      if: steps.cache-wolfssl.outputs.cache-hit != 'true'
+    - name: Build wolfSSL (${{ matrix.wolfssl-version }})
+      if: matrix.wolfssl-version == 'master' || steps.cache-wolfssl.outputs.cache-hit != 'true'
+      env:
+        PQC: ${{ matrix.pqc }}
       run: |
         cd ~
-        git clone --depth 1 https://github.com/wolfSSL/wolfssl.git
+        git clone --depth 1 --branch ${{ matrix.wolfssl-ref }} \
+            https://github.com/wolfSSL/wolfssl.git
         cd wolfssl
         ./autogen.sh
+        if [ "$PQC" = "true" ]; then
+          PQC_FLAGS="--enable-dilithium --enable-experimental"
+        else
+          PQC_FLAGS=""
+        fi
         ./configure --enable-ecc --enable-ed25519 --enable-ed448 \
                     --enable-curve25519 --enable-aesgcm --enable-aesccm \
                     --enable-sha384 --enable-sha512 --enable-keygen \
                     --enable-rsapss --enable-chacha --enable-poly1305 \
-                    --enable-dilithium --enable-hkdf --enable-aeskeywrap \
+                    $PQC_FLAGS --enable-hkdf --enable-aeskeywrap \
                     --prefix=$HOME/wolfssl-install
         make -j$(nproc)
         make install

.github/workflows/coverage.yml

@@ -37,11 +37,14 @@ jobs:
         git clone --depth 1 https://github.com/wolfSSL/wolfssl.git
         cd wolfssl
         ./autogen.sh
+        # Coverage thresholds (99%/100%) require the ML-DSA paths compiled in,
+        # so build against master with the PQC/experimental wc_MlDsaKey API.
         ./configure --enable-ecc --enable-ed25519 --enable-ed448 \
                     --enable-curve25519 --enable-aesgcm --enable-aesccm \
                     --enable-sha384 --enable-sha512 --enable-keygen \
                     --enable-rsapss --enable-chacha --enable-poly1305 \
-                    --enable-dilithium --enable-hkdf --enable-aeskeywrap \
+                    --enable-dilithium --enable-experimental \
+                    --enable-hkdf --enable-aeskeywrap \
                     --enable-aescbc \
                     --prefix=$HOME/wolfssl-install
         make -j$(nproc)

.github/workflows/coverity.yml

@@ -32,18 +32,19 @@ jobs:
         path: ~/wolfssl-install
         key: wolfssl-coverity-v3
 
-    - name: Build wolfSSL
+    - name: Build wolfSSL (latest stable + master, PQC-gated)
       if: steps.cache-wolfssl.outputs.cache-hit != 'true'
       run: |
         cd ~
+        # Coverity scans against master; ML-DSA always available there.
         git clone --depth 1 https://github.com/wolfSSL/wolfssl.git
         cd wolfssl
         ./autogen.sh
         ./configure --enable-ecc --enable-ed25519 --enable-ed448 \
                     --enable-curve25519 --enable-aesgcm --enable-aesccm \
                     --enable-sha384 --enable-sha512 --enable-keygen \
                     --enable-rsapss --enable-chacha --enable-poly1305 \
-                    --enable-dilithium \
+                    --enable-dilithium --enable-experimental \
                     --prefix=$HOME/wolfssl-install
         make -j$(nproc)
         make install