Updated documentation with new keygen syntax

docs/Signing.md

@@ -37,6 +37,29 @@ Use the `wolfBootSignTool.vcxproj` Visual Studio project to build the `sign.exe`
 
 ## Command Line Usage
 
+### Keygen tool
+
+Usage: `keygen[.py] [OPTIONS] [-g new-keypair.der] [-i existing-pubkey.der] [...]`
+
+`keygen` is used to populate a keystore with existing and new public keys.
+Two options are supported:
+
+- `-g privkey.der` to generate a new keypair, add the public key to the keystore and save the private key in a new file `privkey.der`
+- `-i existing.der` to import an existing public key from `existing.der`
+
+Arguments are not exclusive, and can be repeated more than once to populate a keystore with multiple keys.
+
+One option must be specified to select the algorithm enabled in the keystore (e.g. `--ed25519` or `--rsa3072`. See the section "Public key signature options" for the sign tool for the available options.
+
+The files generate by the keygen tool is the following:
+
+- A C file `src/keystore.c`, which is normally linked with the wolfBoot image, when the keys are provisioned through generated C code.
+- A binary file `keystore.img` that can be used to provision the public keys through an alternative storage
+- The private key, for each `-g` option provided from command line
+
+For more information about the keystore mechanism, see [keystore.md](keystore.md).
+
+
 ### Sign tool
 
 `sign` and `sign.py` produce a signed firmware image by creating a manifest header
@@ -69,6 +92,9 @@ file is in this format.
   * `--rsa2048` Use rsa2048 for signing the firmware. Assume that the given KEY.DER
 file is in this format.
 
+  * `--rsa3072` Use rsa3072 for signing the firmware. Assume that the given KEY.DER
+file is in this format.
+
   * `--rsa4096` Use rsa4096 for signing the firmware. Assume that the given KEY.DER
 file is in this format.
 
@@ -172,13 +198,13 @@ For a real-life example, see the section below.
 
 ### Signing Firmware
 
-1. Load the private key to use for signing into `./rsa2048.der`, `./rsa4096.der`, `./ed25519.der`, `ecc256.der`, or `./ed448.der`
+1. Load the private key to use for signing into `./wolfboot_signing_private_key.der`
 2. Run the signing tool with asymmetric algorithm, hash algorithm, file to sign, key and version.
 
 ```sh
-./tools/keytools/sign --rsa2048 --sha256 test-app/image.bin rsa2048.der 1
+./tools/keytools/sign --rsa2048 --sha256 test-app/image.bin wolfboot_signing_private_key.der 1
 # OR
-python3 ./tools/keytools/sign.py --rsa2048 --sha256 test-app/image.bin rsa2048.der 1
+python3 ./tools/keytools/sign.py --rsa2048 --sha256 test-app/image.bin wolfboot_signing_private_key.der 1
 ```
 
 Note: The last argument is the “version” number.
@@ -189,10 +215,12 @@ Steps for manually signing firmware using an external key source.
 
 ```sh
 # Create file with Public Key
-openssl rsa -inform DER -outform DER -in rsa2048.der -out rsa2048_pub.der -pubout
+openssl rsa -inform DER -outform DER -in my_key.der -out rsa2048_pub.der -pubout
 
-# Create .c file with public key for wolfBoot root of trust
-./lib/wolfssl/scripts/dertoc.pl rsa2048_pub.der rsa2048_pub_key src/rsa2048_pub_key.c
+# Add the public key to the wolfBoot keystore using `keygen -i`
+./tools/keytools/keygen --rsa2048 -i rsa2048_pub.der
+# OR
+python3 ./tools/keytools/keygen.py --rsa2048 -i rsa4096_pub.der
 
 # Generate Hash to Sign
 ./tools/keytools/sign            --rsa2048 --sha-only --sha256 test-app/image.bin rsa2048_pub.der 1
@@ -200,7 +228,7 @@ openssl rsa -inform DER -outform DER -in rsa2048.der -out rsa2048_pub.der -pubou
 python3 ./tools/keytools/sign.py --rsa2048 --sha-only --sha256 test-app/image.bin rsa4096_pub.der 1
 
 # Sign hash Example (here is where you would use an HSM)
-openssl rsautl -sign -keyform der -inkey rsa2048.der -in test-app/image_v1_digest.bin > test-app/image_v1.sig
+openssl pkeyutl -sign -keyform der -inkey my_key.der -in test-app/image_v1_digest.bin > test-app/image_v1.sig
 
 # Generate final signed binary
 ./tools/keytools/sign            --rsa2048 --sha256 --manual-sign test-app/image.bin rsa2048_pub.der 1 test-app/image_v1.sig

docs/Targets.md

@@ -644,7 +644,7 @@ resume 0x0000001
 To sign the same application image as new version (2), use the python script `sign.py` provided:
 
 ```
-tools/keytools/sign.py test-app/image.bin ed25519.der 2
+tools/keytools/sign.py test-app/image.bin wolfboot_signing_private_key.der 2
 ```
 
 From OpenOCD, the updated image (version 2) can be flashed to the second bank:
@@ -715,8 +715,8 @@ st-flash write test-app/image_v1_signed.bin 0x08020000
 
 To sign the same application image as new version (2), use the sign tools
 
-Python: `tools/keytools/sign.py --ecc256 --sha256 test-app/image.bin ecc256.der 2`
-C Tool: `tools/keytools/sign    --ecc256 --sha256 test-app/image.bin ecc256.der 2`
+Python: `tools/keytools/sign.py --ecc256 --sha256 test-app/image.bin wolfboot_signing_private_key.der 2`
+C Tool: `tools/keytools/sign    --ecc256 --sha256 test-app/image.bin wolfboot_signing_private_key.der 2`
 
 Flash the updated version 2 image: `st-flash write test-app/image_v2_signed.bin 0x08120000`
 
@@ -825,7 +825,7 @@ make wolfboot.bin CROSS_COMPILE=aarch64-linux-gnu-
 * Sign Image
 ```
 make keytools
-./tools/keytools/sign --rsa4096 --sha3 Image rsa4096.der 1
+./tools/keytools/sign --rsa4096 --sha3 Image wolfboot_signing_private_key.der 1
 ```
 
 * Compose the image
@@ -873,7 +873,7 @@ make CROSS_COMPILE=aarch64-unknown-nto-qnx7.0.0-
 
 #### Signing
 
-`tools/keytools/sign.py --rsa4096 --sha3 /srv/linux-rpi4/vmlinux.bin rsa4096.der 1`
+`tools/keytools/sign.py --rsa4096 --sha3 /srv/linux-rpi4/vmlinux.bin wolfboot_signing_private_key.der 1`
 
 
 ## Cypress PSoC-6

docs/encrypted_partitions.md

@@ -97,7 +97,7 @@ The `sign.py` script can now be invoked to produce a signed+encrypted image, by
 secret file:
 
 ```
-./tools/keytools/sign.py --encrypt enc_key.der test-app/image.bin ecc256.der 24
+./tools/keytools/sign.py --encrypt enc_key.der test-app/image.bin wolfboot_signing_private_key.der 24
 
 ```
 
@@ -125,7 +125,7 @@ The `sign.py` script can now be invoked to produce a signed+encrypted image, by
 secret file. To select AES-256, use the `--aes256` option.
 
 ```
-./tools/keytools/sign.py --aes256 --encrypt enc_key.der test-app/image.bin ecc256.der 24
+./tools/keytools/sign.py --aes256 --encrypt enc_key.der test-app/image.bin wolfboot_signing_private_key.der 24
 
 ```
 

docs/firmware_update.md

@@ -152,11 +152,11 @@ Requirement: wolfBoot is compiled with `DELTA_UPDATES=1`
 
 Version "1" is signed as usual, as a standalone image:
 
-`tools/keytools/sign.py --ecc256 --sha256 test-app/image.bin ecc256.der 1`
+`tools/keytools/sign.py --ecc256 --sha256 test-app/image.bin wolfboot_signing_private_key.der 1`
 
 When updating from version 1 to version 2, you can invoke the sign tool as:
 
-`tools/keytools/sign.py --delta test-app/image_v1_signed.bin --ecc256 --sha256 test-app/image.bin ecc256.der 2`
+`tools/keytools/sign.py --delta test-app/image_v1_signed.bin --ecc256 --sha256 test-app/image.bin wolfboot_signing_private_key.der 2`
 
 Besides the usual output file `image_v2_signed.bin`, the sign tool creates an additional `image_v2_signed_diff.bin`
 which should be noticeably smaller in size as long as the two binary files contain overlapping areas.

docs/lib.md

@@ -91,7 +91,7 @@ Step 3: compile keytools and create keys.
 
 ```
 make keytools
-./tools/keytools/keygen --ed25519 src/ed25519_pub_key.c
+./tools/keytools/keygen --ed25519 -g wolfboot_signing_private_key.der
 ```
 
 
@@ -99,7 +99,7 @@ Step 4: Create an empty file and sign it using the private key.
 
 ```
 touch empty
-./tools/keytools/sign --ed25519 --sha256 empty ed25519.der 1
+./tools/keytools/sign --ed25519 --sha256 empty wolfboot_signing_private_key.der 1
 ```