Merge pull request #64 from dgarske/keytools

Improvements to the key tools documentation

Author: danielinux

.gitignore

@@ -48,6 +48,7 @@
 # automatically generated keys
 *.der
 *.pem
+*.sig
 
 # automatically generated source files
 src/ed25519_pub_key.c
@@ -57,12 +58,13 @@ src/rsa4096_pub_key.c
 
 # keygen binaries
 tools/keytools/sign
+tools/keytools/sign.exe
 tools/keytools/keygen
+tools/keytools/keygen.exe
 
 # Vim swap files
 .*.swp
 
-
 # tags etc.
 cscope.out
 tags

Makefile

@@ -271,7 +271,7 @@ factory.bin: $(BOOT_IMG) wolfboot-align.bin $(PRIVATE_KEY)
 	@echo "\t[SIGN] $(BOOT_IMG)"
 	$(Q)$(SIGN_TOOL) $(SIGN_OPTIONS) $(BOOT_IMG) $(PRIVATE_KEY) 1
 	@echo "\t[MERGE] $@"
-	@cat wolfboot-align.bin test-app/image_v1_signed.bin > $@
+	$(Q)cat wolfboot-align.bin test-app/image_v1_signed.bin > $@
 
 wolfboot.elf: include/target.h $(OBJS) $(LSCRIPT) FORCE
 	@echo "\t[LD] $@"

docs/Signing.md

@@ -1,8 +1,8 @@
-# wolfBoot Signing
+# wolfBoot Key Tools
 
-Instructions for setting up Python, wolfCrypt-py module and wolfBoot for firmware signing. 
+Instructions for setting up Python, wolfCrypt-py module and wolfBoot for firmware signing and key generation.
 
-Note: There is a pure C signing tool available as well. See [C Signing Tool](#c-signing-tool) below.
+Note: There is a pure C version of the key tool available as well. See [C Key Tools](#c-key-tools) below.
 
 ## Install Python3
 
@@ -39,48 +39,65 @@ make config
 make
 ```
 
-## Signing Firmware
+## C Key Tools
 
-1. Load the private key to use for signing into “./rsa4096.der”
-2. `python3 ./tools/keytools/sign.py --rsa4096 --sha3 test-app/image.bin rsa4096.der 1`
+A standalone C version of the keygen tools is available in: `./tools/keytools`. 
 
-Note: The last argument is the “version” number.
+These can be built in `tools/keytools` using `make` or from the wolfBoot root using `make keytools`. 
 
-## Signing Firmware with External Private Key (HSM)
+If the C version of the key tools exists they will be used by wolfBoot (the default is the Python scripts).
+
+### Windows Visual Studio
 
-I've tested this with separate signature and the correct public key, the two files are identical either if I do one step signing:
+Use the `wolfBootSignTool.vcxproj` Visual Studio project to build the `sign.exe` and `keygen.exe` tools for use on Windows.
 
-```sh
-# Create file with Public Key
-openssl rsa -inform DER -outform DER -in rsa4096.der -out rsa4096_pub.der -pubout
 
-# Generate Hash to Sign
-python3 ./tools/keytools/sign.py --rsa4096 --sha-only --sha3 test-app/image.bin rsa4096_pub.der 1
+## Command Line Usage
 
-# Example for signing
-openssl rsautl -sign -keyform der -inkey rsa4096.der -in test-app/image_v1_digest.bin > test-app/image_v1.sig
+```sh
+./tools/keytools/keygen [--ed25519 | --ecc256 | --rsa2048 | --rsa4096 ]  pub_key_file.c
+```
 
-# Generate final signed binary
-python3 ./tools/keytools/sign.py --rsa4096 --sha3 --manual-sign test-app/image.bin rsa4096_pub.der 1 test-app/image_v1.sig
+```sh
+./tools/keytools/sign [--ed25519 | --ecc256 | --rsa2048 | --rsa4096 ] [--sha256 | --sha3] [--wolfboot-update] image key.der fw_version
+  - or -        ./tools/keytools/sign [--sha256 | --sha3] [--sha-only] [--wolfboot-update] image pub_key.der fw_version
+  - or -        ./tools/keytools/sign [--ed25519 | --ecc256 | --rsa2048 | --rsa4096 ] [--sha256 | --sha3] [--manual-sign] image pub_key.der fw_version signature.sig
 ```
 
-## C Signing Tool
+## Signing Firmware
 
-A standalone C version of the signing tool is available here: `./tools/keytools/sign.c`. Build using `make keytools`
+1. Load the private key to use for signing into `./rsa2048.der`, `./rsa4096.der` or `./ed25519.der`.
+2. Run the signing tool with asymmetric algorithm, hash algorithm, file to sign, key and version.
 
 ```sh
-./tools/keytools/sign --rsa4096 --sha3 test-app/image.bin rsa4096.der 1
+./tools/keytools/sign --rsa2048 --sha256 test-app/image.bin rsa2048.der 1
+# OR
+python3 ./tools/keytools/sign.py --rsa2048 --sha256 test-app/image.bin rsa2048.der 1
 ```
 
-### Windows Visual Studio
+Note: The last argument is the “version” number.
 
-Use the `wolfBootSignTool.vcxproj` Visual Studio project to build the `sign.exe` tool for use on Windows.
+## Signing Firmware with External Private Key (HSM)
 
+Steps for manually signing firmware using an external key source.
 
-## Command Line Usage
+```sh
+# Create file with Public Key
+openssl rsa -inform DER -outform DER -in rsa2048.der -out rsa2048_pub.der -pubout
 
-```
-./tools/keytools/sign [--ed25519 | --ecc256 | --rsa2048 | --rsa4096 ] [--sha256 | --sha3] [--wolfboot-update] image key.der fw_version
-  - or -        ./tools/keytools/sign [--sha256 | --sha3] [--sha-only] [--wolfboot-update] image pub_key.der fw_version
-  - or -        ./tools/keytools/sign [--ed25519 | --ecc256 | --rsa2048 | --rsa4096 ] [--sha256 | --sha3] [--manual-sign] image pub_key.der fw_version signature.sig
+# Generate Hash to Sign
+./tools/keytools/sign            --rsa2048 --sha-only --sha256 test-app/image.bin rsa2048_pub.der 1
+# OR
+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
+
+# Generate final signed binary
+./tools/keytools/sign            --rsa2048 --sha256 --manual-sign test-app/image.bin rsa2048_pub.der 1 test-app/image_v1.sig
+# OR
+python3 ./tools/keytools/sign.py --rsa2048 --sha256 --manual-sign test-app/image.bin rsa4096_pub.der 1 test-app/image_v1.sig
+
+# Combine into factory image
+cat wolfboot-align.bin test-app/image_v1_signed.bin > factory.bin
 ```

tools/keytools/README.md

@@ -1,3 +1,3 @@
-# Signing Tool
+# Key Tools for signing and key generation
 
 See documentation [here](../../docs/Signing.md).