aidangarske · Oct 7, 2026 · Oct 8, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "gitsubmodule"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    commit-message:
+      prefix: "[ci]"
diff --git a/.github/semgrep-rules.yml b/.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

diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
@@ -33,5 +33,5 @@ jobs:
       - name: Run codespell
         run: |
           codespell --count \
-            --skip '.git,./IDE,./lib/wolfHAL,./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,challener'
diff --git a/.github/workflows/wolfssl-submodule.yml b/.github/workflows/wolfssl-submodule.yml
@@ -0,0 +1,78 @@
+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 recursive submodules
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          submodules: recursive
+          persist-credentials: false
+
+      - name: Verify wolfSPDM keeps its standalone wolfSSL opt-in
+        run: |
+          # Older wolfSPDM pins do not have a wolfSSL submodule at all.
+          if git -C lib/wolfSPDM config -f .gitmodules \
+              --get submodule.lib/wolfssl.path >/dev/null; then
+            test "$(git -C lib/wolfSPDM config -f .gitmodules \
+                --get submodule.lib/wolfssl.update)" = none
+          fi
+          test -f lib/wolfssl/.git
+          test ! -e lib/wolfSPDM/lib/wolfssl/.git
+
+      - 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
+            '
diff --git a/.gitmodules b/.gitmodules
@@ -6,3 +6,8 @@
 [submodule "lib/wolfHAL"]
 	path = lib/wolfHAL
 	url = https://github.com/wolfSSL/wolfHAL.git
+[submodule "lib/wolfssl"]
+	path = lib/wolfssl
+	url = https://github.com/wolfSSL/wolfssl.git
+	branch = master
+	ignore = dirty
diff --git a/README.md b/README.md
@@ -89,17 +89,48 @@ for build instructions, responder modes, and the end-to-end test scripts.
 
 ### wolfSSL
 
+wolfTPM links against wolfSSL/wolfCrypt. wolfSSL is bundled as the `lib/wolfssl`
+submodule at a known-good commit. 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 ../..
 ```
 
-`autogen.sh` requires automake and libtool: `sudo apt-get install automake libtool`.
+#### Sharing wolfSSL with wolfSPDM
+
+For SPDM builds, initialize the direct dependency with
+`git submodule update --init lib/wolfSPDM`. wolfTPM compiles the wolfSPDM sources
+against the same wolfSSL headers and library as the rest of wolfTPM. It does not
+build or use `lib/wolfSPDM/lib/wolfssl`, so recursive submodule initialization
+is unnecessary.
+
+wolfSPDM's standalone wolfSSL submodule uses `update = none` so normal recursive
+clones and updates skip it. CI checks this policy when the pinned wolfSPDM has
+that submodule. Older wolfSPDM pins have no nested wolfSSL submodule. An explicit
+`--checkout` override or an existing local update setting can still opt in;
+already initialized copies are not removed automatically.
+
+An existing wolfSSL installation can be shared: pass
+`--with-wolfcrypt=/path/to/wolfssl-install` to wolfTPM and, when building
+wolfSPDM separately, `--with-wolfssl=/path/to/wolfssl-install` to wolfSPDM.
+Neither bundled wolfSSL checkout is needed in that case. Build the shared
+wolfSSL with the features required by both consumers and use its matching
+headers and library throughout.
 
 ### wolfTPM
 

diff --git a/docs/README.md b/docs/README.md
@@ -53,25 +53,28 @@ 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; initialize it with `git submodule update --init lib/wolfssl` and build it from there.
 
 ```sh
-git clone https://github.com/wolfssl/wolfssl
+git clone https://github.com/wolfSSL/wolfTPM.git
+cd wolfTPM
+git submodule update --init lib/wolfssl
+cd 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

diff --git a/docs/building.md b/docs/building.md
@@ -4,16 +4,19 @@ wolfTPM is built on top of wolfSSL (wolfCrypt) and can be built with autotools,
 
 ## Building wolfSSL
 
