Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Signing keys (secure boot)

A production board trusts the signing-key fingerprints in its OTP. Keep a backup of the corresponding private key and a signed recovery image before enabling Secure Boot. The full fuse sequence is in Production.

The keys on an RS-Key, and which one this is

KeyWhere it livesPurpose
Secure Boot signing keyPrivate PEM on the signing host. Public-key fingerprint in OTP page 2.Authorizes firmware and recovery images
MKEK and DEVKGenerated by the host provisioning tool and written to OTP page 58Storage sealing and device attestation. See OTP master key.
Applet secretsDevice storageFIDO, PIV, OpenPGP and other credentials. See Seals and PINs.

Architecture — the trust chain

The host signs the final combined TrustZone ELF, including the partition table, and converts the signed ELF to UF2. The image carries the public key and its ECDSA signature. With Secure Boot enabled, the RP2350 boot ROM checks that the SHA-256 fingerprint of that public key matches a trusted slot, verifies the signature and applies the rollback policy before starting Secure firmware. The board stores the fingerprint, so recovering it cannot recover the private PEM. See the Production signing chain and the RP2350 datasheet, §10.1.1.

1. Generate (one fresh key per board, off-repo, ideally offline)

Generate a secp256k1 key for a new board. Keep a separate directory for each board and keep private keys outside the repository and the build sandbox. Use the existing key for a provisioned board.

The standard Production recipe uses an unencrypted PEM. This example protects the new file with umask 077 and refuses to overwrite an existing private PEM.

mkdir -p ~/.rs-key-secrets
cd ~/.rs-key-secrets
openssl ecparam -genkey -name secp256k1 -noout > secure_boot_key.pem
openssl ec -in secure_boot_key.pem -pubout -out secure_boot_pub.pem

Optional PEM passphrase

To store the private key in an encrypted PEM, use this block in place of the one above. OpenSSL asks for the passphrase when creating the PEM and again when extracting the public key. Use a long, unique passphrase.

mkdir -p ~/.rs-key-secrets
cd ~/.rs-key-secrets
openssl ecparam -genkey -name secp256k1 -noout |
    openssl pkcs8 -topk8 -v2 aes-256-cbc -iter 600000 > secure_boot_key.pem
openssl ec -in secure_boot_key.pem -pubout -out secure_boot_pub.pem

Adding a passphrase to an existing key changes its file encoding. Keep the same private key and compare the public keys from the old and new PEMs before replacing your working copy.

2. Back it up — before you fuse anything

Keep durable backups of the private PEM on separate media. Use encrypted storage for an unencrypted PEM. If the PEM is passphrase-protected, keep the passphrase separately. Before provisioning, restore a copy and verify that you can open it and derive the expected public key.

Keep the inspected firmware-signed.uf2 and rsk-wipe-signed.uf2 as well. They must match the board, a trusted signing key and its current rollback policy. otp_secureboot.json carries the public-key fingerprint and can be regenerated by sealing with the same private key.

3. Provision — fuse the fingerprint (slot 0)

Build and seal the final combined ELF and the separate rsk-wipe ELF. Convert both signed ELFs to UF2, inspect both files and prove the signed firmware boots before writing any Secure Boot fuses. This is Production Stage 1b. Use the otp_secureboot.json produced by the same seal as that firmware.

Enter BOOTSEL after the test boot. Stage A writes the fingerprint into slot 0 and sets its KEY_VALID bit.

rsk secure-boot load-key ~/.rs-key-secrets/otp_secureboot.json &&
    rsk secure-boot status

Check that slot 0 shows [0]KV. and SECURE_BOOT_ENABLE is still False. Reboot and verify the signed firmware. Continue with harden, a cold power cycle and debug denial check, then enable and the first enforced boot. After proving enforcement, run lock for a fixed key or skip it to retain rotation. Provision page 58 after this sequence. The commands and readback checkpoints are in Production Stage 1c.

With the version-1 recipe on a fresh board, the first normal flash boot after enable can set floor 1 and ROLLBACK_REQUIRED. Prepare both signed images at the intended version before enable. To defer anti-rollback, the Production recipe omits the rollback argument from both seals.

4. Daily use — sign every flash

Read the board’s policy with rsk secure-boot status in BOOTSEL. For a routine update use the current floor for both firmware and rsk-wipe. For an intentionally versionless setup, verify that the floor is zero and ROLLBACK_REQUIRED is clear, then omit the rollback argument. The highest version with the default OTP rows is 47. See Anti-rollback.

For an unencrypted PEM, use the two picotool seal commands in Production Stage 1b with the correct rollback argument. The nix run .#flash helper also takes an unencrypted PEM directly. It defaults to RSK_ROLLBACK=1, so set the value for the target board if using that helper.

Sign with a passphrase-protected PEM

