Merge pull request #574 from bigbrett/wolfhsm-cert-verify

Add cert chain verification via wolfHSM on sim and TC3xx

Author: dgarske

.github/workflows/test-wolfhsm-simulator.yml

@@ -18,6 +18,8 @@ jobs:
             file: "config/examples/sim-wolfHSM.config"
           - name: "wolfHSM ML-DSA"
             file: "config/examples/sim-wolfHSM-mldsa.config"
+          - name: "wolfHSM cert chain verify"
+            file: "config/examples/sim-wolfHSM-certchain.config"
       fail-fast: false
 
     runs-on: ubuntu-latest
@@ -54,8 +56,7 @@ jobs:
         with:
           repository: wolfssl/wolfHSM-examples
           # Make sure to update this when the wolfHSM submodule is updated!
-          #ref: wolfHSM-v1.1.0
-          ref: 3e03bd4d4a8439ed4a8a9577823c89e4c37eb9be
+          ref: wolfHSM-examples-v1.2.0
           path: wolfHSM-examples
 
       - name: Build example POSIX TCP server
@@ -65,7 +66,13 @@ jobs:
       - name: Run POSIX TCP server
         run: |
           cd wolfHSM-examples/posix/tcp/wh_server_tcp
-          ./Build/wh_server_tcp.elf --client 12 --id 255 --key ../../../../wolfboot_signing_private_key_pub.der  &
+          if [ "${{ matrix.config.name }}" = "wolfHSM cert chain verify" ]; then
+            tmpfile=$(mktemp)
+            echo "obj 1 0xFFFF 0x0000 \"cert CA\" ../../../../test-dummy-ca/root-cert.der" >> $tmpfile
+            ./Build/wh_server_tcp.elf --nvminit $tmpfile &
+          else
+            ./Build/wh_server_tcp.elf --client 12 --id 255 --key ../../../../wolfboot_signing_private_key_pub.der &
+          fi
           TCP_SERVER_PID=$!
           echo "TCP_SERVER_PID=$TCP_SERVER_PID" >> $GITHUB_ENV
 

.gitignore

@@ -99,6 +99,7 @@ include/target.h
 .wolfboot-partition-size
 .bootloader-partition-size
 MPLabX/wolfBoot-SAME51.X/.generated_files/
