Convert wolfSSL to lib/wolfssl submodule

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "gitsubmodule"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    commit-message:
+      prefix: "[ci]"

.github/semgrep-rules.yml

@@ -6,9 +6,10 @@
 #
 # Style/maintainability is intentionally out of scope (owned by codespell,
 # Coverity, and the CodeQL security suite). These rules only enforce security
-# invariants. The vendored lib/wolfSPDM/, src/spdm/ and src/fwtpm/ trees, the HAL platform
-# drivers, and the swtpm socket transport carry their own platform libc usage
-# and are excluded where noted.
+# invariants. The lib/wolfssl/ and lib/wolfSPDM/ submodules are excluded from
+# all rules. The src/spdm/ and src/fwtpm/ trees, HAL platform drivers, and swtpm
+# socket transport carry their own platform libc usage and are excluded where
+# noted.
 
 rules:
   - id: wolftpm-no-unbounded-libc
@@ -24,7 +25,9 @@ rules:
         - src/
         - hal/
         - wolftpm/
-        - lib/wolfSPDM/src/
+      exclude:
+        - lib/wolfssl/
+        - lib/wolfSPDM/
     pattern-either:
       - pattern: gets(...)
       - pattern: strcpy(...)
@@ -44,7 +47,9 @@ rules:
         - src/
         - hal/
         - wolftpm/
-        - lib/wolfSPDM/src/
+      exclude:
+        - lib/wolfssl/
+        - lib/wolfSPDM/
     pattern-either:
       - pattern: system(...)
       - pattern: popen(...)
@@ -74,6 +79,7 @@ rules:
         - src/
       exclude:
         - src/spdm/
+        - lib/wolfssl/
         - lib/wolfSPDM/
         - src/fwtpm/
         - src/tpm2_swtpm.c

.github/workflows/codespell.yml

@@ -33,5 +33,5 @@ jobs:
       - name: Run codespell
         run: |
           codespell --count \
-            --skip '.git,./IDE,./certs,./m4,*.der,*.pem,*prebuilt_bindings.rs' \
+            --skip '.git,./lib,./IDE,./certs,./m4,*.der,*.pem,*prebuilt_bindings.rs' \
             --ignore-words-list 'inh,inout,keypair,nd,parm,rcv,ser,loadIn,importIn,certifyIn,bu,fo,daa,pris,hsi,fram,hart,cna'

.github/workflows/wolfssl-submodule.yml

@@ -0,0 +1,67 @@
+name: wolfSSL submodule build
+
+# Builds the pinned lib/wolfssl submodule with the documented flags and builds
+# plus tests wolfTPM (plain and full SPDM) against it, so Dependabot pin bumps
+# are gated on CI. The _resolve-wolfssl matrix still covers latest-stable and
+# master.
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+permissions:
+  contents: read
+
+jobs:
+  pinned-build:
+    name: Build against the pinned wolfSSL submodule
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@6c3c2f2c1c457b00c10c4848d6f5491db3b629df
+        with:
+          egress-policy: audit
+
+      - name: Checkout wolfTPM with submodules
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          submodules: recursive
+          persist-credentials: false
+
+      - name: Build and test the pinned submodule in Docker
+        env:
+          CI_IMAGE: ghcr.io/wolfssl/wolftpm-ci:v1.1
+        run: |
+          docker run --rm --user "$(id -u):$(id -g)" \
+            --env GIT_CONFIG_GLOBAL=/tmp/wolftpm-ci.gitconfig \
+            --mount "type=bind,source=$GITHUB_WORKSPACE,target=/workspace" \
+            --workdir /workspace "$CI_IMAGE" bash -euo pipefail -c '
+              git config --global --add safe.directory /workspace
+              git config --global --add safe.directory /workspace/lib/wolfssl
+              prefix="$PWD/wolfssl-install"
+              (
+                cd lib/wolfssl
+                ./autogen.sh
+                ./configure --enable-wolftpm --enable-pkcallbacks --enable-keygen \
+                    --enable-aescfb CFLAGS="-DWC_RSA_NO_PADDING" --prefix="$prefix"
+                make -j"$(nproc)"
+                make install
+              )
+              export LD_LIBRARY_PATH="$prefix/lib"
+              export WOLFSSL_PATH="$PWD/lib/wolfssl"
+              ./autogen.sh
+              ./configure --with-wolfcrypt="$prefix"
+              make -j"$(nproc)"
+              make distclean
+              ./autogen.sh
+              ./configure --with-wolfcrypt="$prefix" \
+                  --enable-spdm --enable-fwtpm --enable-tcg --enable-psk \
+                  --enable-nuvoton --enable-nations --enable-debug --enable-swtpm
+              make -j"$(nproc)"
+              make check
+              ./examples/spdm/spdm_test.sh ./examples/spdm/spdm_ctrl fwtpm-tcg
+              ./examples/spdm/spdm_test.sh ./examples/spdm/spdm_ctrl fwtpm-psk
+            '

