WIP: Add support for secure-boot - see Readme.md

.gitignore

@@ -1,2 +1,3 @@
 rpiboot
 bin2c
+*.exe

Readme.md

@@ -50,7 +50,7 @@ standard firmware release then this will at the very least boot the linux kernel
 you can build an initramfs into the kernel, add an initramfs to the boot directory or provide some
 other interface to the filesystem.
 
-```
+```bash
 sudo ./rpiboot -d boot
 ```
 
@@ -60,6 +60,69 @@ This will serve the boot directory to the Raspberry Pi Device.
 On Compute Module 4 EMMC-DISABLE / nRPIBOOT (GPIO 40) must be fitted to switch the ROM to usbboot mode.
 Otherwise, the SPI EEPROM bootloader image will be loaded instead.
 
+<a name="secure-boot"></a>
+## Secure Boot
+TODO - Add link to whitepaper / user-guide
+
+### Host setup
+Secure boot require a 2048 bit RSA asymettric keypair and the Python `pycrytodomex` module to sign the EEPROM config and boot image.
+
+#### Install Python Crypto support (the pycryptodomex module)
+```bash
+python3 -m pip install pycryptodomex
+# or
+pip install pycryptodomex
+```
+
+#### Create an RSA key-pair using OpenSSL. Must be 2048 bits
+```bash
+cd $HOME
+openssl genrsa 2048 > private.pem
+```
+
+### Secure Boot - configuration
+* Please see the [secure boot EEPROM guide](secure-boot-recovery/README.md) to enable via rpiboot `recovery.bin`.
+* Please see the [secure boot MSD guide](secure-boot-msd/README.md) for instructions about to mount the EMMC via USB mass-storage once secure-boot has been enabled.
+
+## Secure Boot - image creation
+Secure boot requires a boot.img FAT image to be created. This plus a signature file (boot.sig)
+must be placed in the boot partition of the Raspberry Pi.
+
+The contents of the boot.img are the files normally present in the Raspberry Pi OS boot
+partition i.e. firmware, DTBs and kernel image. However, in order to reduce boot time
+it is advisible to remove unused files e.g. firmware or kernel images for Pi models.
+
+The firmware must be new enough to support secure boot. Either download the latest
+Raspberry Pi OS Bullseye OS image or alternateively, download the files
+for the `raspberrypi-bootloader` APT package directly from Github and use the files
+in the `boot` directory.
+
+`git clone --depth 1 --branch stable https://github.com/raspberrypi/firmware`
+
+A helper script (`make-boot-image`) is provided to automate the image creation process. This
+script depends upon the mkfs.fat and udisksctl tools and only runs on Linux.
+
+#### Clone the Raspberry Pi OS boot files
+Copy the contents of `/boot` to a local directory called `secure-boot-files`
+
+#### Set the kernel root device
+Verify that `cmdline.txt` in `secure-boot-files` points to the correct device for the root file-system.
+e.g. `root=/dev/mmcblk0p2` for the normal partition on CM4 EMMC.
+
+#### Create the boot image
+The `-p` product argument (pi4,pi400,cm4) tells the script to discard files which are not required by that product. This makes the image smaller and reduces the time taken to calculate the hash of the image file thereby reducing the boot time.
+```bash
+../tools/make-boot-image -d secure-boot-files -o boot.img -p pi4
+```
+
+#### Sign the boot image
+```bash
+../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
+```
+
+#### Copy the secure boot image to the device boot filesystem
+Copy `boot.img` and `boot.sig` to the chosen boot filesystem. Secure boot images can be loaded from any of the normal boot devices (e.g. SD, USB, Network).
+
 ### Raspberry Pi Imager - BETA
 The Raspberry Pi Imager can be run natively on the CM4 providing a GUI for downloading and installing the operating system.
 
@@ -69,7 +132,7 @@ Beta notes:
 * The HDMI display is limited to 1080p to avoid potential problems with cables etc if a 4K display is attached.
 
 Run Raspberry Pi Imager:  