+test-dummy-ca/**
 
 # Test tools
 tools/check_config/check_config

IDE/AURIX/README.md

@@ -10,6 +10,7 @@ This example demonstrates using wolfBoot on the Infineon AURIX TC3xx family of m
   - [Flash Partitioning](#flash-partitioning)
     - [Standard wolfBoot images](#standard-wolfboot-images)
     - [ELF files](#elf-files)
+    - [Cert Chain Verification](#cert-chain-verification)
   - [Configuration and the wolfBoot AURIX tool (wbaurixtool.sh)](#configuration-and-the-wolfboot-aurix-tool-wbaurixtoolsh)
   - [Building and running the wolfBoot demo](#building-and-running-the-wolfboot-demo)
     - [Prerequisites](#prerequisites)
@@ -23,6 +24,9 @@ This example demonstrates using wolfBoot on the Infineon AURIX TC3xx family of m
     - [Load and run the wolfBoot demo in TRACE32](#load-and-run-the-wolfboot-demo-in-trace32)
   - [wolfHSM Compatibility](#wolfhsm-compatibility)
     - [Building wolfBoot with wolfHSM](#building-wolfboot-with-wolfhsm)
+    - [Building wolfBoot with wolfHSM and cert chain verification](#building-wolfboot-with-wolfhsm-and-cert-chain-verification)
+    - [Custom Certificate Chain](#custom-certificate-chain)
+    - [Dummy Certificate Chain](#dummy-certificate-chain)
   - [Building: Command Sequence](#building-command-sequence)
   - [Troubleshooting](#troubleshooting)
     - [WSL "bad interpreter" error](#wsl-bad-interpreter-error)
@@ -95,6 +99,10 @@ Different linker script templates are used to configure the memory layout via `w
 - [test-app (standard wolfBoot images)](test-app/Lcf_Gnu_Tricore_Tc.lsl.in)
 - [test-app (ELF files)](test-app/Lcf_Gnu_Tricore_elf.lsl.in)
 
+### Cert Chain Verification
+
+wolfBoot on AURIX supports verifying firmware images using certificate chains. For more information on how this wolfBoot feature works, refer to [Signing.md](../../docs/Signing.md), [firmware_update.md](../docs/firmware_update.md), and [wolfBoot-wolfHSM](../../IDE/AURIX/wolfBoot-wolfHSM). Currently this feature can only be used in conjunction with wolfHSM. Instructions for using this feature are detailed below in the [Building wolfBoot with wolfHSM](#building-wolfboot-with-wolfhsm) section.
+
 ## Configuration and the wolfBoot AURIX tool (wbaurixtool.sh)
 
 wolfBoot relies extensively on its build system in order to properly set configuration macros, linker addresses, and other target-specific items. Because wolfBoot on AURIX uses the AURIX studio IDE to build, changing things like the signature algorithm would require manually editing IDE settings, linker scripts, etc. which is error prone and tedious. The `wbaurixtool.sh` script provides a single tool that automates the generation of all configurable items required for building wolfBoot and the test application on AURIX given the chosen signature and hashing algorithms, including managing all configuration macros, linker scripts, as well as handling the actual key generation and image signing process. `wbaurixtool.sh` can also generate wolfHSM NVM images containing the generated image signing key when used in conjunction with wolfHSM.
@@ -320,6 +328,27 @@ IDE/AURIX/wolfHSM-infineon-tc3xx/
    3. Provide the `--hsm` global option to the `wbaurixtool.sh` script when invoking it so that the wolfHSM projects are used instead of the standard wolfBoot projects
    4. If using the default build options in [wolfBoot-tc3xx-wolfHSM](./wolfBoot-tc3xx-wolfHSM/), wolfBoot will expect the public key for image verification to be stored at a specific keyId for the wolfBoot client ID. You can use [whnvmtool](https://github.com/wolfSSL/wolfHSM/tree/main/tools/whnvmtool) to generate a loadable NVM image that contains the required keys automatically via `wbaurixtool.sh` through the `nvm` subcommand. This generates an NVM image containing the generated image signing key based on the [wolfBoot-wolfHSM-keys.nvminit](../../tools/scripts/tc3xx/wolfBoot-wolfHSM-keys.nvminit) configuration file, which can then be loaded to the device via a flash programming tool. Before using the `nvm` subcommand of `wbaurixtool.sh`, first compile `whnvmtool` by running `make` in the `lib/wolfHSM/tools/whnvmtool` directory. See the `whnvmtool` documentation and the documentation included in your wolfHSM AURIX release for more details. Note: if you want to use the standard wolfBoot keystore functionality in conjunction with wolfHSM for testing purposes (doesn't require pre-loading keys on the HSM) you can configure wolfBoot to send the keys to the HSM on-the-fly as ephemeral keys. To do this, ensure `WOLFBOOT_USE_WOLFHSM_PUBKEY_ID` is **NOT** defined, and add the `--localkeys` argument to then `./wbaurixtool.sh keygen` command, which invokes the `keygen` tool without the default `--nolocalkeys` option.
 
+### Building wolfBoot with wolfHSM and cert chain verification
+
+wolfBoot with wolfHSM supports certificate chain verification for firmware images. This feature allows wolfBoot to verify that firmware images are signed with certificates that can be traced back to a trusted root certificate authority through a certificate chain.
+
+The `wbaurixtool.sh` script provides two options for applicable commands that enable automation of configuring the build for certificate chain verification:
+
+- `--certchain <file>`: Use a user-provided certificate chain file
+- `--dummy-certchain`: Use a "dummy" certificate chain that is created from the key pair generated by the wolfBoot keytools for development/testing purposes.
+
+Both options require the `--hsm` global option and can be used with the `keygen`, `sign`, `macros`, `lcf`, and `nvm` subcommands.
+
+### Custom Certificate Chain
+
+If you want to use a custom certificate chain for verification, you can provide the `--certchain <certchain file>` option to the `macros`, `lcf`, and `sign` subcommands. This ensures that your certificate chain will be included in the generated firmware image and that wolfBoot will verify the chain on boot, then verify the signature of the firmware image using the public key corresponding to the leaf certificate in the chain. Note that the user is responsible for properly constructing the certificate chain and ensuring that the leaf certificate is bound to the firmware signing key pair, as well as properly provisioning the HSM with the root CA certificate at the expected NVM object ID specified by the HAL.
+
+### Dummy Certificate Chain
+
+If you just want to test out the certificate verifcation functionality, `wbaurixtool.sh` can generate and use a dummy certificate chain by   providing the `--dummy-certchain` option to the `keygen`, `sign`, `macros`, `lcf`, and `nvm` subcommands. This will cause the keygen step to generate a dummy root CA at `test-dummy-ca/root-ca.der`, well as a dummy certificate chain at `test-dummy-ca/raw-chain.der` using the specified algorithm. The generated chain consists of a single intermediate as well as a leaf (signing) certificate whose identity is bound to the generated firmware signing key pair. The subsequent commands will then ensure this generated chain is used by wolfBoot. Additionally, the `nvm` subcommand will create an NVM image containing the generated root CA that can be loaded into HSM NVM.
+
+**Note: The `--dummy-certchain` option is intended for development and testing. For production use, generate and use your own certificate chain.**
+
 ## Building: Command Sequence
 
 The following pseudo command sequence shows a brief overview of the commands needed to build wolfBoot on AURIX (optionally with wolfHSM). The signature and hashing algorithms used in the example are ECC 256 and SHA 256 and specified explicitly for clarity. Note that these algorithms are the default, so do not need to be explicitly specified. Optional arguments are shown in square brackets (e.g. if targeting wolfHSM, the `--hsm` option must be provided as a global option to `wbaurixtool.sh`).

IDE/AURIX/wolfBoot-tc3xx-wolfHSM/.cproject

@@ -7,4 +7,5 @@
 @ML_DSA_LEVEL@
 @ML_DSA_IMAGE_SIGNATURE_SIZE@
 @WOLFBOOT_ELF@
-@WOLFBOOT_ELF_FLASH_SCATTER@
+@WOLFBOOT_ELF_FLASH_SCATTER@
+@WOLFBOOT_CERT_CHAIN_VERIFY@

IDE/AURIX/wolfBoot-tc3xx-wolfHSM/wolfBoot_macros.in

@@ -26,5 +26,6 @@
 #define WOLFHSM_CFG_H_
 
 #define WOLFHSM_CFG_DMA
+#define WOLFHSM_CFG_CERTIFICATE_MANAGER
 
 #endif /* WOLFHSM_CFG_H_ */