wolfBoot/docs/Signing.md

wolfBoot Key Management Tools

This document describes the tools used for key management and firmware signing in wolfBoot.

Overview

Two primary tools are provided:

• keygen: Manages private keys and keystore
• sign: Creates signed firmware images

These tools can be used on:

• Development machines
• Build servers
• CI/CD pipelines

Building the Tools

Linux/Unix

# From tools/keytools directory
make

# From wolfBoot root
make keytools

Windows

Use Visual Studio project:

• Project file: wolfBootSignTool.vcxproj
• Outputs: sign.exe and keygen.exe

Note: If target.h is missing:

• This file is generated from your .config
• Required for WOLFBOOT_SECTOR_SIZE definition
• Used in delta update calculations

Keygen Tool

Basic Usage

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

Purpose

Creates and manages keystores containing public keys for firmware verification.

Key Options

Option	Description
-g privkey.der	Generate new keypair, save private key
-i existing.der	Import existing public key
--der	Save private key in DER format
--exportpubkey	Export public key to DER (with -g)
--nolocalkeys	Create keystore entry without key material*

*Used with wolfHSM for external key reference

Algorithm Selection

Must specify one:

• --ed25519
• --rsa3072
• (See "Public Key Options" section below)

Multiple Keys

• Options can be combined
• Multiple -g or -i allowed
• Builds keystore with all specified keys

Output Files

1. src/keystore.c

   • C source for linking with wolfBoot
   • Contains embedded public keys

2. keystore.img

   • Binary keystore file
   • For alternative storage methods

3. Private Key Files

   • One per -g option
   • Used for firmware signing

For detailed keystore information, see keystore.md

Sign Tool

Basic Usage

sign [OPTIONS] IMAGE.BIN KEY.DER VERSION

Parameters

Parameter	Description
IMAGE.BIN	Binary firmware/software to sign
KEY.DER	Private key in DER format
VERSION	Version number for the firmware
OPTIONS	Optional configuration flags

Header Size Configuration

The manifest header size can be customized:

# Default: Automatically determined based on configuration
# Override: Set IMAGE_HEADER_SIZE environment variable

# Method 1: Export variable
export IMAGE_HEADER_SIZE=2048
sign [OPTIONS] IMAGE.BIN KEY.DER VERSION

# Method 2: Inline setting
IMAGE_HEADER_SIZE=2048 sign [OPTIONS] IMAGE.BIN KEY.DER VERSION

Note: Custom header size may be needed for:

• Large signatures (e.g., RSA-4096)
• Multiple signatures (hybrid mode)
• Additional custom TLV fields

Signature Algorithms

The tool automatically detects key type from KEY.DER if no algorithm is specified.

Classical Algorithms

Option	Algorithm	Description
--ed25519	ED25519	Edwards curve signature
--ed448	ED448	Edwards curve signature
--ecc256	ECDSA P-256	NIST P-256 curve
--ecc384	ECDSA P-384	NIST P-384 curve
--ecc521	ECDSA P-521	NIST P-521 curve
--rsa2048	RSA-2048	2048-bit RSA
--rsa3072	RSA-3072	3072-bit RSA
--rsa4096	RSA-4096	4096-bit RSA

Post-Quantum Algorithms

Option	Algorithm	Description
--lms	LMS/HSS	Hash-based signature
--xmss	XMSS/XMSS^MT	Hash-based signature

Special Options

Option	Description
--no-sign	Disable signature verification

Note: With --no-sign:

• No KEY.DER required
• No signature verification in bootloader
• Not recommended for production use

Hash Algorithm Options

Default: --sha256

Option	Algorithm	Description
--sha256	SHA-256	Standard SHA-2 256-bit
--sha384	SHA-384	Standard SHA-2 384-bit
--sha3	SHA3-384	SHA-3 384-bit variant

Target Partition Configuration

Default: --id=1

Partition IDs

ID	Purpose	Description
0	Bootloader	Reserved for wolfBoot self-update
1	Primary Firmware	Default application partition
N	Custom	User-defined partitions

Options

Option	Description
--id N	Target partition N
--wolfboot-update	Bootloader update (same as --id 0)

Use Cases:

• Single partition systems: Use default --id=1
• Multi-partition systems: Specify partition with --id N
• Bootloader update: Use --wolfboot-update or --id 0

Firmware Encryption

By default, firmware images are signed but not encrypted. For secure external storage, end-to-end encryption is available.

Basic Encryption

--encrypt SHAREDKEY.BIN   # Enable encryption with shared key

Encryption Algorithms

Default: --chacha (when using --encrypt)