-```
+```bash
 sudo ./rpiboot -d imager
 ```
 

imager/README.md

@@ -0,0 +1,17 @@
+# Signing the Raspberry Pi Imager for secure boot
+
+If secure-boot has been enabled then this image must be signed with
+the customer's RSA private key. Otherwise, the SPI EEPROM bootloader
+will refused to load this image.
+
+To do this run:
+
+```bash
+KEY_FILE=$HOME/private.pem
+../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
+```
+
+To run load the USB MSD device drivers via RPIBOOT run
+```bash
+../rpiboot -d .
+```

imager/boot.sig

@@ -0,0 +1,2 @@
+7d8720352f4256cfbb4426e5488b3de45009e8bc95a3e98d0a3645b9375fcd8e
+ts: 1621442422

recovery/boot.conf

@@ -3,8 +3,8 @@ BOOT_UART=0
 WAKE_ON_GPIO=1
 POWER_OFF_ON_HALT=0
 
-# Try  SD- > USB PCIe MSD -> USB 2.0 BCM XHCI -> Network ->  Loop
-BOOT_ORDER=0xf2541
+# Try  SD -> NVMe -> USB PCIe MSD -> USB 2.0 BCM XHCI -> Network ->  Loop
+BOOT_ORDER=0xf25461
 
 # Set to 0 to prevent bootloader updates from USB/Network boot
 # For remote units EEPROM hardware write protection should be used.

recovery/pieeprom.sig

@@ -1,2 +1,2 @@
-68086076eca7de8f9d9041e43525f19e21e78dcf5db3a30210068cc21e184e19
-ts: 1626189116
+ce348cdde7a9676f749b4bfbfb04839a164834220609d61ecc181d37e19f0608
+ts: 1628767561

recovery/update-pieeprom.sh

@@ -3,13 +3,11 @@
 # Utility to update the EEPROM image (pieeprom.bin) and signature
 # (pieeprom.sig) with a new EEPROM config.
 #
+# This script is now a thin wrapper for the new version in ../tools
+#
 # pieeprom.original.bin - The source EEPROM from rpi-eeprom repo
 # boot.conf - The bootloader config file to apply.
 
 set -e
 
-script_dir="$(cd "$(dirname "$0")" && pwd)" 
-
-${script_dir}/rpi-eeprom-config --config ${script_dir}/boot.conf --out ${script_dir}/pieeprom.bin ${script_dir}/pieeprom.original.bin
-sha256sum ${script_dir}/pieeprom.bin | awk '{print $1}' > ${script_dir}/pieeprom.sig
-echo "ts: $(date -u +%s)" >> "${script_dir}/pieeprom.sig"
+../tools/update-pieeprom.sh "$@"

secure-boot-msd/.gitignore

@@ -0,0 +1,2 @@
+*.h
+boot.sig

secure-boot-msd/README.md

@@ -0,0 +1,17 @@
+# USB MSD device mode drivers for signed-boot
+
+If secure-boot has been enabled then this image must be signed with
+the customer's RSA private key. Otherwise, the SPI EEPROM bootloader
+will refused to load this image.
+
+To do this run:
+
+```bash
+KEY_FILE=$HOME/private.pem
+../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
+```
+
+To run load the USB MSD device drivers via RPIBOOT run
+```bash
+../rpiboot -d .
+```

secure-boot-msd/config.txt

@@ -0,0 +1,5 @@
+# Load boot.img which contains usb.elf
+# In signed-boot or secure-boot mode the bootloader checks the
+# RSA signature of the ramdisk. The signature is located in boot.sig
+boot_ramdisk=1
+uart_2ndstage=1

secure-boot-recovery/.gitignore

@@ -0,0 +1,2 @@
+pieeprom.bin
+pieeprom.sig

secure-boot-recovery/README.md

@@ -0,0 +1,96 @@
+# Raspberry Pi 4 - secure boot
+
+This directory contains the beta bootcode4.bin (recovery.bin) and pieeprom-2021-05-19.bin
+bootloader release. Older bootloader and recovery.bin releases do not support secure boot.
+
+Steps for enabling secure boot:
+
+## Extra steps for Raspberry Pi 4B & Pi 400
+Raspberry Pi 4B and Pi400 do not have a dedicated RPIBOOT jumper so a different GPIO
+must be used to enable RPIBOOT if pulled low. The available GPIOs are 2,4,5,6,7,8
+since these are high by default.
+
+### Step 1 - Erase the EEPROM
+In order to avoid this OTP configuration being accidently set on Pi 4B / Pi 400
+this option can only be set via RPIBOOT. To force RPIBOOT on a Pi 4B / Pi 400
+erase the SPI EEPROM.
+
+Copy recovery.bin to a blank FAT32 formatted SD card with the following `config.txt` file.
+Then insert the SD card and boot the Pi and wait at least 10 seconds for the green
+LED to flash rapidly.
+```
+erase_eeprom=1
+```
+
+### Step 2 - Select the nRPIBOOT GPIO
+Then use rpiboot config.txt specify the GPIO to use for nRPIBOOT. For example:
+```
+program_rpiboot_gpio=8
+```
+
+The OTP setting for nRPIBOOT will then be set in the next steps when the
+EEPROM / secure-boot configuration is programmed.
+
+## Optional. Specify the private key file in an environment variable.
+Alternatively, specify the path when invoking the helper scripts.
+```bash
+export KEY_FILE="${HOME}/private.pem"
+```
+
+## Optional. Customize the EEPROM config.
+Custom with the desired bootloader settings. 
+See: [Bootloader configuration](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bcm2711_bootloader_config.md)
+
+Setting `SIGNED_BOOT=1` enables signed-boot mode so that the bootloader will only
+boot.img files signed with the specified RSA key. Since this is an EEPROM config
+option secure-boot can be tested and reverted via `RPIBOOT` at this stage.
+
+## Generate the signed bootloader image
+```bash
+cd secure-boot-recovery
+../tools/update-pieeprom.sh -k "${KEY_FILE}"
+```
+
+`pieeprom.bin` can then be flashed to the bootloader EEPROM via rpiboot.
+
+## Program the EEPROM image using rpiboot
+* Power off CM4
+* Set nRPIBOOT jumper and remove EEPROM WP protection
+```bash
+cd secure-boot-recovery
+../rpiboot -d .
+```
+* Power ON CM4
+
+## Locking secure-boot mode
+After verifying that the signed OS image boots successfully the system
+can be locked into secure-boot mode.  This writes the hash of the
+customer public key to "one time programmable" (OTP) bits. From then
+onwards:
+
+* The bootloader will only load OS images signed with the customer private key.
+* The EEPROM configuration file must be signed with the customer private key.
+* It is not possible to install an old version of the bootloader that does
+  support secure boot.
+* **It is NOT possible to use a different private key to signed the OS images**
+
+**WARNING: THESE OPTIONS PERMANENTLY THE BCM2711 CHIP AND ARE IRREVERSIBLE.**
+
+To enable this edit the `config.txt` file in this directory and set
+`program_pubkey=1`
+
+* `program_pubkey` - If 1, write the hash of the customer's public key to OTP.
+* `revoke_devkey` - If 1, revoke the ROM bootloader development key which
+ requires secure-boot mode and prevents downgrades to bootloader versions that
+ don't support secure boot.
+
+ ** DO NOT SET THIS `revoke_devkey` UNTIL THE BOOTLOADER IS SIGNED WITH THE SECURE
+BOOT KEY. IT WILL PREVENT THE PI FROM BOOTING.**
+
+## Disabling VideoCore JTAG
+
+VideoCore JTAG may be permentantly disabled by setting `program_jtag_lock` in
+`config.txt`. This option has no effect unless `revoke_revkey=1` is set and
+the EEPROM and customer OTP key were programmed successfully.
+
+See [config.txt](config.txt)

secure-boot-recovery/boot.conf

@@ -0,0 +1,17 @@
+[all]
+BOOT_UART=1
+WAKE_ON_GPIO=0
+POWER_OFF_ON_HALT=1
+HDMI_DELAY=0
+
+# SD, USB-MSD, BCM-USB-MSD, Network
+BOOT_ORDER=0xf2541
+
+# Disable self-update mode
+ENABLE_SELF_UPDATE=0
+
+# Select signed-boot mode in the EEPROM. This can be used to during development
+# to test the signed boot image. Once secure boot is enabled via OTP this setting
+# has no effect i.e. it is always 1.
+SIGNED_BOOT=1
+

secure-boot-recovery/config.txt

@@ -0,0 +1,39 @@
+uart_2ndstage=1
+
+# Mark the EEPROM as write protected when the EEPROM /WIP pin is pulled low.
+# See https://www.raspberrypi.org/documentation/hardware/raspberrypi/bcm2711_bootloader_config.md#eeprom_write_protect
+
+eeprom_write_protect=1
+
+# Uncomment to write to enable secure-boot by writing. This
+# locks the device to the public key in the EEPROM by storing the
+# sha256 hash of the public key in OTP.
+#
+# This option also prevents the ROM from loading recovery.bin from SD/EMMC
+# which means that the bootloader can only be updated via RPIBOOT or self-update.
+#
+# Uncomment program_pubkey=1 to enable this
+# WARNING: THIS OPTION MODIFIES THE BCM2711 CHIP AND IS IRREVERSIBLE.
+
+#program_pubkey=1
+
+# Uncomment to revoke the ROM development key via OTP preventing older
+# bootloader or recovery.bin releases from running on this Pi
+# WARNING: THIS OPTION MODIFIES THE BCM2711 CHIP AND IS IRREVERSIBLE.
+#
+# DO NOT SET THIS OPTION UNTIL THE BOOTLOADER IS SIGNED WITH THE SECURE
+# BOOT KEY. IT WILL PREVENT THE PI FROM BOOTING.
+#revoke_devkey=1
+
+# Pi 4B and Pi400 do not have a dedicated RPIBOOT jumper so a different GPIO
+# must be used to enable RPIBOOT if pulled low. The options are 2,4,5,6,7,8.
+#
+# This option has no effect on CM4.
+
+# WARNING: THIS OPTION MODIFIES THE BCM2711 CHIP AND IS IRREVERSIBLE.
+#program_rpiboot_gpio=8
+
+# Permanently disable VideoCore JTAG access.
+# Warning: This option limits the ability to do failure analysis on 
+# boards returned to resellers or Raspberry Pi Trading Ltd.
+#program_jtag_lock=1

tools/example-private.pem

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEowIBAAKCAQEA+l3E+h/QNjrIR1cG6NpzP0fBwp2UDpuQAafXDS5yryrfCPDY
+TO9DvzAfOk9Dz/putDfHV0RTOFXv1tmc4nqOgU6nKx7tTdsjTiY4CgG3vXRMuAmD
+GX5ssJFCVmljGuILt1INlCmtun7Ow35VTxOcRDDfrBDKnSitzOTf6KTR7xJhqFFh
+dMpIg8hW4bDBKMavyt38pRvDaO1o01qaQT/GgAPmJm27y5RKNAe6iVTqsm4TMAhK
+C6P4XyRAbe6OMdFZyEWEk7Asexuc7uZlVHsUI6pebSW/07O+5l/U7/3k6r//hO/H
+DFOBUUW55EjzzC1BhTlWHWfZNI+5+NdN8o323QIDAQABAoIBAByQGZKSkhG5w5MV
+++ERWQARaurNyPAgsb1qnUdw8t8GlFLkDT07t74mWo2vsNQXpU0Upv6O+jKNZVMc
+2P/ijQL2Cu7JtLeC5mR6Sj7kAscPr1f4p9b+/B3puIh8tfSBcOY9a3Spi5sg7+xQ
+K6HdoiCKdd4evUrQMwHS47OaKCQuuibm46LWbXO1nk9QkymUy6zyaT5IuNpfKYKD
+UdFqV1FNwZ9A2Yb89rweBgU4DWdbjgVqBc23vS9l913rqd2LHN/4+XDBOGrovu5r
+mJy4WsyXuT0twuqi7FzhtbCdN/zhLo2od1XK6uA65EKdA9rrRMkNeGvxts6q3fPE
+i6tj7OECgYEA/YbIR8n8Vvb5XPAav/aAon4qjXyhkUTjnJfVT0yA+6T1AJwvQ+O4
+AhYgN4ld7msKRDJLcJs0EU8CmWUKJRt5Ai+JsOCbPuBNo+VGEFSsdG0mrSjFZf2e
+Bjm41lnvAEWReGwr9MVIf/prDE2/3aUl9irkNdu5q6NpG9M0N7AhzGECgYEA/M8Y
+Ew9Nv+XqEVKvOzxKRZBa6yzlOUj5PQ3cD7jl1aUNK4rTucvr3sJZAsgm5j+0XG99
+AJ447zdDEdcQbsOSaBR69pccdHYEaRSiIxWaCAir2BBS5DxYtgB6BLrIfBd1cKHv
+qB6u4M6FRJ5BcQa6VYlizAfG2yXoJv0xFrlQ2/0CgYEAwq0Alb+QOOckzCzDHayX
+Ui83VbXiCr6vWMtuTJoeYR1l1LYZxTPTVCbRTlP5AN7I310PeMR00uWsxUVE6QGT
+hg4i2ONf0oRCmhuwFVIvqqc2D7lC+vIoqfcg69fbIoZJEgNeLXJgHYWZNbVuIzBx
+WfnNi13R0O6GA4vGiQyCp4ECgYB1ZTG3wBaJsxlDnBLVPgT7UrJ1nO6A8HsUt/fl
+sSXBVRjNjHUPRTutwLAW050EtLZrajYw8EheBVp20VjHJrg47rG/CqLjDd60cSlt
+g114t5YdCk+DvuYu9f+zbI0m2rnlaL1iY4UvzZcjKx4Wf1pN2DNxrXbRU0P/vvlp
+pPqAfQKBgDZnxWuvRsT9rztGrEottifchfrStZx7u/2+iBtjFeFXr7L4MI14fNm2
+HkoThCpfFXCJFpRxy+kYi6xbPK/Om/hFNs3J5xqheTW8hFx7KN/zPg7jc0MlZ2R/
+uuOgZU9kkzLOamDyP85Doah7kAyA2PnLUno2k4IirbNVoH3aV++G
+-----END RSA PRIVATE KEY-----