Add wolfHSM cert chain verification for ECC and RSA

Author: bigbrett

.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 --cert ../../../../wolfboot_signing_cert_chain.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

Makefile

@@ -229,6 +229,7 @@ $(PRIVATE_KEY):
 	$(Q)(test $(SIGN) = NONE) || ($(SIGN_ENV) "$(KEYGEN_TOOL)" $(KEYGEN_OPTIONS) -g $(PRIVATE_KEY)) || true
 	$(Q)(test $(SIGN) = NONE) && (echo "// SIGN=NONE" >  src/keystore.c) || true
 	$(Q)(test "$(FLASH_OTP_KEYSTORE)" = "1") && (make -C tools/keytools/otp) || true
+	$(Q)(test $(SIGN) = NONE) || (test "$(CERT_CHAIN_VERIFY)" = "") || (test "$(CERT_CHAIN_GEN)" = "") || (tools/scripts/sim-gen-dummy-chain.sh --algo $(CERT_CHAIN_GEN_ALGO) --leaf $(PRIVATE_KEY))
 
 $(SECONDARY_PRIVATE_KEY): $(PRIVATE_KEY) keystore.der
 	$(Q)$(MAKE) keytools_check
@@ -390,6 +391,7 @@ utilsclean: clean
 
 keysclean: clean
 	$(Q)rm -f *.pem *.der tags ./src/*_pub_key.c ./src/keystore.c include/target.h
+	$(Q)(test "$(CERT_CHAIN_GEN)" = "") || rm -rf test-dummy-ca || true
 
 distclean: clean keysclean utilsclean
 	$(Q)rm -f *.bin *.elf

config/examples/sim-wolfHSM-certchain.config

@@ -0,0 +1,39 @@
+ARCH=sim
+TARGET=sim
+SIGN?=ECC256
+HASH?=SHA256
+WOLFBOOT_SMALL_STACK?=0
+SPI_FLASH=0
+DEBUG=1
+
+# Cert chain options
+CERT_CHAIN_VERIFY=1
+CERT_CHAIN_GEN=1
+
+# Ensure header is large enough to hold the cert chain (check sign tool output)
+# for actual length
+IMAGE_HEADER_SIZE=2048
+
+# If SIGN=RSA4096, use the below options
+#WOLFBOOT_HUGE_STACK=1
+#IMAGE_HEADER_SIZE=4096
+
+# wolfHSM options
+WOLFHSM_CLIENT=1
+
+# sizes should be multiple of system page size
+#WOLFBOOT_PARTITION_SIZE=0x40000
+WOLFBOOT_PARTITION_SIZE=0x100000
+WOLFBOOT_SECTOR_SIZE=0x1000
+WOLFBOOT_PARTITION_BOOT_ADDRESS=0x80000
+# if on external flash, it should be multiple of system page size
+#WOLFBOOT_PARTITION_UPDATE_ADDRESS=0x100000
+#WOLFBOOT_PARTITION_SWAP_ADDRESS=0x180000
+WOLFBOOT_PARTITION_UPDATE_ADDRESS=0x180000
+WOLFBOOT_PARTITION_SWAP_ADDRESS=0x280000
+
+# required for keytools
+WOLFBOOT_FIXED_PARTITIONS=1
+
+# For debugging XMALLOC/XFREE
+#CFLAGS_EXTRA+=-DWOLFBOOT_DEBUG_MALLOC

docs/Signing.md

@@ -119,6 +119,14 @@ If none of the following is used, '--sha256' is assumed by default.
 
   * `--sha3` Use sha3-384 for digest calculation on binary images and public keys.
 
+#### Certificate Chain Options
+
+wolfBoot also supports verifying firmware images using certificate chains instead of raw public keys. In this mode of operation, a certificate chain is included in the image manifest header, and the image is signed with the private key corresponding to the leaf certificate identity (signer cert). On boot, wolfBoot verifies the trust of the certificate chain (and therefore the signer cert) against a trusted root CA stored in the wolfHSM server, and if the chain is trusted, verifies the authenticity of the firmware image using the public key from the image signer certificate.
+
+To generate an image for use with this mode, pass the `--cert-chain CERT_CHAIN.der` option to the sign tool, where `CERT_CHAIN.der` is a der encoded certificate chain containing one or more certificates in SSL order (leaf/signer cert last). Note that the sign tool still expects a signing private key to be provided as described above, and assumes that the public key of the signer cert in the chain corresponds to the signing private key.
+
+Certificate chain verification of images is currently limited to use in conjuction with wolfHSM. See [wolfHSM.md](wolfHSM.md) for more details.
+
 #### Target partition id (Multiple partition images, "self-update" feature)
 
 If none of the following is used, "--id=1" is assumed by default. On systems
@@ -257,7 +265,7 @@ For a real-life example, see the section below.
 ./tools/keytools/sign --rsa2048 --sha256 test-app/image.bin wolfboot_signing_private_key.der 1
 ```
 
-Note: The last argument is the “version” number.
+Note: The last argument is the "version" number.
 
 ### Signing Firmware with External Private Key (HSM)
 

docs/firmware_update.md

@@ -221,3 +221,26 @@ Note: When using scattered ELF images, ensure that:
 
 - The ELF file adheres to the ELF file specification and was generated by a toolchain supporting the target architecture
 - All section addresses are within valid executable memory regions and **do not overlap with the wolfBoot image, nor the BOOT, UPDATE and SWAP partitions**.
+
+## Certificate Verification
+
+wolfBoot supports authenticating images using certificate chains instead of raw public keys. in this mode of operation, a certificate chain is included in the image manifest header, and the image is signed with the private key corresponding to the leaf certificate identity (signer cert). On boot, wolfBoot verifies the trust of the certificate chain (and therefore the signer cert) against a trusted root CA stored in the wolfHSM server, and if the chain is trusted, verifies the authenticity of the firmware image using the public key from the image signer certificate.
+
+To use this feature:
+
+1. Enable the feature in your wolfBoot configuration by defining `WOLFBOOT_CERT_CHAIN_VERIFY`
+2. When signing firmware, include the certificate chain using the `--cert-chain` option:
+
+```sh
+./tools/keytools/sign --rsa2048 --sha256 --cert-chain cert_chain.der test-app/image.bin private_key.der 1
+```
+
+When verifying firmware, wolfBoot will:
+
+1. Extract the certificate chain from the firmware header
+2. Verify the chain using the pre-provisioned root certificate
+3. Use the public key from the leaf certificate to verify the firmware signature
+
+This feature is particularly useful in scenarios where you want to rotate signing keys without updating the bootloader, as you can simply resign the image with a new key, create a new certificate chain, then update the certificate chain in the firmware header.
+
+Note: Currently, support for certificate verification is limited to use in conjuction with wolfHSM. Fore more information see [wolfHSM.md](wolfHSM.md).

docs/wolfHSM.md

@@ -31,6 +31,34 @@ wolfBoot supports using wolfHSM for the following algorithms:
 
 Encrypted images with wolfHSM is not yet supported in wolfBoot. Note that every HAL target may not support all of these algorithms. Consult the platform-specific wolfBoot documentation for details.
 
+## Additional Features
+
+wolfBoot with wolfHSM also supports the following features:
+
+### Certificate Verification
+
+wolfBoot with wolfHSM supports certificate chain verification for firmware images. In this mode, instead of using raw public keys for signature verification, wolfBoot verifies firmware images using wolfHSM with a public key embedded in a certificate chain that is included in the image manifest header.
+
+The certificate verification process with wolfHSM works as follows:
+
+1. A root CA is created serving as the root of trust for the entire PKI system
+2. A signing keypair and corresponding identity certificate is created for signing firmware images
+3. The firmware image is signed with the signing private key
+4. A certificate chain is created consisting of the signing identity certificate and an optional number of intermediate certificates, where trust is chained back to the root CA.
+5. During the signing process, the image is signed with the signer private key and the certificate chain is embedded in the firmware image header.
+6. During boot, wolfBoot extracts the certificate chain from the firmware header
+7. wolfBoot uses the wolfHSM server to verify the certificate chain against a pre-provisioned root CA certificate stored on the HSM and caches the public key of the leaf certificate if the chain verifies as trusted
+8. If the chain is trusted, wolfBoot uses the cached public key from the leaf certificate to verify the firmware signature on the wolfHSM server
+
+To use certificate verification with wolfHSM:
+
+1. Enable `WOLFBOOT_CERT_CHAIN_VERIFY` in your wolfBoot configuration
+2. Ensure the wolfHSM server is configured with certificate manager support (`WOLFHSM_CFG_CERTIFICATE_MANAGER`)
+3. Pre-provision the root CA certificate on the wolfHSM server at the NVM ID specified by the HAL `hsmClientNvmIdCertRootCA`
+4. Sign firmware images with the `--cert-chain` option, providing a DER-encoded certificate chain
+
+To build the simulator using wolfHSM for certificate verification, use [config/examples/sim-wolfHSM-certchain.config](config/examples/sim-wolfHSM-certchain.config).
+
 ## Configuration Options
 
 This section describes the configuration options available for wolfHSM client integration. Note that these options should be configured automatically by the build system for each supported platform when wolfHSM support is enabled. Consult the platform-specific documentation for details on enabling wolfHSM support.

hal/sim.c

@@ -100,6 +100,9 @@ const int       hsmClientKeyIdPubKey = 0xFF;
 const int       hsmClientDevIdCrypt = WH_DEV_ID;
 const int       hsmClientKeyIdCrypt = 0xFF;
 #endif
+#ifdef WOLFBOOT_CERT_CHAIN_VERIFY
+const int       hsmClientNvmIdCertRootCA = 1;
+#endif
 
 int hal_hsm_init_connect(void);
 int hal_hsm_disconnect(void);

include/hal.h

@@ -161,6 +161,10 @@ extern const int hsmClientKeyIdPubKey; /* KeyId for public key operations */
 #ifdef EXT_ENCRYPTED
 extern const int hsmClientKeyIdCrypt; /* KeyId for image (enc/dec)ryption */
 #endif
+#ifdef WOLFBOOT_CERT_CHAIN_VERIFY
+/* NvmId for trusted root CA certificate */
+extern const whNvmId hsmClientNvmIdCertRootCA;
+#endif
 
 /* Implementation of functions provided by HAL */
 int hal_hsm_init_connect(void);

include/wolfboot/wolfboot.h

@@ -79,6 +79,7 @@ extern "C" {
 #define HDR_SIGNATURE               0x20
 #define HDR_POLICY_SIGNATURE        0x21
 #define HDR_SECONDARY_SIGNATURE     0x22
+#define HDR_CERT_CHAIN              0x23
 #define HDR_PADDING                 0xFF
 
 /* Auth Key types */