Simplify use of user-supplied keys and certificates with test app via

new `USER_ variables`

Author: bigbrett

Makefile

@@ -40,16 +40,61 @@ ifneq ($(TARGET),library)
 	OBJS+=./hal/$(TARGET).o
 endif
 
+# User-provided key configuration
+# - USER_PRIVATE_KEY: Path to user's private key (DER format)
+# - USER_PUBLIC_KEY: Path to user's public key (DER format)
+# - USER_CERT_CHAIN: Path to user's certificate chain (DER format)
+# All must be provided together, or none at all
+
+# Validate USER_PRIVATE_KEY and USER_PUBLIC_KEY are used together
+ifneq ($(USER_PRIVATE_KEY),)
+  ifeq ($(USER_PUBLIC_KEY),)
+    $(error USER_PRIVATE_KEY requires USER_PUBLIC_KEY to also be set)
+  endif
+  ifeq ($(wildcard $(USER_PRIVATE_KEY)),)
+    $(error USER_PRIVATE_KEY file not found: $(USER_PRIVATE_KEY))
+  endif
+endif
+
+ifneq ($(USER_PUBLIC_KEY),)
+  ifeq ($(USER_PRIVATE_KEY),)
+    $(error USER_PUBLIC_KEY requires USER_PRIVATE_KEY to also be set)
+  endif
+  ifeq ($(wildcard $(USER_PUBLIC_KEY)),)
+    $(error USER_PUBLIC_KEY file not found: $(USER_PUBLIC_KEY))
+  endif
+endif
+
+# Validate USER_CERT_CHAIN requires USER_PRIVATE_KEY and USER_PUBLIC_KEY
+ifneq ($(USER_CERT_CHAIN),)
+  ifeq ($(USER_PRIVATE_KEY),)
+    $(error USER_CERT_CHAIN requires USER_PRIVATE_KEY to also be set)
+  endif
+  ifeq ($(USER_PUBLIC_KEY),)
+    $(error USER_CERT_CHAIN requires USER_PUBLIC_KEY to also be set)
+  endif
+  ifeq ($(wildcard $(USER_CERT_CHAIN)),)
+    $(error USER_CERT_CHAIN file not found: $(USER_CERT_CHAIN))
+  endif
+endif
+
 ifeq ($(SIGN),NONE)
   PRIVATE_KEY=
 else
-  # Key selection logic:
-  # - Without CERT_CHAIN_GEN: Single key (wolfboot_signing_private_key.der) signs everything
-  # - With CERT_CHAIN_GEN: Generate cert chain, use leaf key (test-dummy-ca/leaf-prvkey.der) for signing
-  ifneq ($(CERT_CHAIN_GEN),)
-    PRIVATE_KEY=test-dummy-ca/leaf-prvkey.der
+  # Private Key selection logic:
+  # 1. User-provided private keys take precedence (USER_PRIVATE_KEY)
+  # 2. Otherwise, if CERT_CHAIN_VERIFY, use generated dummy cert chain leaf key
+  # 3. Otherwise use standard generated private key
+  ifneq ($(USER_PRIVATE_KEY),)
+    PRIVATE_KEY=$(USER_PRIVATE_KEY)
   else
-    PRIVATE_KEY=wolfboot_signing_private_key.der
+    ifneq ($(CERT_CHAIN_VERIFY),)
+      # Auto-generate cert chain mode - use leaf key
+      PRIVATE_KEY?=test-dummy-ca/leaf-prvkey.der
+    else
+      # No cert chain verification - standard single key mode
+      PRIVATE_KEY?=wolfboot_signing_private_key.der
+    endif
   endif
   ifeq ($(FLASH_OTP_KEYSTORE),1)
     OBJS+=./src/flash_otp_keystore.o
@@ -268,21 +313,31 @@ hal/$(TARGET).o:
 
 keytools_check: keytools
 
-# Generate the initial signing key
-# - Always creates wolfboot_signing_private_key.der
-# - If CERT_CHAIN_GEN is set, also generates cert chain with leaf key
+# Generate the initial signing key (only if not using user-provided keys)
+# - Creates wolfboot_signing_private_key.der when USER_PRIVATE_KEY is not set
+# - If CERT_CHAIN_VERIFY is enabled and USER_CERT_CHAIN not provided, also generates cert chain with leaf key
 wolfboot_signing_private_key.der:
+ifeq ($(USER_PRIVATE_KEY),)
 	$(Q)$(MAKE) keytools_check
 	$(Q)(test $(SIGN) = NONE) || ($(SIGN_ENV) "$(KEYGEN_TOOL)" $(KEYGEN_OPTIONS) -g wolfboot_signing_private_key.der) || 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 wolfboot_signing_private_key.der)