Build both ELFs first, using the board and flash layout in the Production recipe. The pinned picotool requires an unencrypted PEM, so OpenSSL opens the key in a private temporary directory for the two seals. Set TMPDIR to a RAM-backed directory such as /dev/shm on Linux, or use an encrypted volume for temporary storage. The block removes the temporary PEM when it exits. The example assumes floor 1. Replace the rollback argument in both commands to match the board’s policy.

sign_dir=$(mktemp -d "${TMPDIR:-/tmp}/rs-key-sign.XXXXXXXX")
trap 'rm -f "$sign_dir/key.pem"; rmdir "$sign_dir"' EXIT
trap 'exit 1' HUP INT TERM
openssl ec -in ~/.rs-key-secrets/secure_boot_key.pem -out "$sign_dir/key.pem"

picotool seal --sign --hash target/trustzone/combined.elf -t elf firmware-signed.elf -t elf \
    "$sign_dir/key.pem" ~/.rs-key-secrets/otp_secureboot.json \
    --major 1 --minor 0 --rollback 1
picotool seal --sign --hash target/thumbv8m.main-none-eabihf/release/rsk-wipe -t elf \
    rsk-wipe-signed.elf -t elf "$sign_dir/key.pem" \
    --major 1 --minor 0 --rollback 1

Once both seals succeed, continue with picotool uf2 convert and picotool info -a for each signed ELF as in Production. Inspect the signature, hash and rollback metadata, then load the checked firmware UF2 in BOOTSEL.

picotool load -v firmware-signed.uf2 && picotool reboot

After USB reconnects, verify the expected firmware and applets. Keep the matching signed wipe UF2 for recovery.

Key slots and validity

Page 2 has four one-time fingerprint slots. A trusted slot has its KEY_VALID bit set and its KEY_INVALID bit clear. Revocation sets KEY_INVALID permanently. A free slot is blank with both bits clear.

Full rsk secure-boot lock requires exactly one trusted slot and completed hardening. It revokes all other slots and makes pages 1 and 2 read-only from BOOTSEL. To retain rotation, leave a free slot and keep both pages BOOTSEL-writable by skipping the full lock. See Production Stage D.

5. Rotate a key

Rotation requires a free slot and BOOTSEL write access to both key-policy pages. Use it to retire a compromised signing key or to exclude vulnerable images when the rollback floor cannot be raised further. With one initial key, at most three replacements fit. This example replaces slot 0 with slot 1. Check the actual slots in rsk secure-boot status first.

  1. Generate and back up the replacement PEM in a separate directory such as ~/.rs-key-secrets/next. Using the Production ELF workflow, sign both firmware and rsk-wipe with that key at the board’s current policy. Name the new outputs firmware-next-signed.elf / .uf2 and rsk-wipe-next-signed.elf / .uf2 so the previous artifacts stay available. Write the firmware seal’s JSON to ~/.rs-key-secrets/next/otp_secureboot.json.

  2. Enter BOOTSEL and preview provisioning into the free slot.

    rsk secure-boot rotate ~/.rs-key-secrets/next/otp_secureboot.json --slot 1 --dry-run
    

    If the slot and fingerprint are correct, provision it and read back the state. rotate performs the same slot write as load-key --slot 1. Both keys are trusted at this point.

    rsk secure-boot rotate ~/.rs-key-secrets/next/otp_secureboot.json --slot 1 &&
        rsk secure-boot status
    
  3. In BOOTSEL load the firmware UF2 signed with the replacement key. Verify that it boots and that the expected applets respond. Keep the inspected wipe image signed with the replacement key.

    picotool load -v firmware-next-signed.uf2 && picotool reboot
    
  4. Return to BOOTSEL only after proving that boot. Revoke the old slot and verify the readback. revoke refuses to remove the last trusted slot.

    rsk secure-boot revoke 0 && rsk secure-boot status
    

    Check that slot 0 is revoked and slot 1 is still trusted. Reboot and verify that the replacement firmware starts. Images signed only by the old key now fail Secure Boot.

Loss and recovery — the cases

SituationWhat to do
Lost the PEM before load-keyGenerate a new key and prepare new signed firmware, wipe and OTP JSON.
Lost the PEM after load-key, before enableWith pages 1 and 2 still writable, provision a replacement in a free slot, verify the matching firmware and recovery files, and revoke the lost key’s slot before enabling enforcement. Follow the remaining Production checks.
Lost the PEM after enableRestore the backup, use another trusted key you still have, or rotate into a free slot while pages 1 and 2 remain writable. With every trusted private key lost and rotation unavailable, only existing eligible signed files remain usable. Use a new board for future builds.
Lost the passphrase to an encrypted PEMRecover the passphrase or an accessible copy of the same key. Otherwise follow the lost-key case for the board’s current state.
Key compromisedRotate and revoke the compromised slot, or replace the board if rotation is unavailable. The board trusts signatures from that slot until revocation.
Replacing the boardGenerate a fresh signing key for the replacement. A seed backup restores non-resident FIDO credentials. See Moving to a new board for migration scope.