WolfSSL
/
wolfBoot
mirror of https://github.com/wolfSSL/wolfBoot.git
1
0
Fork 0
Code Issues Releases Wiki Activity
wolfBoot/docs/Signing.md

14 KiB
Raw Blame History

wolfBoot Key Tools

keygen and sign are two command line tools to be used on a PC (or automated server) environment to manage wolfBoot private keys and sign the initial firmware and all the updates for the target.

C Key Tools

A standalone C version of the key tools is available in: ./tools/keytools.

These can be built in tools/keytools using make or from the wolfBoot root using make keytools.

Windows Visual Studio

Use the wolfBootSignTool.vcxproj Visual Studio project to build the sign.exe and keygen.exe tools for use on Windows.

If you see any error about missing target.h this is a generated file based on your .config using the make process. It is needed for WOLFBOOT_SECTOR_SIZE used in delta updates.

Command Line Usage

Keygen tool

Usage: keygen [OPTIONS] [-g new-keypair.der] [-i existing-pubkey.der] [...]

keygen is used to populate a keystore with existing and new public keys. The following 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
  • --der save generated private key in DER format.
  • --exportpubkey to export the public key (corresponding to the private key generated with -g) to a DER file. This option only has an effect if used in conjunction with the -g option.
  • --nolocalkeys to generate a keystore entry with zeroized key material. This option is only useful on platforms that support using an external key by reference, such as wolfHSM. Only has an effect if used in conjunction with the -g option.

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.

Sign tool

sign produces a signed firmware image by creating a manifest header in the format supported by wolfBoot.

Usage: sign [OPTIONS] IMAGE.BIN KEY.DER VERSION

IMAGE.BIN: A file containing the binary firmware/software to sign KEY.DER: Private key file, in DER format, to sign the binary image VERSION: The version associated with this signed software OPTIONS: Zero or more options, described below

Image header size

By default, the manifest header size used by SIGN tool depends on the ideal value for the configuration chosen. In some cases however, it is necessary to use a different value than the default. To override the IMAGE_HEADER_SIZE value, set an environment variable with the same name and the desired value, via setenv, export, or simply inlining it with the sign command:

IMAGE_HEADER_SIZE=2048 sign [OPTIONS] IMAGE.BIN KEY.DER VERSION

Public key signature options

If none of the following arguments is given, the tool will try to guess the key size from the format and key length detected in KEY.DER.

  • --ed25519 Use ED25519 for signing the firmware. Assume that the given KEY.DER file is in this format.

  • --ed448 Use ED448 for signing the firmware. Assume that the given KEY.DER file is in this format.

  • --ecc256 Use ecc256 for signing the firmware. Assume that the given KEY.DER file is in this format.

  • --ecc384 Use ecc384 for signing the firmware. Assume that the given KEY.DER file is in this format.

  • --ecc521 Use ecc521 for signing the firmware. Assume that the given KEY.DER 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.

  • --lms Use LMS/HSS for signing the firmware. Assume that the given KEY.DER file is in this format.

  • --xmss Use XMSS/XMSS^MT for signing the firmware. Assume that the given KEY.DER file is in this format.

  • --no-sign Disable secure boot signature verification. No signature verification is performed in the bootloader, and the KEY.DER argument should not be supplied.

Hash digest options

If none of the following is used, '--sha256' is assumed by default.

  • --sha256 Use sha256 for digest calculation on binary images and public keys.

  • --sha348 Use sha384 for digest calculation on binary images and public keys.

  • --sha3 Use sha3-384 for digest calculation on binary images and public keys.

Certificate Chain Options

wolfBoot also supports verifying firmware images using certificate chains instead of raw public keys. In this mode of operation, a certificate chain is included in the image manifest header, and the image is signed with the private key corresponding to the leaf certificate identity (signer cert). On boot, wolfBoot verifies the trust of the certificate chain (and therefore the signer cert) against a trusted root CA stored in the wolfHSM server, and if the chain is trusted, verifies the authenticity of the firmware image using the public key from the image signer certificate.

To generate an image for use with this mode, pass the --cert-chain CERT_CHAIN.der option to the sign tool, where CERT_CHAIN.der is a der encoded certificate chain containing one or more certificates in SSL order (leaf/signer cert last). Note that the sign tool still expects a signing private key to be provided as described above, and assumes that the public key of the signer cert in the chain corresponds to the signing private key.

Certificate chain verification of images is currently limited to use in conjuction with wolfHSM. See wolfHSM.md for more details.

Target partition id (Multiple partition images, "self-update" feature)

If none of the following is used, "--id=1" is assumed by default. On systems with a single image to verify (e.g. microcontroller with a single active partition), ID=1 is the default identifier for the firmware image to stage. ID=0 is reserved for wolfBoot 'self-update', and refers to the partition where the bootloader itself is stored.

  • --id N Set image partition id to "N".

  • --wolfboot-update Indicate that the image contains a signed self-update package for the bootloader. Equivalent to --id 0.

Encryption using a symmetric key

Although signed to be authenticated, by default the image is not encrypted and it's distributed as plain text. End-to-end encryption from the firmware packaging to the update process can be used if the firmware is stored on external non-volatile memories. Encrypted updates can be produced using a pre-shared, secret symmetric key, by passing the following option:

  • --encrypt SHAREDKEY.BIN use the file SHAREKEY.BIN to encrypt the image.

The format of the file depends on the algorithm selected for the encryption. If no format is specified, and the --encrypt SHAREDKEY.BIN option is present, --chacha is assumed by default.

