Merge pull request #465 from danielinux/azure-keyvault-docs

Added documentation for signing with Azure Key Vault

Author: dgarske

docs/Signing.md

@@ -280,3 +280,7 @@ openssl pkeyutl -sign -keyform der -inkey my_key.der -in test-app/image_v1_diges
 tools/bin-assemble/bin-assemble factory.bin 0x0 wolfboot.bin \
                               0xc0000 test-app/image_v1_signed.bin
 ```
+
+### Signing Firmware with Azure Key Vault
+
+See [docs/azure_keyvault.md](/docs/azure_keyvault.md).

docs/azure_keyvault.md

@@ -0,0 +1,109 @@
+## Signing firmware using Microsoft Azure Key Vault
+
+Microsoft offers secure key management and provisioning tools, using keys stored
+in HSMs. This mechanisms helps to centralize key management for several purposes,
+including the support for signing payloads using the managed keys, which can be
+used in combination with wolfBoot for provisioning public keys in a fleet of
+devices.
+
+
+### Preparing the keystore
+
+wolfBoot can import public keys in the keystore using the `keygen` command line
+tool provided. `keygen` supports both raw ECC keys and ASN.1 format (.der).
+
+Azure allows to download the public keys in ASN.1 format to provision the device.
+To retrieve each public key to use for firmware authentication in wolfBoot, use:
+
+```sh
+az keyvault key download --vault-name <vault-name> -n test-signing-key-1 -e DER -f public-key-1.der
+```
+
+A keystore can now be created importing the public keys and with `keygen`'s `-i`
+(import) option. The option may be repeated multiple times to add more keys to
+the keystore.
+
+```sh
+./tools/keytools/keygen --ecc256 -i public-key-1.der [-i public-key-2.der ...]
+```
+
+### Signing the firmware image for wolfBoot
+
+The signing operation using any external HSM is performed through three-steps,
+as described in the relevant section in [Signing.md](signing.md).
+In this section we describe the procedure to sign the firmware image using Azure key vault.
+
+
+#### Obtaining the SHA256 digest
+
+Step 1 consists in calling the `./sign` tool with the extra `--sha-only` argument,
+to generate the digest to sign. The public key associated to the selected signing
+key in the vault needs to be provided:
+
+```sh
+./tools/keytools/sign --ecc256 --sha-only --sha256 test-app/image.bin public-key-1.der 1
+```
+
+To fit in a https REST request, the digest obtained must be encoded using base64:
+
+```sh
+DIGEST=$(cat test-app/image_v1_digest.bin | base64url_encode)
+```
+
+The variable `DIGEST` now contains a printable encoding of the key, which can be
+attached to the request.
+
+#### HTTPS request for signing the digest with the Key Vault
+
+
+To prepare the request, first get an access token from the vault and store it in a variable:
+
+```sh
+ACCESS_TOKEN=$(az account get-access-token --resource "https://vault.azure.net" --query "accessToken" -o tsv)
+```
+
+Use the URL associated to the selected key vault:
+
+```sh
+KEY_IDENTIFIER="https://<vault-name>.vault.azure.net/keys/test-signing-key"
+```
+
+Perform the request using cURL, and store the result in a variable:
+
+```sh
+SIGNING_RESULT=$(curl -X POST \
+    -s "${KEY_IDENTIFIER}/sign?api-version=7.4" \
+    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+    -H "Content-Type:application/json" \
+    -H "Accept:application/json" \
+    -d "{\"alg\":\"ES256\",\"value\":\"${DIGEST}\"}")
+echo $SIGNING_RESULT
+```
+
+The field `.value` in the result contains the (base64 encoded) signature.
+To extract the signature from the response, you can use a JSON parser:
+
+```sh
+SIGNATURE=$(jq -jn "$SIGNING_RESULT|.value")
+```
+
+The signature can now be decoded from base64 into a binary, so the
+`sign` tool can incorporate the signature into the manifest header.
+
+```sh
+echo $SIGNATURE| base64url_decode > test-app/image_v1_digest.sig
+```
+
+#### Final step: create the signed firmware image
+
+The 'third step' in the HSM three-steps procedure requires the `--manual-sign` option and the
+signature obtained through the Azure REST API.
+
+
+```
+./tools/keytools/sign --ecc256 --sha256 --manual-sign test-app/image.bin test-signin-key_pub.der 1 test-app/image_v1_digest.sig
+```
+
+The resulting binary file `image_v1_signed.bin` will now contain a signed firmware
+image that can be authenticated and staged by wolfBoot.
+