update docs

Author: bigbrett

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,80 @@ 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 associated keys.
+
+### User-Provided Keys
+
+Instead of auto-generating keys, you can provide your own pre-existing keys 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 can not 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
+
+### 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.
+
+### Legacy Key and Keystore Generation Behavior
+
+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 subsequenly invoked.

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