Prepare wolfTrust documentation for public release

.github/workflows/README.md

@@ -16,6 +16,11 @@ and rejects an invalid capture. Keep submodules under `lib/` and enable
 
 An accepted upload queues analysis; results appear after Coverity processes it.
 
+`docs-site.yml` builds the HTML and PDF manual with the shared
+`wolfSSL/documentation` tooling for documentation pull requests and merges to
+`main`. The website's existing documentation update picks up merged changes
+through the documentation repository. See [DOCS-BUILD.md](../../DOCS-BUILD.md).
+
 ## At a glance
 
 | Tier | Trigger | Purpose |

.github/workflows/docs-site.yml

@@ -0,0 +1,75 @@
+name: Build manual with documentation tooling
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'DOCS-BUILD.md'
+      - 'mkdocs.yml'
+      - 'tools/docs_manual.py'
+      - 'tools/docs-manual/**'
+      - 'docker/docs/**'
+      - '.github/workflows/docs-site.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'DOCS-BUILD.md'
+      - 'mkdocs.yml'
+      - 'tools/docs_manual.py'
+      - 'tools/docs-manual/**'
+      - 'docker/docs/**'
+      - '.github/workflows/docs-site.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - name: Select documentation revision
+        id: documentation
+        run: echo "sha=$(cat tools/docs-manual/documentation-rev)" >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@v4
+        with:
+          repository: wolfSSL/documentation
+          ref: ${{ steps.documentation.outputs.sha }}
+          path: build/documentation
+          submodules: recursive
+          persist-credentials: false
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Pull documentation builder
+        run: |
+          set -euo pipefail
+          image_sha=$(sha256sum docker/docs/Dockerfile docker/docs/requirements.txt | sha256sum | cut -c1-16)
+          image="ghcr.io/wolfssl/wolftrust-docs:sha-$image_sha"
+          if ! docker pull "$image"; then
+            docker build --pull -t "$image" docker/docs
+          fi
+          echo "DOCS_IMAGE=$image" >> "$GITHUB_ENV"
+      - name: Build and validate HTML and PDF
+        run: |
+          tools/check-docs-no-internal-links.sh
+          docker run --rm --user "$(id -u):$(id -g)" --env HOME=/tmp \
+            --mount "type=bind,source=$GITHUB_WORKSPACE,target=/work/wolfTrust" \
+            --workdir /work/wolfTrust "$DOCS_IMAGE" \
+            sh -c 'python3 tools/docs_manual.py build --documentation-root /work/wolfTrust/build/documentation --source-root /work/wolfTrust --target all && cd build/documentation/wolfTrust && mkdocs build --strict -f mkdocs.yml'
+          test -s build/documentation/wolfTrust/html/index.html
+          test -s build/documentation/wolfTrust/wolfTrust-Manual.pdf
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wolftrust-manual
+          path: |
+            build/documentation/wolfTrust/html/
+            build/documentation/wolfTrust/wolfTrust-Manual.pdf
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/publish-docs-image.yml

