diff --git a/Readme.md b/Readme.md index 5acc200..c63771f 100644 --- a/Readme.md +++ b/Readme.md @@ -1,26 +1,26 @@ -# USB device boot code +# USB Device Boot Code -This is the USB MSD boot code which should work on the Raspberry Pi model A, Compute Module, Compute +This is the USB MSD boot code which supports the Raspberry Pi 1A, Compute Module, Compute Module 3, Compute Module 4 and Raspberry Pi Zero. The default behaviour when run with no arguments is to boot the Raspberry Pi with special firmware so that it emulates USB Mass Storage Device (MSD). The host OS -will treat this as a normal USB mass storage device allowing the file-system +will treat this as a normal USB mass storage device allowing the file system to be accessed. If the storage has not been formatted yet (default for Compute Module) then the [Raspberry Pi Imager App](https://www.raspberrypi.com/software/) can be used to install a new operating system. -Since `RPIBOOT` is a generic firmware loading interface it is possible to load +Since `RPIBOOT` is a generic firmware loading interface, it is possible to load other versions of the firmware by passing the `-d` flag to specify the directory where the firmware should be loaded from. E.g. The firmware in the [msd](msd/README.md) can be replaced with newer/older versions. -For more information run `rpiboot -h` +For more information run `rpiboot -h`. ## Building ### Linux / Cygwin / WSL -Clone this on your Pi or a Linux machine. +Clone this repository on your Pi or other Linux machine. Make sure that the system date is set correctly, otherwise Git may produce an error. ``` @@ -31,7 +31,7 @@ make sudo ./rpiboot ``` -sudo isn't required if you have write permissions for the `/dev/bus/usb` device. +`sudo` isn't required if you have write permissions for the `/dev/bus/usb` device. ### macOS From a macOS machine, you can also run usbboot, just follow the same steps: @@ -63,7 +63,7 @@ Otherwise, the SPI EEPROM bootloader image will be loaded instead. -## Compute Module 4 extensions +## Compute Module 4 Extensions In addition to the MSD functionality, there are a number of other utilities that can be loaded via RPIBOOT on Compute Module 4. @@ -79,7 +79,7 @@ via RPIBOOT on Compute Module 4. **The `secure-boot-msd`, `rpi-imager-embedded` and `mass-storage-gadget` extensions require that the `2022-04-26` (or newer) bootloader EEPROM release has already been written to the EEPROM using `recovery.bin`** ## Booting Linux -The `RPIBOOT` protocol provides a virtual file-system to the Raspberry Pi bootloader and GPU firmware. It's therefore possible to +The `RPIBOOT` protocol provides a virtual file system to the Raspberry Pi bootloader and GPU firmware. It's therefore possible to boot Linux. To do this, you will need to copy all of the files from a Raspberry Pi boot partition plus create your own initramfs. On Raspberry Pi 4 / CM4 the recommended approach is to use a `boot.img` which is a FAT disk image containing @@ -92,12 +92,12 @@ WARNING: If the `revoke_devkey` option is used to revoke the ROM development key not be possible to downgrade to a bootloader older than 2022-01-06 OR disable secure-boot mode. ### Tutorial -Creating a secure-boot system from scratch can be quite complex. The [secure-boot tutorial](secure-boot-example/README.md) uses a minimal example OS image to demonstrate how the Raspberry Pi specific aspects of secure-boot work. +Creating a secure boot system from scratch can be quite complex. The [secure boot tutorial](secure-boot-example/README.md) uses a minimal example OS image to demonstrate how the Raspberry Pi-specific aspects of secure boot work. -### Host setup +### Host Setup Secure boot require a 2048 bit RSA asymmetric keypair and the Python `pycrytodomex` module to sign the EEPROM config and boot image. -#### Install Python Crypto support (the pycryptodomex module) +#### Install Python Crypto Support (the pycryptodomex module) ```bash python3 -m pip install pycryptodomex # or @@ -130,7 +130,7 @@ package supports secure boot. To download the firmware files directly. A helper script (`make-boot-image`) is provided to automate the image creation process. This script depends upon the `mkfs.fat` and `losetup` tools and only runs on Linux. -### Root file-system +### Root File System Normally, the Kernel modules and overlays for a secure-boot system would be provided in an [initramfs](https://www.raspberrypi.com/documentation/computers/config_txt.html#initramfs) and built with [buildroot](https://buildroot.org/) or [yocto](https://www.yoctoproject.org/). diff --git a/secure-boot-example/README.md b/secure-boot-example/README.md index ca17f3d..8146367 100644 --- a/secure-boot-example/README.md +++ b/secure-boot-example/README.md @@ -1,26 +1,26 @@ -# Secure-boot quickstart +# Secure Boot Quickstart ## Overview -Secure-boot is a mechanism for verifying the integrity of the kernel image and +Secure boot is a mechanism for verifying the integrity of the kernel image and other files required during boot by storing them in a signed ramdisk image. -These files include the GPU firmware (start.elf etc), Kernel, initrd, device-tree tree +These files include the GPU firmware (start.elf etc), kernel, initrd, Device Tree and overlays. -Secure-boot does not depend on particular OS, nor does it provide services -to the OS after startup. However, since the secure-boot will only load trusted -kernel + initrd images the kernel/initrd can safely verify or mount an -an encrypted file-system e.g. by using a TPM. +Secure boot does not depend on a particular OS, nor does it provide services +to the OS after startup. However, since secure boot will only load trusted +kernel and initrd images, the kernel/initrd can safely verify or mount an +an encrypted file system e.g. by using a TPM. -N.B The memory for the secure ramdisk is reclaimed as soon as the CPU is started. +N.B. The memory for the secure ramdisk is reclaimed as soon as the CPU is started. ## Example OS This example includes a simple buildroot image for Compute Module 4 in order -to demonstrate secure-boot on a simple but functional OS. +to demonstrate secure boot on a simple but functional OS. -The example does NOT modify the OTP or make other permanent changes to the system -and the code-signing can be disabled by reflashing the default bootloader EEPROM. +The example does NOT modify the OTP or make other permanent changes to the system; + the code signing can be disabled by reflashing the default bootloader EEPROM. -The tutorial does not cover how to create the `boot.img` file or permanently -require secure-boot in OTP. Please see the top level [README](../Readme.md#building) and +This tutorial does not cover how to create the `boot.img` file or permanently +require secure boot in OTP. Please see the top level [README](../Readme.md#building) and [secure-boot-recovery/README](../secure-boot-recovery/README.md) guides for more information. @@ -51,7 +51,7 @@ make See the top-level [README](../Readme.md) for build instructions. ### Hardware setup for `rpiboot` mode -Prepare the Compute Module for `rpiboot` mode. +Prepare the Compute Module for `rpiboot` mode: * Set the `nRPIBOOT` jumper which is labelled `Fit jumper to disable eMMC Boot' on the Compute Module 4 IO board. * Connect the micro USB cable to the `USB slave` port on the CM4 IO board. @@ -59,20 +59,20 @@ Prepare the Compute Module for `rpiboot` mode. * Connect the USB serial adapter to [GPIO 14/15](https://www.raspberrypi.com/documentation/computers/os.html#gpio-and-the-40-pin-header) on the 40-pin header. ### Reset the Compute Module EEPROM -Enable `rpiboot` mode and flash the latest EEPROM image +Enable `rpiboot` mode and flash the latest EEPROM image: ```bash ./rpiboot -d recovery ``` ### Boot the example image -Enable `rpiboot` mode and load the OS via `rpiboot` without enabling code-signing. +Enable `rpiboot` mode and load the OS via `rpiboot` without enabling code-signing: ```bash ./rpiboot -d secure-boot-example ``` The OS should load and show activity on the boot UART and HDMI console. ### Generate a signing key -Secure-boot requires a 2048 bit RSA private key. You can either use a pre-existing +Secure boot requires a 2048 bit RSA private key. You can either use a pre-existing key or generate an specific key for this example. The `KEY_FILE` environment variable used in the following instructions must contain the absolute path to the RSA private key in PEM format. @@ -82,10 +82,10 @@ openssl genrsa 2048 > private.pem export KEY_FILE=$(pwd)/private.pem ``` -**In a production environment it's essential that this key-file is stored privately and securely.** +**In a production environment it's essential that this key file is stored privately and securely.** ### Update the EEPROM to require signed OS images -Enable `rpiboot` mode and flash the bootloader EEPROM with updated setting enables code-signing. +Enable `rpiboot` mode and flash the bootloader EEPROM with updated setting enables code signing. The `boot.conf` file sets the `SIGNED_BOOT` property `1` which instructs the bootloader to only load files (firmware, kernel, overlays etc) from `boot.img` instead of the normal boot partition and verify the `boot.img` signature `boot.sig` using the public key in the EEPROM. @@ -113,7 +113,7 @@ cd .. ### Launch the signed OS image Enable `rpiboot` mode and run the example OS as before. However, if the -`boot.sig` signature does not match `boot.img` the bootloader will refuse to +`boot.sig` signature does not match `boot.img`, the bootloader will refuse to load the OS. ```bash @@ -124,35 +124,35 @@ This example OS image is minimal Linux ramdisk image. Login as `root` with the e ### Mount the CM4 SD/EMMC after enabling secure-boot Now that `SIGNED_BOOT` is enabled the bootloader will only load images signed with private key generated earlier. -To boot the Compute Module in mass-storage mode a signed version of this code must be generated. +To boot the Compute Module in mass storage mode a signed version of this code must be generated. -**This signed-image should not be made available for download because it gives access to the EMMC as a block device** +**This signed image should not be made available for download because it gives access to the EMMC as a block device.** #### Sign the mass storage firmware image -Sign the mass-storage drivers in the `secure-boot-msd` directory. Please see the [top level README](../Readme.md#compute-module-4-extensions) for a description of the different `usbboot` firmware drivers. +Sign the mass storage drivers in the `secure-boot-msd` directory. Please see the [top level README](../Readme.md#compute-module-4-extensions) for a description of the different `usbboot` firmware drivers. ```bash cd secure-boot-msd ../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}" cd .. ``` -#### Enable MSD mode. -A new mass-storage device should now be visible on the host-OS. On Linux check `dmesg` for something like '/dev/sda' +#### Enable MSD mode +A new mass storage device should now be visible on the host OS. On Linux check `dmesg` for something like '/dev/sda'. ```bash ./rpiboot -d secure-boot-msd ``` -### Loading `boot.img` from SD/EMMC. +### Loading `boot.img` from SD/EMMC The bootloader can load a ramdisk `boot.img` from any of the bootable modes defined by the [BOOT_ORDER](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#BOOT_ORDER) EEPROM config setting. -For example. +For example: * Boot the CM4 in MSD mode as explained in the previous step. -* Copy the `boot.img` and `boot.sig` files from the `secure-boot-example` stage to the mass-storage-drive. No other files are required. +* Copy the `boot.img` and `boot.sig` files from the `secure-boot-example` stage to the mass storage drive: No other files are required. * Remove the `nRPIBOOT` jumper. * Power cycle the CM4 IO board. * The system should now boot into the OS. -N.B. The example image is currently the same as the `mass-storage-gadget so the EMMC/SD will appear as block devices on the host PC if the micro USB cable is still connected. +N.B. The example image is currently the same as the `mass storage-gadget`, so the EMMC/SD will appear as block devices on the host PC if the micro USB cable is still connected.