7.2 KiB

Raw Blame History

OTP Flash Keystore Guide

Overview

This guide explains how to use One-Time Programmable (OTP) flash memory for secure key storage in wolfBoot.

Key Features

Immutable key storage
Tamper-resistant security
Runtime key access
Multiple key support
Header-based organization

Architecture

Memory Layout

OTP Area
+------------------------+ <- OTP Start
|     16-byte Header    | - Key count
|                      | - Key sizes
|                      | - Metadata
+------------------------+
|     Public Keys      |
|                      |
|                      |
+------------------------+

Configuration

Build Options

# Enable OTP keystore
make FLASH_OTP_KEYSTORE=1

Default Behavior

OTP support disabled by default
Keys embedded in wolfBoot binary
Runtime key access when enabled
Separate provisioning required

Depending on the target device, you can either prepare a binary image of the OTP area content, or use otp-keystore-primer firmware to directly provision the keys on the target.

Provisioning Methods

Method 1: Binary Image Generation

Tool Usage

# Build OTP generator
make otpgen

# Create OTP binary
./tools/keytools/otp/otp-keystore-gen

Deployment

Output: otp.bin
Manual flashing required
Use external programming tools
Target-specific flash process

Method 2: Direct Provisioning

Primer Application

# Build primer tool
make FLASH_OTP_KEYSTORE=1
make otp

# Result: tools/keytools/otp/otp-keystore-primer

Operation Flow

Generate keys (keygen)
Build primer
Flash primer
Auto-provision on boot

Key Source

Keys from keystore.c
Generated by keygen
Embedded in primer
Written to OTP on execution

⚠️ Critical Warnings

One-Time Operation
- No undo capability
- Permanent key storage
- Verify before flashing
- Backup private keys
Security Implications
- Keys cannot be changed
- Private key loss = unusable system
- Verify key correctness
- Secure key backup required

Examples

STM32H5 OTP KeyStore

Example for NULCLEO-STM32H563ZI with TrustZone (via PKCS11), DualBank and signing with PQ LMS:

Setup the configuration and key tools:

cp config/examples/stm32h5-tz-dualbank-otp-lms.config .config
make include/target.h
make keytools

Generate key(s) to write to OTP

./examples/keytools/keygen --lms -g 1.key -g 2.key -g 3.key -g 4.key -g 5.key

Backup the generated keys and src/keystore.c

Save to safe place outside of the wolfBoot tree

Set the signing key to use

Copy one of the generated keys to wolfboot_signing_private_key.der
cp 1.key wolfboot_signing_private_key.der

Setup the OTP keystore

Flash the OTP keystore primer:

Run make otp
Flash ./tools/keytools/otp/otp-keystore-primer.bin to 0x08000000
Disconnect the tool and hit reset button
The primer will run and flash keystore.c to OTP and enable write protection on those blocks

Generate OTP (otp.bin) and flash using external tool

Run make otpgen
Run ./tools/keytools/otp/otp-keystore-gen to generate an otp.bin file
Program otp.bin to 0x08FFF000 using external tool like STM32CubeProgrammer

Verify OTP keystore

Read memory at address 0x08FFF000 (should start with ASCII "WOLFBOOT")
Typically use STM32CubeProgrammer for this

Setup the option bytes

User Configuration 2 -> TrustZone Enable (TZEN=0xB4)
Bank1 - Flash Watermark area (SECWM1_START=0x00, SECWM1_END=0x1F)
Bank2 - Flash Watermark area (SECWM2_START=0x00, SECWM2_END=0x1F)

Mass erase the device

STM32CubeProgrammer -> Full chip erase

Build wolfBoot and test application using make
Flash wolfBoot and test-app

Flash wolfboot.bin at 0x0C000000
Flash test-app/image_v1_signed.bin at 0x08040000

Disconnect and reboot, the red LED should turn on.
Connect to USB UART on NUCLEO board for console

Explore the command line (run help)

========================
STM32H5 wolfBoot demo Application
Copyright 2024 wolfSSL Inc
GPL v3
Version : 0x1
========================

cmd> help
help : shows this help message
info : display information about the system and partitions
success : confirm a successful update
pkcs11 : enable and test crypto calls with PKCS11 in secure mode
random : generate a random number
timestamp : print the current timestamp
benchmark : run the wolfCrypt benchmark
test : run the wolfCrypt test
update : update the firmware via XMODEM
reboot : reboot the system

Test Update

Sign a new version of the firmware: ./tools/keytools/sign --lms test-app/image.bin wolfboot_signing_private_key.der 2
Run "update" command on the shell and wait for xmodem transfer
Use serial terminal that supports xmodem like "minicom" or "CoolTerm".
- Run minicom on /dev/ttyACM0 and start file transfer using "CTRL+A; S"
- Select xmodem then navigate to the new signed firmware file test-app/image_v2_signed.bin
During the transfer, the yellow LED will flash.
The green LED is dim because it's sync with the UART RX
At the end of the transfer, the new image will be in the update partition.
Reset board to install new firmware and confirm new version number.

Example update output:

cmd> update
Erasing update partition...Done.
Waiting for XMODEM transfer...
.......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................




End of transfer. ret: 0
New firmware version: 0x2
Triggering update...
Update completed successfully.

cmd> reboot

========================
STM32H5 wolfBoot demo Application
Copyright 2024 wolfSSL Inc
GPL v3
Version : 0x2
========================

cmd>

7.2 KiB Raw Blame History