Algorithm	Option	Key File Size	Key Size	IV Size
ChaCha20	--chacha	44 bytes	32 bytes	12 bytes
AES-128-CTR	--aes128	32 bytes	16 bytes	16 bytes
AES-256-CTR	--aes256	48 bytes	32 bytes	16 bytes

Use Cases:

• External flash storage
• Over-the-air updates
• Sensitive firmware protection

Note: Key file (SHAREDKEY.BIN) must be pre-shared and kept secure

Delta Updates

Create incremental updates between firmware versions to minimize update size.

Basic Usage

--delta BASE_SIGNED_IMG.BIN   # Create incremental update

Process:

1. Takes base image (BASE_SIGNED_IMG.BIN)
2. Compares with new image (IMAGE.BIN)
3. Creates diff file (*_signed_diff.bin)
4. Uses Bentley-McIlroy compression

Options

Option	Description	Impact
Default	Includes base image SHA	+32-48 bytes header
--no-base-sha	Skips base image SHA	Smaller header

Considerations:

• Base image SHA ensures correct update base
• --no-base-sha for legacy header size compatibility
• Reduces update bandwidth and storage requirements

TPM Policy Signing

Enable TPM-based sealing/unsealing with signed policies.

Basic Usage

--policy policy.bin   # Add signed TPM policy

Policy File Format

1. Default Mode:

   • 4-byte PCR mask
   • SHA2-256 PCR digest (to be signed)

2. Manual Sign Mode:

   • 4-byte PCR mask
   • Pre-computed signature

Outputs

• Policy signature in HDR_POLICY_SIGNATURE header
• Signed policy (with PCR mask) in [inputname].sig

Note: May require increased IMAGE_HEADER_SIZE for dual signatures

Custom Manifest Fields

Add custom Type-Length-Value (TLV) entries to the manifest header.

TLV Tag Range

• Valid tags: 0x0030 to 0xFEFE
• 16-bit values

Options

1. Fixed-Length Values

--custom-tlv <tag> <len> <val>

• Numeric values (decimal/hex)
• Fixed length in bytes

2. Buffer Values

--custom-tlv-buffer <tag> <hex-string>

Example:

--custom-tlv-buffer 0x0030 AABBCCDDEE
# Creates: tag=0x0030, len=5, val=0xAABBCCDDEE

3. String Values

--custom-tlv-string <tag> "<ascii-string>"

Example:

--custom-tlv-string 0x0030 "Version-1"
# Creates: tag=0x0030, len=9, val="Version-1"

External Signing Process

For scenarios where private keys are managed by HSMs or external services, the signing process can be split into three phases.

Phase 1: Generate Digest

--sha-only   # Generate intermediate digest file

Inputs:

• IMAGE.BIN: Firmware to sign
• KEY.DER: Public key only

Output:

• *_digest.bin: Intermediate file for signing

Phase 2: External Signing

Sign the digest using external tools:

• Hardware Security Module (HSM)
• Cloud Key Management Service
• Third-party signing service

Output:

• IMAGE_SIGNATURE.SIG: Raw signature file

Phase 3: Create Final Image

--manual-sign IMAGE_SIGNATURE.SIG   # Combine components

Inputs:

• Original IMAGE.BIN
• Public key (KEY.DER)
• Version number
• IMAGE_SIGNATURE.SIG

Output:

• Complete signed firmware with manifest

Note: See Examples section below for detailed workflow

Usage Examples

Basic Firmware Signing

Direct Signing with Local Key

# 1. Prepare private key
cp signing_key.der wolfboot_signing_private_key.der

# 2. Sign firmware
./tools/keytools/sign --rsa2048 --sha256 \
    test-app/image.bin \
    wolfboot_signing_private_key.der 1

HSM Integration Example

Complete HSM Workflow

# 1. Export public key
openssl rsa -inform DER -outform DER \
    -in my_key.der \
    -out rsa2048_pub.der -pubout

# 2. Add to wolfBoot keystore
./tools/keytools/keygen --rsa2048 -i rsa2048_pub.der

# 3. Generate digest for HSM
./tools/keytools/sign --rsa2048 --sha-only --sha256 \
    test-app/image.bin rsa2048_pub.der 1

# 4. Sign with HSM (example using OpenSSL)
openssl pkeyutl -sign -keyform der \
    -inkey my_key.der \
    -in test-app/image_v1_digest.bin \
    -out test-app/image_v1.sig

# 5. Create signed firmware
./tools/keytools/sign --rsa2048 --sha256 --manual-sign \
    test-app/image.bin rsa2048_pub.der 1 \
    test-app/image_v1.sig

# 6. Create factory image
tools/bin-assemble/bin-assemble factory.bin \
    0x0 wolfboot.bin \
    0xc0000 test-app/image_v1_signed.bin

Cloud Service Integration

For Azure Key Vault integration, see azure_keyvault.md