From c9a7c2bc8d6d09f9884e4fd58bfb6b969e388309 Mon Sep 17 00:00:00 2001 From: Daniele Lacamera Date: Wed, 20 Jul 2022 20:17:22 +0200 Subject: [PATCH] Updated documentation with new keygen syntax --- docs/Signing.md | 42 ++++++++++++++++++++++++++++++------ docs/Targets.md | 10 ++++----- docs/encrypted_partitions.md | 4 ++-- docs/firmware_update.md | 4 ++-- docs/lib.md | 4 ++-- 5 files changed, 46 insertions(+), 18 deletions(-) diff --git a/docs/Signing.md b/docs/Signing.md index 23a4ef18..c06188fe 100644 --- a/docs/Signing.md +++ b/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 diff --git a/docs/Targets.md b/docs/Targets.md index 5573dc89..0c612086 100644 --- a/docs/Targets.md +++ b/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 diff --git a/docs/encrypted_partitions.md b/docs/encrypted_partitions.md index b404b791..a30a48e9 100644 --- a/docs/encrypted_partitions.md +++ b/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 ``` diff --git a/docs/firmware_update.md b/docs/firmware_update.md index 7f3b5579..0c51eb8b 100644 --- a/docs/firmware_update.md +++ b/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. diff --git a/docs/lib.md b/docs/lib.md index 960b98fd..a86e9010 100644 --- a/docs/lib.md +++ b/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 ```