# 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
```bash
# 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
```bash
# 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
```bash
# Build primer tool
make FLASH_OTP_KEYSTORE=1
make otp

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

#### Operation Flow
1. Generate keys (`keygen`)
2. Build primer
3. Flash primer
4. Auto-provision on boot

#### Key Source
- Keys from `keystore.c`
- Generated by `keygen`
- Embedded in primer
- Written to OTP on execution

⚠️ **Critical Warnings**

1. **One-Time Operation**
   - No undo capability
   - Permanent key storage
   - Verify before flashing
   - Backup private keys

2. **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:

1) Setup the configuration and key tools:

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

2) 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`

3) Backup the generated keys and `src/keystore.c`
  - Save to safe place outside of the wolfBoot tree

4) 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`

5) 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

  OR

  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

6) Verify OTP keystore
  - Read memory at address `0x08FFF000` (should start with ASCII "WOLFBOOT")
  - Typically use STM32CubeProgrammer for this

7) 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)

8) Mass erase the device
  - STM32CubeProgrammer -> Full chip erase

9) Build wolfBoot and test application using `make`

10) Flash wolfBoot and test-app

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

11) Disconnect and reboot, the red LED should turn on.

12) Connect to USB UART on NUCLEO board for console

Explore the command line (run help)

```sh
========================
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
```

13) 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:

```sh
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>
```