+	$(Q)(test $(SIGN) = NONE) || (test "$(CERT_CHAIN_VERIFY)" = "") || (test "$(USER_CERT_CHAIN)" != "") || (tools/scripts/sim-gen-dummy-chain.sh --algo $(CERT_CHAIN_GEN_ALGO) --leaf wolfboot_signing_private_key.der)
+else
+	@echo "Using user-provided private key: $(USER_PRIVATE_KEY)"
+endif
 
-# CERT_CHAIN_GEN only: Ensure leaf key exists after cert chain generation
-ifneq ($(CERT_CHAIN_GEN),)
+# Auto-generate cert chain mode: Ensure leaf key exists after cert chain generation
+# Only applies when CERT_CHAIN_VERIFY is enabled and USER_CERT_CHAIN not provided
+# Skip this when using user-provided keys
+ifeq ($(USER_PRIVATE_KEY),)
+ifneq ($(CERT_CHAIN_VERIFY),)
+ifeq ($(USER_CERT_CHAIN),)
 $(PRIVATE_KEY): wolfboot_signing_private_key.der
 	@test -f $(PRIVATE_KEY) || (echo "Error: $(PRIVATE_KEY) not found" && exit 1)
 endif
+endif
+endif
 
 $(SECONDARY_PRIVATE_KEY): $(PRIVATE_KEY) keystore.der
 	$(Q)$(MAKE) keytools_check
@@ -435,7 +490,15 @@ srec: wolfboot.srec
 	@echo "\t[ELF2SREC] $@"
 	@$(OBJCOPY) -O srec $^ $@
 
+# Keystore generation: use user-provided public key if available
+ifneq ($(USER_PUBLIC_KEY),)
+src/keystore.c: $(USER_PUBLIC_KEY)
+	@echo "Generating keystore from user-provided public key: $(USER_PUBLIC_KEY)"
+	$(Q)$(MAKE) keytools_check
+	$(Q)$(SIGN_ENV) "$(KEYGEN_TOOL)" $(KEYGEN_OPTIONS) --force -i $(USER_PUBLIC_KEY)
+else
 src/keystore.c: $(PRIVATE_KEY)
+endif
 
 flash_keystore: src/flash_otp_keystore.o
 
@@ -479,7 +542,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
+	$(Q)(test "$(CERT_CHAIN_VERIFY)" = "" || test "$(USER_CERT_CHAIN)" != "") || rm -rf test-dummy-ca || true
 
 distclean: clean keysclean utilsclean
 	$(Q)rm -f *.bin *.elf

arch.mk

@@ -1163,6 +1163,14 @@ ifeq ($(ARCH),sim)
                     $(WOLFBOOT_LIB_WOLFHSM)/src/wh_transport_mem.o
 
   endif
+  # wolfHSM NVM image generation support for simulator
+  # User must provide NVM_CONFIG for their specific setup
+  ifneq ($(filter 1,$(WOLFHSM_CLIENT) $(WOLFHSM_SERVER)),)
+    WH_NVM_BIN ?= whNvmImage.bin
+    WH_NVM_HEX ?= whNvmImage.hex
+    WH_NVM_PART_SIZE ?= 16384 # must match partition size in hal/sim.c
+    WH_NVM_BASE_ADDRESS ?= 0x0
+  endif
 endif
 
 # Infineon AURIX Tricore
@@ -1204,10 +1212,11 @@ ifeq ($(ARCH), AURIX_TC3)
       WH_NVM_BASE_ADDRESS ?= 0xAFC00000
 
       # Select config file based on certificate chain verification
+      # Use ?= to allow user override via command line (e.g., for offline cert chain)
       ifneq ($(CERT_CHAIN_VERIFY),)
-        NVM_CONFIG = tools/scripts/tc3xx/wolfBoot-wolfHSM-dummy-certchain.nvminit
+        NVM_CONFIG ?= tools/scripts/tc3xx/wolfBoot-wolfHSM-dummy-certchain.nvminit
       else
-        NVM_CONFIG = tools/scripts/tc3xx/wolfBoot-wolfHSM-keys.nvminit
+        NVM_CONFIG ?= tools/scripts/tc3xx/wolfBoot-wolfHSM-keys.nvminit
       endif
     endif
 

config/examples/aurix-tc375-elf-wolfHSM-certs.config

@@ -26,7 +26,6 @@ ELF_FLASH_SCATTER=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

