diff --git a/docs/Signing.md b/docs/Signing.md index f0b73d7b5..728d27840 100644 --- a/docs/Signing.md +++ b/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). diff --git a/docs/azure_keyvault.md b/docs/azure_keyvault.md new file mode 100644 index 000000000..d9f2c40de --- /dev/null +++ b/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 -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.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. +