.gitmodules

@@ -3,3 +3,8 @@
 	url = https://github.com/wolfSSL/wolfSPDM.git
 	branch = main
 	ignore = dirty
+[submodule "lib/wolfssl"]
+	path = lib/wolfssl
+	url = https://github.com/wolfSSL/wolfssl.git
+	branch = master
+	ignore = dirty

README.md

@@ -343,20 +343,62 @@ There is no `Caps/Did/Vid/Rid` line above because those values come from TIS bus
 
 ### Building wolfSSL
 
+wolfTPM links against wolfSSL/wolfCrypt. wolfSSL is bundled as the `lib/wolfssl`
+submodule at a known-good commit, so clone wolfTPM with `--recursive` (or run
+`git submodule update --init lib/wolfssl`) and build it from there. **Build
+wolfSSL with `--enable-wolftpm`**; it turns on the RSA, ECC, and crypto-callback
+support wolfTPM relies on. wolfTPM's `configure` only link-checks
+`wolfCrypt_Init`, so it will not flag a wolfSSL built without it, but the
+runtime integration needs it.
+
+`autogen.sh` requires automake and libtool: `sudo apt-get install automake libtool`.
+
+#### Default build
+
 ```bash
-git clone https://github.com/wolfSSL/wolfssl.git
-cd wolfssl
+cd lib/wolfssl
 ./autogen.sh
 ./configure --enable-wolftpm
 make
 sudo make install
 sudo ldconfig
+cd ../..
+```
+
+Then build wolfTPM from the repository root:
+
+```bash
+./autogen.sh
+./configure
+make
 ```
 
-autogen.sh requires: automake and libtool: `sudo apt-get install automake libtool`
+#### SPDM and post-quantum builds
+
+For SPDM, build wolfSSL with the SPDM algorithm-set flags documented in
+[`src/spdm/README.md`](src/spdm/README.md). For a post-quantum build (ML-DSA and
+ML-KEM), add `--enable-mldsa --enable-mlkem`; these require **wolfSSL >=
+v5.9.2-stable**, the release carrying the `wc_MlDsaKey` and `wc_MlKemKey` context
+APIs:
+
+```bash
+cd lib/wolfssl
+./autogen.sh
+./configure --enable-wolftpm --enable-mldsa --enable-mlkem
+make
+sudo make install
+sudo ldconfig
+cd ../..
+```
+
+The pinned wolfSSL submodule can be updated like any checkout: `cd lib/wolfssl`,
+check out or rebuild whatever you need, then reinstall. `git submodule update`
+restores the pinned commit.
 
 ### Building wolfSSL with an alternate directory
 
