Improve docs for USER_XXX variables to clarify intent

Author: bigbrett

docs/Signing.md

@@ -128,7 +128,7 @@ 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:
+When building wolfBoot and the test app with the Makefile, the `USER_*` variables provide a convenience for using your own locally-managed keys and certificate chain, avoiding manual `keygen -i` and file placement steps:
 
 - `CERT_CHAIN_VERIFY=1`: Enables certificate chain verification mode
 - `USER_PRIVATE_KEY`: Path to your leaf signing key (DER format)
@@ -143,9 +143,12 @@ make CERT_CHAIN_VERIFY=1 \
      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.
+Note that `USER_PUBLIC_KEY` and `USER_PRIVATE_KEY` must 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#pre-existing-local-keys-for-test-app-builds) documentation for full details on these options.
+
+**Note:** If your private key is managed by a third party and you only have access to the public key, use `keygen -i` to import it instead. See the [Keygen tool](#keygen-tool) section above.
 
 Certificate chain verification of images is currently limited to use in conjunction with wolfHSM. See [wolfHSM.md](wolfHSM.md) for more details.
 

docs/compile.md

@@ -369,9 +369,13 @@ The key algorithm is determined by the `SIGN` variable (e.g., `SIGN=ECC256`, `SI
 
 For most targets, the makefile also builds the wolfBoot test app and signs it with the aforementioned key.
 
-### User-Provided Keys
+### Pre-existing Local Keys for Test App Builds
 
-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:
+The `USER_*` Makefile variables provide a convenience for building the test app with your own locally-managed keys, avoiding the need to manually run `keygen -i` and place key files before building.
+
+**Note:** If your private key is managed by a third party (e.g., HSM-as-a-service, Azure KeyVault) and you only have access to the public key, use the `keygen -i` option instead. See [Signing.md](Signing.md#keygen-tool) and [Manual Key Management](#manual-key-management) below.
+
+The following variables are available:
 
 - `USER_PRIVATE_KEY`: Path to your private signing key (DER format)
 - `USER_PUBLIC_KEY`: Path to your public key (DER format)
@@ -385,22 +389,22 @@ make USER_PRIVATE_KEY=/path/to/my-signing-key.der \
 
 #### Requirements
 
-- Both `USER_PRIVATE_KEY` and `USER_PUBLIC_KEY` must be provided together. You cannot supply one without the other.
+- Both `USER_PRIVATE_KEY` and `USER_PUBLIC_KEY` must be provided together
 - Keys must be in DER format appropriate for the selected `SIGN` algorithm
 
-When user-provided keys are specified:
+When these variables are specified, the build:
 
-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
+1. Skips auto-generation of `wolfboot_signing_private_key.der`
+2. Generates the keystore (`src/keystore.c`) from your public key via `keygen -i`
+3. Uses your private key to sign the test app
 
-The `USER_` variables are meant to simplify the wolfBoot "demo" behavior where wolfBoot boots a simple test app.
+This is primarily useful when you want a single `make` invocation to build wolfBoot and a signed test app using keys you've generated externally. For wolfBoot-only builds (without the test app), the main benefit is automating the `keygen -i` step for simple single-key keystores. If you need multiple keys in the keystore then you must invoke `keygen -i` manually before building wolfBoot.
 
-### User-Provided Certificate Chain
+### Pre-existing Certificate Chain for Test App Builds
 
-When using certificate chain verification (`CERT_CHAIN_VERIFY=1`), you can also provide your own certificate chain:
+When building the test app using certificate chain verification (`CERT_CHAIN_VERIFY=1`), you can provide your own certificate chain:
 
-- `USER_CERT_CHAIN`: Path to your certificate chain (DER format, wolfHSM order with leaf last)
+- `USER_CERT_CHAIN`: Path to your certificate chain (DER format, leaf cert last)
 
 **Usage:**
 
@@ -413,24 +417,38 @@ make CERT_CHAIN_VERIFY=1 \
 
 **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
+- `USER_CERT_CHAIN` requires both `USER_PRIVATE_KEY` and `USER_PUBLIC_KEY`
+- The private and public keys must correspond to the leaf certificate identity in the chain
+
+When `CERT_CHAIN_VERIFY=1` is set without `USER_CERT_CHAIN`, the build auto-generates a dummy 3-tier certificate hierarchy in `test-dummy-ca/` for testing. This also applies to wolfHSM NVM image generation when applicable.
 
-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 Management
 
-### Manual Key Generation
+For advanced scenarios (multiple keys, mixed algorithms, partition-restricted keys, or third-party managed private keys), use the `keygen` tool directly instead of the `USER_*` variables.
 
-As an alternative to the `USER_*` variables, you can manually fulfill the build dependencies:
+**Importing a public key (when private key is externally managed):**
+
+```sh
+./tools/keytools/keygen --ecc256 -i my-public-key.der
+```
 
-1. **Generate or import your keystore manually:**
+This creates `src/keystore.c` from your public key. Signing must then be performed in two steps following the steps outlined in [Signing.md](./Signing.md#signing-firmware-with-external-private-key-hsm)
+
+
+**Using locally-managed keys without `USER_XXX` variables:**
+
+1. Import your public key to generate the keystore:
    ```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:**
+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.
+Now the build system detects existing files and skips auto-generation when building wolfBoot and the test app.
+
+**Multiple keys and advanced keystores:**
+
+The `keygen` tool supports multiple `-g` (generate) and `-i` (import) arguments, mixed key algorithms, and partition ID restrictions. See [keystore.md](keystore.md) for full details on keystore capabilities. When using these advanced features, image signing via the `sign` tool must also be performed manually.

docs/keystore.md

@@ -222,12 +222,26 @@ wolfBoot supports certain platforms that contain connected HSMs (Hardware Securi
 
 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
+## Build System Integration
 
-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
+By default, when running `make` to build the default target (`factory.bin`) for the first time, wolfBoot automatically generates a signing keypair and creates a single-key keystore as a "demonstration". This is distinct from using `keygen` directly with `-g` or `-i` options, which provides full control over keystore creation.
 
-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.
+### Default `make` Behavior
 
-See [compile.md](./compile.md#key-generation-and-signing) for more information
+Running `make` without creating the expected pre-existing keys automatically:
+- Generates a signing keypair at `wolfboot_signing_private_key.der`
+- Creates the keystore at `src/keystore.c` with the corresponding public key
+
+Note that supplying either of these dependencies manually will cause the build system to skip the generation step
+
+### Pre-existing Local Keys for Test App Builds
+
+The `USER_PRIVATE_KEY` and `USER_PUBLIC_KEY` Makefile variables provide a convenience for building the test app with your own locally-managed keys, avoiding manual `keygen -i` invocation:
+
+```sh
+make USER_PRIVATE_KEY=/path/to/my-key.der USER_PUBLIC_KEY=/path/to/my-pubkey.der
+```
+
+This is primarily useful for test app builds where you wish to use your own PKI as a test. For wolfBoot-only builds, the main benefit is automating the `keygen -i` step for simple single-key keystores.
+
+**Note:** If your private key is managed by a third party (e.g., HSM-as-a-service) and you only have access to the public key, use `keygen -i` directly instead. See [Signing.md](./Signing.md#signing-firmware-with-external-private-key-hsm) and [compile.md](./compile.md#pre-existing-local-keys-for-test-app-builds) for full details regarding this use case.