config/examples/aurix-tc375-hsm-wolfHSM-certs.config

@@ -23,7 +23,6 @@ WOLFHSM_SERVER=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

config/examples/sim-wolfHSM-client-certchain.config

@@ -9,7 +9,6 @@ SPMATH=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

config/examples/sim-wolfHSM-server-certchain.config

@@ -9,7 +9,6 @@ SPMATH=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

docs/Signing.md

@@ -128,6 +128,25 @@ wolfBoot also supports verifying firmware images using certificate chains instea
 
 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.
 
+When building wolfBoot and the test app with the Makefile, certificate chain signing can be configured using the following variables:
+
+- `CERT_CHAIN_VERIFY=1`: Enables certificate chain verification mode
+- `USER_PRIVATE_KEY`: Path to your leaf signing key (DER format)
+- `USER_PUBLIC_KEY`: Path to your leaf public key (DER format)
+- `USER_CERT_CHAIN`: Path to your certificate chain (DER format)
+
+Example:
+
+```sh
+make CERT_CHAIN_VERIFY=1 \
+     USER_PRIVATE_KEY=my-leaf-private-key.der \
+     USER_PUBLIC_KEY=my-leaf-pubkey.der \
+     USER_CERT_CHAIN=my-cert-chain.der
+```
+Note that it is up to the user to guarantee that `USER_PUBLIC_KEY` and `USER_PRIVATE_KEY` both correspond to the leaf certificate identity in the chain.
+
+If `USER_CERT_CHAIN` is not provided when `CERT_CHAIN_VERIFY=1`, a dummy certificate hierarchy is auto-generated for testing. See the [Compiling wolfBoot](compile.md#key-generation-and-signing) documentation for full details on these options.
+
 Certificate chain verification of images is currently limited to use in conjunction with wolfHSM. See [wolfHSM.md](wolfHSM.md) for more details.
 
 #### Target partition id (Multiple partition images, "self-update" feature)

docs/compile.md

@@ -355,3 +355,82 @@ Available overrides:
 - `WOLFBOOT_LIB_WOLFTPM`: Path to the [wolfTPM](https://github.com/wolfSSL/wolfTPM) library source code
 - `WOLFBOOT_LIB_WOLFPKCS11`: Path to the [wolfPKCS11](https://github.com/wolfssl/wolfpkcs11) library source code
 - `WOLFBOOT_LIB_WOLFHSM`: Path to the [wolfHSM](https://github.com/wolfSSL/wolfHSM) library source code
+
+## Key Generation and Signing
+
+### Default Key Behavior
+
+When building wolfBoot for the first time, the build system automatically generates the cryptographic keys needed for firmware signing and verification.
+
+- **Private Key**: `wolfboot_signing_private_key.der` - Used to sign firmware images
+- **Keystore**: `src/keystore.c` - Contains the public key embedded in the bootloader
+
+The key algorithm is determined by the `SIGN` variable (e.g., `SIGN=ECC256`, `SIGN=RSA2048`).
+
+For most targets, the makefile also builds the wolfBoot test app and signs it with the aforementioned key.
+
+### User-Provided Keys
+
+Instead of auto-generating keys, you can provide your own pre-existing keys for use with the test app by using the following Makefile variables:
+
+- `USER_PRIVATE_KEY`: Path to your private signing key (DER format)
+- `USER_PUBLIC_KEY`: Path to your public key (DER format)
+
+**Usage:**
+
+```sh
+make USER_PRIVATE_KEY=/path/to/my-signing-key.der \
+     USER_PUBLIC_KEY=/path/to/my-public-key.der
+```
+
+#### Requirements
+
+- Both `USER_PRIVATE_KEY` and `USER_PUBLIC_KEY` must be provided together. You cannot supply one without the other.
+- Keys must be in DER format appropriate for the selected `SIGN` algorithm
+
+When user-provided keys are specified:
+
+1. The build skips auto-generation of `wolfboot_signing_private_key.der`
+2. The keystore (`src/keystore.c`) is generated from your public key
+3. Your private key is used for all signing operations
+
+The `USER_` variables are meant to simplify the wolfBoot "demo" behavior where wolfBoot boots a simple test app.
+
+### User-Provided Certificate Chain
+
+When using certificate chain verification (`CERT_CHAIN_VERIFY=1`), you can also provide your own certificate chain:
+
+- `USER_CERT_CHAIN`: Path to your certificate chain (DER format, wolfHSM order with leaf last)
+
+**Usage:**
+
+```sh
+make CERT_CHAIN_VERIFY=1 \
+     USER_PRIVATE_KEY=/path/to/leaf-signing-key.der \
+     USER_PUBLIC_KEY=/path/to/leaf-public-key.der \
+     USER_CERT_CHAIN=/path/to/my-cert-chain.der
+```
+
+**Requirements:**
+
+- `USER_CERT_CHAIN` requires both `USER_PRIVATE_KEY` and `USER_PUBLIC_KEY` to be set
+- The user-supplied private and public keys must correspond to the identity of the leaf certificate in the chain
+
+When `CERT_CHAIN_VERIFY=1` is set without `USER_CERT_CHAIN`, the build system auto-generates a dummy 3-tier certificate hierarchy (root CA, intermediate, and leaf) in the `test-dummy-ca/` directory for testing purposes. This is then used to sign the test app.
+
+### Manual Key Generation
+
+As an alternative to the `USER_*` variables, you can manually fulfill the build dependencies:
+
+1. **Generate or import your keystore manually:**
+   ```sh
+   ./tools/keytools/keygen --ecc256 -i my-public-key.der
+   ```
+   This creates `src/keystore.c` from your public key.
+
+2. **Place your signing key at the expected location:**
+   ```sh
+   cp my-private-key.der wolfboot_signing_private_key.der
+   ```
+
+The build system will detect these existing files and skip auto-generation when make is subsequently invoked. This approach is required when more advanced options like multiple public keys in the keystore are required. In these cases, the keystore generation using the keygen tool and image signing via the sign tool must be performed manually.

docs/keystore.md

@@ -221,3 +221,13 @@ Returns the permissions mask, as a 32-bit word, for the public key stored in the
 wolfBoot supports certain platforms that contain connected HSMs (Hardware Security Modules) that can provide cryptographic services using keys that are not stored in the device NVM or readable by wolfBoot, for example, wolfHSM. In these scenarios, wolfBoot key tools should be used to generate the keys, which can then be manually loaded into the HSM (see [--exportpubkey](#exporting-the-public-key-to-a-file)). At runtime, wolfBoot will still use the keystore to obtain information about the public keys, specifically the size of the key and the key type, but does not need access to the actual key material.
 
 To support this mode of operation, the `keygen` tool supports the `--nolocalkeys` option, which instructs the tool to generate a keystore entry with a zeroed key material. It still generates the `.der` files for private and public keys, so the wolfBoot key tools can sign images, but the `keystore.c` file that is linked into wolfBoot will contain all zeros in the `pubkey` field. Because the key material isn't present in the keystore, the keypair used to sign the image and stored on the HSM for verification can be updated in the field without needing to rebuild wolfBoot against a new `keystore.c`, as long as the signature algorithm and key size does not change. Most targets that use this option will automatically add it to the key generation options or explicitly mention this step in the build documentation.
+
+## Using User-Provided Keys with the Keystore and Build System
+
+By default, when running `make` for the first time, wolfBoot automatically generates:
+- A signing keypair at `wolfboot_signing_private_key.der`
+- The keystore module at `src/keystore.c` containing the corresponding public key
+
+This default behavior can be overridden using the `USER_PRIVATE_KEY` and `USER_PUBLIC_KEY` Makefile variables, allowing you to use externally-managed keys for building the test application and keystore.
+
+See [compile.md](./compile.md#key-generation-and-signing) for more information

include/user_settings.h

@@ -214,7 +214,9 @@ extern int tolower(int c);
 #   define WC_RSA_DIRECT
 #   define RSA_LOW_MEM
 #   define WC_ASN_HASH_SHA256
-#   if !defined(WOLFBOOT_TPM) && !defined(WOLFCRYPT_SECURE_MODE)
+#   if !defined(WOLFBOOT_TPM) && !defined(WOLFCRYPT_SECURE_MODE) && \
+       !defined(WOLFBOOT_ENABLE_WOLFHSM_CLIENT) && \
+       !defined(WOLFBOOT_ENABLE_WOLFHSM_SERVER)
 #       define WOLFSSL_RSA_VERIFY_INLINE
 #       define WOLFSSL_RSA_VERIFY_ONLY
 #       define WOLFSSL_RSA_PUBLIC_ONLY
@@ -585,6 +587,7 @@ extern int tolower(int c);
 #   define WOLFSSL_USER_IO
 #   define WOLFSSL_SP_MUL_D
 #   define WOLFSSL_PEM_TO_DER
+#   define WOLFSSL_ALLOW_NO_SUITES
 #endif
 
 #ifdef WOLFSSL_STM32_PKA