+The bundled `lib/wolfssl` submodule is the default wolfSSL source; this section is for using a different wolfSSL checkout.
+
 ```bash
 # cd /your-wolfssl-repo
 ./autogen.h # as necessary

docs/FWTPM.md

@@ -56,21 +56,28 @@ fwTPM can replace a hardware TPM for:
 
 ### Prerequisites
 
-wolfSSL must be built with TPM support:
+wolfSSL must be built with TPM support plus the RSA features fwTPM needs
+(`--enable-keygen` for RSA CreatePrimary and `WC_RSA_NO_PADDING` for raw RSA
+Encrypt/Decrypt). wolfSSL is bundled as the `lib/wolfssl` submodule; clone
+wolfTPM with `--recursive` (or run `git submodule update --init lib/wolfssl`)
+and build it from there:
 
 ```sh
-cd wolfssl
-./configure --enable-wolftpm --enable-pkcallbacks
+cd lib/wolfssl
+./autogen.sh
+./configure --enable-wolftpm --enable-pkcallbacks --enable-keygen \
+            CFLAGS="-DWC_RSA_NO_PADDING"
 make
 sudo make install
+cd ../..
 ```
 
 ### Build fwTPM Server
 
 **Socket transport (SWTPM protocol, default for development):**
 
 ```sh
-cd wolftpm
+./autogen.sh
 ./configure --enable-fwtpm --enable-swtpm
 make
 ```

docs/README.md

@@ -53,25 +53,26 @@ The firmware TPM (fwTPM) server also implements v1.85 PQC — see [FWTPM.md](FWT
 
 ## Building wolfTPM
 
-To build the wolfTPM library, it's required to first build and install the wolfSSL library. This can be downloaded from the download page, or through a "git clone" command, shown below:
+To build the wolfTPM library, it's required to first build and install the wolfSSL library. wolfSSL is bundled as the `lib/wolfssl` submodule; clone wolfTPM with `--recursive` (or run `git submodule update --init lib/wolfssl`) and build it from there.
 
 ```sh
-git clone https://github.com/wolfssl/wolfssl
+git clone --recursive https://github.com/wolfSSL/wolfTPM.git
+cd wolfTPM/lib/wolfssl
 ```
 
-Once the wolfSSL library has been downloaded, it needs to be built with the following options being passed to the configure script:
+The wolfSSL library needs to be built with the following options being passed to the configure script:
 
 ```sh
+./autogen.sh
 ./configure --enable-wolftpm && make && sudo make install
+cd ../..
 ```
 
 Then the wolfSSL library just needs to be built and installed however the user prefers.
 
-The next step is to download and install the wolfTPM library. At the time this documentation was written, the wolfTPM library does not have a stable release yet and needs to be cloned from GitHub. The following commands show how to clone and install wolfTPM:
+The next step is to build the wolfTPM library from the same checkout (back at the wolfTPM root):
 
 ```sh
-git clone https://github.com/wolfssl/wolftpm
-cd wolftpm
 ./autogen.sh
 ./configure
 make

docs/SWTPM.md

@@ -239,17 +239,18 @@ To build checkout and build wolfTPM, in the QEMU terminal
 ```sh
 sudo apt install automake libtool gcc git make
 
-# get and build wolfSSL
-git clone https://github.com/wolfssl/wolfssl.git
-pushd wolfssl
+# get wolfTPM (wolfSSL is bundled as the lib/wolfssl submodule)
+git clone --recursive https://github.com/wolfSSL/wolfTPM.git
+pushd wolfTPM
+
+# build wolfSSL from the submodule
+pushd lib/wolfssl
 ./autogen.sh && \
-  ./configure --enable-wolftpm --disable-examples --prefix=$PWD/../inst && \
+  ./configure --enable-wolftpm --disable-examples --prefix=$PWD/../../../inst && \
   make install
 popd
 
-# get and build wolfTPM
-git clone https://github.com/wolfssl/wolftpm.git
-pushd wolftpm
+# build wolfTPM
 ./autogen.sh && \
   ./configure --enable-devtpm --prefix=$PWD/../inst --enable-debug && \
   make install

docs/WindowTBS.md

@@ -30,16 +30,18 @@ Unknown    SecurityDevices Trusted Platform Module 2.0
 
 Tested using MSYS2
 
+wolfSSL is bundled as the `lib/wolfssl` submodule; clone wolfTPM with `--recursive` (or run `git submodule update --init lib/wolfssl`) and build it from there.
+
 ```
 export PREFIX=$PWD/tmp_install
 