@@ -0,0 +1,42 @@
+name: Publish documentation image
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docker/docs/**'
+      - '.github/workflows/publish-docs-image.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: publish-wolftrust-docs-image
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: github.repository == 'wolfSSL/wolfTrust'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Select image tag
+        id: image
+        run: |
+          image_sha=$(sha256sum docker/docs/Dockerfile docker/docs/requirements.txt | sha256sum | cut -c1-16)
+          echo "tag=ghcr.io/wolfssl/wolftrust-docs:sha-$image_sha" >> "$GITHUB_OUTPUT"
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: docker/docs
+          file: docker/docs/Dockerfile
+          push: true
+          tags: ${{ steps.image.outputs.tag }}

.gitmodules

@@ -3,16 +3,16 @@
 	url = https://github.com/wolfSSL/wolfHSM.git
 [submodule "lib/wolfSSL"]
 	path = lib/wolfSSL
-	url = git@github.com:wolfSSL/wolfSSL.git
+	url = https://github.com/wolfSSL/wolfSSL.git
 [submodule "lib/wolfhal"]
 	path = lib/wolfhal
-	url = git@github.com:wolfSSL/wolfhal.git
+	url = https://github.com/wolfSSL/wolfhal.git
 [submodule "lib/wolfPSA"]
 	path = lib/wolfPSA
 	url = https://github.com/wolfSSL/wolfPSA.git
 [submodule "lib/wolfIP"]
 	path = lib/wolfIP
-	url = git@github.com:wolfSSL/wolfip.git
+	url = https://github.com/wolfSSL/wolfip.git
 [submodule "lib/wolfCOSE"]
 	path = lib/wolfCOSE
 	url = https://github.com/wolfSSL/wolfCOSE.git

DOCS-BUILD.md

@@ -0,0 +1,72 @@
+# Building and publishing the wolfTrust manual
+
+`docs/` is the manual source. `mkdocs.yml` defines the page order and
+navigation. The adapter in `tools/docs_manual.py` passes those pages to the
+shared MkDocs theme and Pandoc/LaTeX PDF rules in
+[`wolfSSL/documentation`](https://github.com/wolfSSL/documentation). Keep manual
+content and its navigation in wolfTrust; generated files stay under `build/`.
+
+## Local build
+
+Clone the documentation build tools at the revision used by wolfTrust CI:
+
+```sh
+git clone --recurse-submodules https://github.com/wolfSSL/documentation.git build/documentation
+git -C build/documentation checkout "$(cat tools/docs-manual/documentation-rev)"
+docker build --pull -t wolftrust-docs:local docker/docs
+docker run --rm --user "$(id -u):$(id -g)" --env HOME=/tmp \
+    --mount "type=bind,source=$PWD,target=/work/wolfTrust" \
+    --workdir /work/wolfTrust wolftrust-docs:local \
+    python3 tools/docs_manual.py build \
+        --documentation-root /work/wolfTrust/build/documentation \
+        --source-root /work/wolfTrust --target all
+```
+
+The outputs are `build/documentation/wolfTrust/html/` and
+`build/documentation/wolfTrust/wolfTrust-Manual.pdf`. The container includes
+MkDocs, Pandoc, LaTeX, and the fonts used by the shared build rules. On a
+wolfTrust pull request, `docs-site.yml` checks out the pinned documentation
+revision, builds both outputs, runs MkDocs in strict mode, and uploads them as
+one artifact. It also runs after documentation changes merge to `main`.
+CI pulls the versioned builder image from GHCR, or builds it from
+`docker/docs/` if that image is unavailable. No host package installation or
+website credentials are needed for this check.
+
+For an HTML preview, first run the build above, then run:
+
+```sh
+docker run --rm --user "$(id -u):$(id -g)" --env HOME=/tmp -p 8000:8000 \
+    --mount "type=bind,source=$PWD,target=/work/wolfTrust" \
+    --workdir /work/wolfTrust/build/documentation/wolfTrust \
+    wolftrust-docs:local mkdocs serve -a 0.0.0.0:8000 -f mkdocs.yml
+```
+
+The architecture diagram is maintained in `docs/assets/architecture.mmd`.
+Regenerate its static image after editing it so HTML and PDF show the same
+labels:
+
+```sh
+npx --yes @mermaid-js/mermaid-cli@12.0.0 \
+    -i docs/assets/architecture.mmd \
+    -o docs/assets/architecture.png \
+    -b white -c docs/assets/architecture.config.json -s 2
+```
+
+## Website update
+
+The one-time integration in `wolfSSL/documentation` adds a `wolfTrust` manual
+target beside wolfBoot and wolfHSM. It clones `wolfSSL/wolfTrust` **main**, runs
+the adapter from that checkout, and exports `wolfTrust-html/` and
+`wolfTrust-Manual.pdf` through the documentation repository's existing Docker
+build. Merge the wolfTrust adapter before that integration so its source is
+available on `main`.
+
+After both changes are merged, the existing nightly documentation build should
+pick up `wolftrust` through the documentation repository's `all` target. No
+manual trigger is needed for the normal update. Check the first nightly result
+at `https://www.wolfssl.com/documentation/manuals/wolftrust/` and its
+`wolfTrust-Manual.pdf`. The website upload rules are outside these public
+repositories; if the nightly publishes an explicit list of manuals instead of
+all build output, that list will need a one-time addition. Subsequent merged
+wolfTrust documentation changes are read from wolfTrust `main` on the next
+nightly run. Pull requests only build review artifacts.

README.md

@@ -7,13 +7,9 @@ common runtime provides interprocess communication (IPC) through the Arm
 Platform Security Architecture (PSA) Firmware Framework for M (FF-M), manifest
 policy, lifecycle management, scheduling, fault recovery, and PSA services.
 
-The only currently supported and validated reference implementation combines
-the Armv8-M adapter with the STM32H563 Cortex-M33 port. Support for additional
-Cortex-M ports is an intended extension point. Such ports may reuse the common
-runtime and, where applicable, the Armv8-M layer. Cortex-A support is an
-architectural goal, not a current capability. It will require a new adapter and
-changes to current internal execution and protection contracts; the design goal
-is to preserve the public manifest, service, IPC, and PSA API contracts.
+The Armv8-M adapter has two target ports: STM32H563 and NXP MIMXRT700. They
+share the core runtime and architecture layer, with different device security
+controls and validation coverage. See [Ports and supported targets](docs/Targets.md).
 
 ## Architecture
 
@@ -29,15 +25,15 @@ flowchart TB
     subgraph PORT[Architecture and target ports]
         GW[Client gateway<br/>current: five Armv8-M CMSE veneers]
         ARCH[Architecture adapter<br/>current: Armv8-M]
-        TARGET[Target and board port<br/>current: STM32H563]
+        TARGET[Target and board port<br/>STM32H563 or MIMXRT700]
         GW --- ARCH
         ARCH --- TARGET
     end
 
     subgraph WT[wolfTrust policy and service runtime]
         SPM[Secure Partition Manager<br/>policy, identity, IPC, scheduling, lifecycle, recovery]
         subgraph SP[Secure services]
-            CR["Cryptography and hardware<br/>security module (HSM)"]
+            CR["Secure crypto and optional<br/>wolfHSM server"]
             ST["Internal Trusted Storage (ITS),<br/>Protected Storage, and vault"]
             AT[Initial Attestation]
             FW[Firmware Update]
@@ -52,7 +48,7 @@ flowchart TB
 
     subgraph LIBS[wolfSSL ecosystem components]
         PSA[wolfPSA<br/>guest wolfCrypt and wolfHSM client]
-        WC[Secure wolfCrypt and wolfHSM]
+        WC[Secure wolfCrypt<br/>optional wolfHSM server]
         COSE[wolfCOSE]
         HAL[wolfHAL]
         IP[wolfIP<br/>optional bare-metal reference networking]
@@ -64,8 +60,8 @@ flowchart TB
     GA -->|PSA Crypto| PSA
     GB -->|PSA Crypto| PSA
     PSA -->|protected operations over FF-M| GW
-    GA -->|optional networking| IP
-    GB -->|optional networking| IP
+    GA -->|bare-metal VNET guest only| IP
+    GB -->|bare-metal VNET guest only| IP
     IP -->|VNet service over FF-M| GW
     GW -->|validated requests| SPM
     SPM -->|Secure execution operations| ARCH
@@ -77,13 +73,17 @@ flowchart TB
     TARGET -->|current register and RNG access| HAL
 ```
 
+The optional wolfIP/VNET reference uses separate bare-metal guests, not the
+Zephyr and FreeRTOS PSA guest pair.
+
 ### Current reference port
 
 On the STM32H563 reference chain, wolfBoot authenticates wolfTrust, Armv8-M
 TrustZone isolates the Secure runtime from Non-secure guests, and STM32 Global
 TrustZone Controller (GTZC) memory attribution isolates guest RAM. Zephyr and
 FreeRTOS reference guests use wolfPSA's PSA Crypto API through five Cortex-M
-Security Extensions (CMSE) gateway veneers. Those mechanisms describe the
+Security Extensions (CMSE) gateway veneers. The Secure side meets PSA FF-M
+isolation level 3 ([Security Model](docs/Security-Model.md#ff-m-isolation-level-3)). Those mechanisms describe the
 current reference port, not a requirement imposed on every intended port.
 
 ## Ports
@@ -94,25 +94,22 @@ first-stage loader contract, and the runners:
 - STM32H563 (NUCLEO-H563ZI): [STM32H5 Guide](docs/STM32H5-Guide.md)
 - NXP MIMXRT700 (MIMXRT700-EVK): [MIMXRT700 Guide](docs/MIMXRT700-Guide.md)
 
-Both build with `TARGET=<port>` (`stm32h563` is the default) and run the
-same scenario set under the M33MU emulator with `make test-target
-TARGET=<port>`.
+Both build with `TARGET=<port>` (`stm32h563` is the default). Each runs its
+own smoke scenario set under M33MU with `make test-target TARGET=<port>`.
 
 ## Quick start
 
 For the initial Secure build and host tests, install GNU Make, Python 3, Git, a
-native C compiler, and an `arm-none-eabi-` toolchain. Configure GitHub SSH
-access before cloning because three configured submodule URLs use SSH. Guest
-setup, conformance tests, emulator runs, and fresh hardware builds require
-network access. See [Getting Started](docs/Getting-Started.md) for additional
-emulator and hardware prerequisites.
-
-The repository currently requires authorized GitHub access.
+native C compiler, and an `arm-none-eabi-` toolchain. The repository and its
+submodules use public HTTPS URLs; GitHub SSH setup is not required. Guest
+builds also need CMake and Ninja; target tests need M33MU or a provisioned
+NUCLEO-H563ZI with ST-Link, and the published hardware workflow uses Docker.
+These workflows may fetch dependencies on first use. See
+[Getting Started](docs/Getting-Started.md) for the full prerequisites.
 
 ```sh
 git clone --recurse-submodules https://github.com/wolfSSL/wolfTrust.git
 cd wolfTrust
-git submodule update --init --recursive
 make
 make test
 ```
@@ -159,12 +156,17 @@ The version-controlled documentation in [`docs/`](docs/) is the primary
 documentation source:
 
 - [Getting Started](docs/Getting-Started.md)
+- [Ports and supported targets](docs/Targets.md)
+- [MIMXRT700 Guide](docs/MIMXRT700-Guide.md)
 - [Architecture](docs/Architecture.md)
 - [Security Model](docs/Security-Model.md)
 - [Threat Model](docs/Threat-Model.md)
 - [API Reference](docs/API-Reference.md)
 - [Services](docs/Services.md)
-- [TF-M Compatibility](docs/TF-M-Compatibility.md)
+- [Standards and Claims](docs/Standards.md)
+- [FF-M Compatibility](docs/FF-M-Compatibility.md)
+- [PSA Compatibility](docs/PSA-Compatibility.md)
+- [Footprint Comparison](docs/Footprint-Comparison.md)
 - [Macros](docs/Macros.md)
 - [Porting](docs/Porting.md)
 - [Building](docs/Building.md)
@@ -181,8 +183,10 @@ The source tree is authoritative:
 | `port/` | Target policy, memory layout, flash, entropy, and hardware enforcement |
 | `mk/` | Build configuration and linked-image checks |
 
-When enabled, the GitHub wiki is generated from the Markdown sources in
-`docs/`.
+`mkdocs.yml` defines the manual navigation. The shared
+[`wolfSSL/documentation`](https://github.com/wolfSSL/documentation) tooling
+builds HTML and PDF from these pages. [DOCS-BUILD.md](DOCS-BUILD.md) explains
+local previews and how merged changes reach the website.
 
 ## License