Bootware and Secure Boot

Description of Secure Boot process

Steps to setup Secure Boot

Bootware 2.0 Beta integration with Secure Boot is currently only supported on the Pi5. There are two additional stages to completely configure Secure Boot once you have Bootware configured as described in Getting Started:

Stages

  • Stage 1: Configure and install default Bootware 2.0 Beta, including signed image artifacts. Getting Started
  • Stage 2: Turn on SIGNED_BOOT enforcement (Reversibile)
  • Stage 3: Turn on Secure Boot (Not reversible)

Stage 2: Get up and running with SIGNED_BOOT and pre-existing/supplied RSA boot signing key (BSK)

Bootware 2.0 Beta uses a default 2048-bit RSA key to sign its image files. For Stages 2 and 3, the user will need to provide a private key in PEM format. This will be used as the Boot Signing Key (BSK).

Protect your private key! The Beta test is not meant for production, but in practice, you should never leave your private key on your unit. If your private key is leaked, your secure boot chain is broken!

If you need to create a key, the steps are as follows:

  1. Create the Private Key
openssl genpkey -algorithm RSA \
  -pkeyopt rsa_keygen_bits:2048 \
  -out pi_secureboot_private.pem

  1. Import the private BSK PEM with zbcli update-config. This will trigger a re-sign of all existing boot disk image artifacts in /boot/firmware, emitting new signature files (*.sig) generated by the new BSK. The timestamps on these files should reflect (roughly) the time at which this operation was performed. If they are older, then no re-signing has occurred ([BUG])

    1. Via TUI: navigate to Configure Secure Boot parameters and credentials > Configure the boot signing key, and enter the path to the private key in PEM format you wish to use as your BSK
    2. Via CLI: run zbcli update-config --bsk <private-key.pem>

  2. Set the SIGNED_BOOT flag in the Pi’s EEPROM and program the newly imported BSK using zbcli update-config:

    1. Via TUI: navigate to Configure Secure Boot parameters and credentials > Turn on Signed Boot (Flash EEPROM) .
    2. Via CLI: run zbcli update-config --signed-boot

    Wait for the operation to complete (5-15 seconds). Once done, the Pi will only be able to start up from a FAT disk image file signed with your (private) BSK, so do not lose it! If you wish to disable this behavior, the Pi can still be restored to factory settings with the [rpiboot utility](GitHub link).

  3. (Optional) reboot now to confirm that everything has been set up properly. You should briefly see a message on the screen indicating that the Pi’s bootloader has successfully validated the signature of boot.img against the contents of the boot.sig file present on-disk.

  4. Proceed with using bootware by creating a new ZI image using zbcli imager or installing an existing one using zbcli update*

*Image must have been created by zbcli ≥ version 2.0

Stage 3: Get up and running with full secure boot, including programmed OTP

NOTE: This stage is irreversible!

DESTRUCTIVE ACTION

ENABLING SECURE BOOT REQUIRES SETTING ONE TIME PROGRAMMABLE (OTP) REGISTERS AND IS IRREVERSIBLE!

Please read all steps below first before proceeding

DESTRUCTIVE ACTION

  1. Install the usbboot/rpiboot tools from the github repo on your host. Follow the instructions on github to install.

  2. Connect a cabke from the host USB-A to the Pi5 USB-C (Power) connector.

  3. Back on the Pi, use zbcli update-config --prep-otp <OUTPUT_DIR>, then transfer the resulting tarball via rsync or USB stick to the host machine. Unpack it in the usbboot directory.

For the following steps, once secure-boot has been enabled by programming the one-time programmable (OTP) fuses, it cannot be disabled and a different key cannot be programmed.

  1. On the host machine, in the usbboot directory, run rpiboot -d <unpacked-dir>.

  2. rpiboot should reflash the EEPROM permanently enabling secure-boot.

  3. Replace the USB cable between the host system and the Pi with the regular power cable.