-cd wolfssl
+cd lib/wolfssl
 ./autogen.sh
 ./configure --prefix="$PREFIX" --enable-wolftpm
 make
 make install
 
-cd wolftpm/
+cd ../..
 ./autogen.sh
 ./configure --prefix="$PREFIX" --enable-winapi
 make
@@ -68,17 +70,16 @@ export PREFIX=$PWD/tmp_install
 export CFLAGS="-DWIN32 -DMINGW -D_WIN32_WINNT=0x0600 -DUSE_WOLF_STRTOK"
 export LIBS="-lws2_32"
 
-cd wolfssl
+cd lib/wolfssl
 ./autogen.sh
 ./configure --host=i686 CC=i686-w64-mingw32-gcc --prefix="$PREFIX" --enable-wolftpm
 make
 make install
 
-cd ../wolftpm/
+cd ../../
 ./autogen.sh
 ./configure --host=i686 CC=i686-w64-mingw32-gcc --prefix="$PREFIX" --enable-winapi
 make
-cd ..
 ```
 
 ## Running on Windows

examples/pqc/README.md

@@ -12,14 +12,21 @@ fwTPM PQC reference.
 
 ## Building
 
-**wolfSSL** (ML-DSA and ML-KEM in wolfCrypt):
+**wolfSSL** (ML-DSA and ML-KEM in wolfCrypt). wolfSSL is bundled as the
+`lib/wolfssl` submodule; clone wolfTPM with `--recursive` (or run `git submodule
+update --init lib/wolfssl`) and build it from there. ML-DSA and ML-KEM require
+**wolfSSL >= v5.9.2-stable** (the release with the `wc_MlDsaKey` and
+`wc_MlKemKey` context APIs):
 
 ```
+cd lib/wolfssl
+./autogen.sh
 ./configure --enable-wolftpm --enable-mldsa --enable-mlkem \
             --enable-tls-mlkem-standalone \
             --enable-harden --enable-keygen --enable-certgen
 make
 sudo make install
+cd ../..
 ```
 
 `--enable-tls-mlkem-standalone` is required for the standalone `ML_KEM_*` TLS

examples/spdm/README.md

@@ -25,19 +25,19 @@ see the [wolfSPDM](https://github.com/aidangarske/wolfSPDM) standalone library.
 
 ### Prerequisites
 
-wolfSSL with crypto algorithms required for SPDM Algorithm Set B:
+wolfSSL with crypto algorithms required for SPDM Algorithm Set B. wolfSSL is bundled as the `lib/wolfssl` submodule; clone wolfTPM with `--recursive` (or run `git submodule update --init lib/wolfssl`) and build it from there.
 
 ```bash
-cd wolfssl
+cd lib/wolfssl
 ./autogen.sh
 ./configure --enable-wolftpm --enable-ecc --enable-sha384 --enable-aesgcm --enable-hkdf --enable-sp
 make && sudo make install && sudo ldconfig
+cd ../..
 ```
 
 ### wolfTPM with Nuvoton SPDM
 
 ```bash
-cd wolfTPM
 ./autogen.sh
 ./configure --enable-spdm --enable-nuvoton
 make
@@ -46,7 +46,6 @@ make
 ### wolfTPM with Nations SPDM
 
 ```bash
-cd wolfTPM
 ./autogen.sh
 ./configure --enable-spdm --enable-nations
 make