See options below.

  • --chacha Use ChaCha20 algorithm for encrypting the image. The file SHAREDKEY.BIN is expected to be exactly 44 bytes in size, of which 32 will be used for the key, 12 for the initialization of the IV.

  • --aes128 Use AES-128 algorithm in counter mode for encrypting the image. The file SHAREDKEY.BIN is expected to be exactly 32 bytes in size, of which 16 will be used for the key, 16 for the initialization of the IV.

  • --aes256 Use AES-256 algorithm in counter mode for encrypting the image. The file SHAREDKEY.BIN is expected to be exactly 48 bytes in size, of which 32 will be used for the key, 16 for the initialization of the IV.

Delta updates (incremental updates from a known version)

An incremental update is created using the sign tool when the following option is provided:

  • --delta BASE_SIGNED_IMG.BIN This option creates a binary diff file between BASE_SIGNED_IMG.BIN and the new image signed starting from IMAGE.BIN. The result is stored in a file ending in _signed_diff.bin.

The compression scheme used is Bentley–McIlroy.

Options:

  • --no-base-sha : Avoid adding the sha of the base image to the manifest header. By default, the sign tool appends the sha of the base image to the manifest header, so wolfBoot will refuse to start a delta update if the sha does not match the one of the existing image. However, this takes up 32 to 48 bytes extra in the manifest header, so this option is available to provide compatibility on existing installations without this feature, where the header size does not allow to accommodate the field

Policy signing (for sealing/unsealing with a TPM)

Provides a PCR mask and digest to be signed and included in the header. The signing key is used to sign the digest.

  • --policy policy.bin: This argument is multi-purpose. By default the file should contain a 4-byte PCR mask and SHA2-256 PCR digest to be signed. If using --manual-sign then the file should contain the 4-byte PCR mask and signature. The PCR mask and signature will be included in the HDR_POLICY_SIGNATURE header tag. A copy of the final signed policy (including 4 byte PCR mask) will be output to [inputname].sig. Note: This may require increasing the IMAGE_HEADER_SIZE as two signatures will be stored in the header.

Adding custom fields to the manifest header

Provides a value to be set with a custom tag

  • --custom-tlv tag len val: Adds a TLV entry to the manifest header, corresponding to the type identified by tag, with length len bytes, and assigns the value val. Values can be decimal or hex numbers (prefixed by '0x'). The tag is a 16-bit number. Valid tags are in the range between 0x0030 and 0xFEFE.

  • --custom-tlv-buffer tag value: Adds a TLV entry with arbitrary length to the manifest header, corresponding to the type identified by tag, and assigns the value value. The tag is a 16-bit number. Valid tags are in the range between 0x0030 and 0xFEFE. The length is implicit, and is the length of the value. Value argument is in the form of a hex string, e.g. --custom-tlv-buffer 0x0030 AABBCCDDEE will add a TLV entry with tag 0x0030, length 5 and value 0xAABBCCDDEE.

  • --custom-tlv-string tag ascii-string: Adds a TLV entry with arbitrary length to the manifest header, corresponding to the type identified by tag, and assigns the value of ascii-string. The tag is a 16-bit number. Valid tags are in the range between 0x0030 and 0xFEFE. The length is implicit, and is the length of the ascii-string. ascii-string argument is in the form of a string, e.g. --custom-tlv-string 0x0030 "Version-1" will add a TLV entry with tag 0x0030, length 9 and value Version-1.

Three-steps signing using external provisioning tools

If the private key is not accessible, while it's possible to sign payloads using a third-party tool, the sign mechanism can be split in three phases:

  • Phase 1: Only create the sha digest for the image, and prepare an intermediate file that can be signed by third party tool.

This is done using the following option:

  • --sha-only When this option is selected, the sign tool will create an intermediate image including part of the manifest that must be signed, ending in _digest.bin. In this case, KEY.DER contains the public part of the key that will be used to sign the firmware in Phase 2.

  • Phase 2: The intermediate image *_digest.bin is signed by an external tool, an HSM or a third party signing service. The signature is then exported in its raw format and copied to a file, e.g. IMAGE_SIGNATURE.SIG

  • Phase 3: use the following option to build the final authenticated firmware image, including its manifest header in front:

    • --manual-sign When this option is provided, the KEY.DER argument contains the public part of the key that was used to sign the firmware in Phase 2. This option requires one extra argument at the end, after VERSION, which should be the filename of the signature that was the output of the previous phase, so IMAGE_SIGNATURE.SIG

For a real-life example, see the section below.

Examples

Signing Firmware

  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.
./tools/keytools/sign --rsa2048 --sha256 test-app/image.bin wolfboot_signing_private_key.der 1

Note: The last argument is the "version" number.

Signing Firmware with External Private Key (HSM)

Steps for manually signing firmware using an external key source.

# Create file with Public Key
openssl rsa -inform DER -outform DER -in my_key.der -out rsa2048_pub.der -pubout

# Add the public key to the wolfBoot keystore using `keygen -i`
./tools/keytools/keygen --rsa2048 -i rsa2048_pub.der

# Generate Hash to Sign
./tools/keytools/sign --rsa2048 --sha-only --sha256 test-app/image.bin rsa2048_pub.der 1

# Sign hash Example (here is where you would use an HSM)
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

# Combine into factory image (0xc0000 is the WOLFBOOT_PARTITION_BOOT_ADDRESS)
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.