-wolfSSL must be built and installed first. It can be downloaded from the [downloads page](https://wolfssl.com/download/) or cloned from GitHub:
+wolfSSL must be built and installed first. wolfSSL is bundled as the `lib/wolfssl` submodule at a known-good commit, so initialize it with `git submodule update --init lib/wolfssl` and build wolfSSL from there:
 
 ```bash
-git clone https://github.com/wolfSSL/wolfssl.git
-cd wolfssl
+git clone https://github.com/wolfSSL/wolfTPM.git
+cd wolfTPM
+git submodule update --init lib/wolfssl
+cd lib/wolfssl
 ./autogen.sh
 ./configure --enable-wolftpm --enable-pkcallbacks --enable-keygen CFLAGS="-DWC_RSA_NO_PADDING"
 make
 sudo make install
 sudo ldconfig
+cd ../..
 ```
 
 `autogen.sh` requires automake and libtool: `sudo apt-get install automake libtool`.
@@ -27,7 +30,21 @@ The `--enable-wolftpm` option is equivalent to passing these options:
 
 ## Using an alternate wolfSSL directory
 
-To build wolfTPM against a wolfSSL installed in a non-default location, install wolfSSL to a prefix and point wolfTPM at it with `--with-wolfcrypt`:
+wolfTPM and wolfSPDM can use one wolfSSL installation. wolfTPM compiles the
+wolfSPDM sources directly against its selected wolfSSL; it does not use
+`lib/wolfSPDM/lib/wolfssl`. Initialize direct dependencies without `--recursive`:
+
+```sh
+git submodule update --init lib/wolfssl lib/wolfSPDM
+```
+
+To use an existing installation, skip initializing `lib/wolfssl` and configure
+wolfTPM with `--with-wolfcrypt=/path/to/wolfssl-install`. When building wolfSPDM
+separately, use `--with-wolfssl=/path/to/wolfssl-install` there. Build the shared
+wolfSSL with the features needed by both projects and use its matching headers
+and library throughout.
+
+The bundled `lib/wolfssl` submodule is the default wolfSSL source. To build wolfTPM against a different wolfSSL, such as one from the [downloads page](https://wolfssl.com/download/) installed in a non-default location, install wolfSSL to a prefix and point wolfTPM at it with `--with-wolfcrypt`:
 
 ```bash
 # cd /your-wolfssl-repo
@@ -43,11 +60,9 @@ make install
 
 ## Building with autotools
 
-Once wolfSSL is installed, download wolfTPM from the [downloads page](https://wolfssl.com/download/) or clone it from GitHub, then build it:
+Once wolfSSL is installed, build wolfTPM from the repository root:
 
 ```bash
-git clone https://github.com/wolfSSL/wolfTPM.git
-cd wolfTPM
 ./autogen.sh
 ./configure
 make

diff --git a/docs/fwtpm/building.md b/docs/fwtpm/building.md
@@ -4,21 +4,23 @@ This page covers how to build the fwTPM server, the configure options and compil
 
 ## Prerequisites
 
-wolfSSL must be built with TPM support, keygen, and `WC_RSA_NO_PADDING`:
+wolfSSL must be built with TPM support, keygen, and `WC_RSA_NO_PADDING`. wolfSSL is bundled as the `lib/wolfssl` submodule; initialize it with `git submodule update --init lib/wolfssl` and build it from there:
 
 ```sh
-cd wolfssl
+cd lib/wolfssl
+./autogen.sh
 ./configure --enable-wolftpm --enable-pkcallbacks --enable-keygen CFLAGS="-DWC_RSA_NO_PADDING"
 make
 sudo make install
+cd ../..
 ```
 
 ## Build the fwTPM Server
 
 **Socket transport (SWTPM protocol, default for development):**
 
 ```sh
-cd wolftpm
+./autogen.sh
 ./configure --enable-fwtpm --enable-swtpm
 make
 ```

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -4,16 +4,19 @@ wolfTPM is a portable TPM 2.0 library with a native API, a wrapper API, and a se
 
 ## Prerequisites and building wolfSSL
 
-wolfTPM needs wolfSSL (wolfCrypt) built with the wolfTPM options. Build and install wolfSSL first:
+wolfTPM needs wolfSSL (wolfCrypt) built with the wolfTPM options. wolfSSL is bundled as the `lib/wolfssl` submodule, so initialize it with `git submodule update --init lib/wolfssl` and build and install wolfSSL from there first:
 
 ```bash
-git clone https://github.com/wolfSSL/wolfssl.git
-cd wolfssl
+git clone https://github.com/wolfSSL/wolfTPM.git
+cd wolfTPM
+git submodule update --init lib/wolfssl
+cd lib/wolfssl
 ./autogen.sh
 ./configure --enable-wolftpm --enable-pkcallbacks --enable-keygen CFLAGS="-DWC_RSA_NO_PADDING"
 make
 sudo make install
 sudo ldconfig
+cd ../..
 ```
 
 `autogen.sh` requires automake and libtool: `sudo apt-get install automake libtool`.
@@ -23,8 +26,6 @@ See [Building wolfTPM](building.md) for using a wolfSSL installed in a different
 ## Build wolfTPM
 
 ```bash
-git clone https://github.com/wolfSSL/wolfTPM.git
-cd wolfTPM
 ./autogen.sh
 ./configure
 make