docs: Update mass-storage gadget + secure-boot

* Remove the reference to LEDs flashing with mass-storage-gadget because this code was removed. * Mention LUKS / rpi-otp-private-key in the secure-boot section. * Add a link to the PIP * Drop reference to make-boot-image - just use buildroot.

docs: Update mass-storage gadget + secure-boot
* Remove the reference to LEDs flashing with mass-storage-gadget because this code was removed. * Mention LUKS / rpi-otp-private-key in the secure-boot section. * Add a link to the PIP * Drop reference to make-boot-image - just use buildroot.
Tim Gover
1 parent 1ae3d7ec
Showing 3 changed files with 60 additions and 59 deletions
Readme.md
mass-storage-gadget/README.md
secure-boot-example/README.md
@@ -91,6 +91,9 @@ the minimal set of files required from the boot partition.
  
 This section describes how to diagnose common `rpiboot` failures for Compute Modules. Whilst `rpiboot` is tested on every Compute Module during manufacture the system relies on multiple hardware and software elements. The aim of this guide is to make it easier to identify which component is failing.
  
+### Product Information Portal
+The [Product Information Portal](https://pip.raspberrypi.com/) contains the official documentation for hardware revision changes for Raspberry Pi computers.
+
 ### Hardware
 * Inspect the Compute Module pins and connector for signs of damage and verify that the socket is free from debris.
 * Check that the Compute Module is fully inserted.
@@ -157,7 +160,7 @@ openssl genrsa 2048 &gt; private.pem
 Secure Boot requires self-contained ramdisk (`boot.img`) FAT image to be created containing the GPU
 firmware, kernel and any other dependencies that would normally be loaded from the boot partition.
  
-This plus a signature file (boot.sig) must be placed in the boot partition of the Raspberry Pi
+This plus a signature file (`boot.sig`) must be placed in the boot partition of the Raspberry Pi
 or network download location.
  
 The `boot.img` file should contain:-
@@ -166,10 +169,39 @@ The `boot.img` file should contain:-
 * GPU firmware (start.elf and fixup.dat)
 * Linux initramfs containing the application OR scripts to mount/create an encrypted file-system.
  
-Secure boot is only responsible for loading a verified Linux kernel and initramfs. It does NOT
-verify the integrity of other file-systems or provide file-system encryption. This would normally be
-implemented using standard Linux tools such as [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup).
-and controlled by scripts / systemd services in an initramfs.
+
+### Disk encryption
+Secure-boot loads the `boot.img` from an unencrypted FAT / EFI boot partition and is responsible for
+loading the Kernel + initramfs. There is no support in the firmware or ROM for full-disk encryption.
+
+If a custom OS image needs to use an encrypted file-system then this would normally be implement
+via scripts within the initramfs.
+
+Raspberry Pi computers do not have a secure enclave, however, it's possible to store a 256 bit
+[device specific private key](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#device-specific-private-key)
+in OTP. The key is accessible to any process with access to `/dev/vcio` (`vcmailbox`) so the
+secure-boot OS must ensure that access to this interface is restricted.
+
+**It's not possible to prevent code kernel code from accessing OTP directly**
+
+See also:-
+* [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)
+* [cryptsetup FAQ](https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions)
+* [rpi-otp-private-key](../tools/rpi-otp-private-key)
+
+Example script which uses a device-specific private key to create/mount an encrypted file-system.
+```bash
+export BLK_DEV=/dev/mmcblk0p3
+export KEY_FILE=$(mktemp -d)/key.bin
+rpi-otp-private-key -b > "${KEY_FILE}"
+cryptsetup luksFormat --key-file="${KEY_FILE}" --key-size=256 --type=luks2 ${BLK_DEV}
+
+cryptsetup luksOpen ${BLK_DEV} encrypted-disk --key-file="${KEY_FILE}"
+mkfs /dev/mapper/encrypted-disk
+mkdir -p /mnt/application-data
+mount /dev/mapper/encrypted-disk /mnt/application-data
+rm "${KEY_FILE}"
+```
  
 ### Building `boot.img` using buildroot
  
@@ -181,17 +213,6 @@ buildroot config. Whilst not a generic fully featured configuration it should be
 straightforward to cherry-pick the `raspberrypi-secure-boot` package and helper scripts into
 other buildroot configurations.
  
-### Manual boot image creation
-For other systems or manual image creation a helper script `make-boot-image` in the tools
-directory is provided.
-
-To run:-
-* Copy the source firmware + other files into a temporary directory  (`temp`)
-* Run `make-boot-image -d temp -O boot.img`
-* Run `rpi-eeprom-digest -i boot.img -o boot.sig -k private-key.PEM`
-
-`make-boot-image` depends upon the `mkfs.fat` and `losetup` Linux tools.
-
 #### Minimum firmware version
 The firmware must be new enough to support secure boot. The latest firmware APT
 package supports secure boot. To download the firmware files directly.
@@ -205,7 +226,7 @@ To check the version information within a `start4.elf` firmware file run
 strings start4.elf | grep VC_BUILD_
 ```
  
-#### Verifying a boot image
+#### Verifying the contents of a `boot.img` file
 To verify that the boot image has been created correctly use losetup to mount the .img file.
  
 ```bash
@@ -7,6 +7,21 @@ USB mass storage devices using the Linux gadget-fs drivers.
 This allows Raspberry Pi Imager to be run on the host computer
 and write OS images to the Compute Module block devices.
  
+## Running
+To run load the USB MSD device drivers via RPIBOOT run
+```bash
+cd mass-storage-gadget
+../rpiboot -d .
+
+```
+N.B. This takes a few seconds longer to initialise than the 
+previous mass storage implementation. However, the write speed
+should be much faster now that all of the file-system code
+is running on the ARM processors.
+
+### Debug
+The mass-storage-gadget image automatically enables a UART console for debugging (user `root` empty password).
+
 ## secure-boot
 If secure-boot mode has been locked (via OTP) then both the
 bootloader and rpiboot `bootcode4.bin` will only load `boot.img`
@@ -25,24 +40,6 @@ KEY_FILE=$HOME/private.pem
 ../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
 ```
  
-## Running
-To run load the USB MSD device drivers via RPIBOOT run
-```bash
-../rpiboot -d .
-```
-
-The activity LED will flash three times once the USB MSD
-devices have been initialised. A message will also be printed
-to the HDMI console.
-
-The UART console is also enabled (user 'root' no password)
-so that the user can login and debug the Compute Module.
-
-N.B. This takes a few seconds longer to initialise than the 
-previous mass storage implementation. However, the write speed
-should be much faster now that all of the file-system code
-is running on the ARM processors.
-
 ## Source code
 The buildroot configuration and supporting patches is available on
 the [mass-storage-gadget](https://github.com/raspberrypi/buildroot/tree/mass-storage-gadget)
@@ -58,18 +55,3 @@ make
  
 The output is written to `output/target/images/sdcard.img` and can be copied
 to `boot.img`
-
-Optional:
-Load time can be reduced by optmizing the size of the sdcard.img as
-follows (run as root).
-
-```bash
-mkdir -p source-files
-kpartx -av sdcard.img
-mount /dev/mapper/loop0p1 source-files/
-usbboot/tools/make-boot-image -d source-files/ -o boot.img
-umount source-files
-kpartx -dv sdcard.img
-dmsetup remove /dev/mapper/loop0p1
-losetup -D
-```
 # 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+initramfs 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
 and overlays.
+
 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.
+to the OS after the Kernel + initramfs has started.
  
 N.B. The memory for the secure ramdisk is reclaimed as soon as the CPU is started.
  
@@ -100,7 +99,7 @@ cd ..
 ./rpiboot -d secure-boot-recovery
 ```
  
-At this stage OTP has not been modified and the signed image requirement can be reverted by flashing a default, unsigned image. 
+At this stage OTP has not been modified and the signed image requirement can be reverted by flashing a default, unsigned image.
 However, once the [OTP secure-boot flags](../secure-boot-recovery/README.md#locking-secure-boot-mode) are set then `SIGNED_BOOT` is permanently enabled and cannot be overridden via the EEPROM config.
  
  
@@ -123,9 +122,9 @@ load the OS.
 This example OS image is minimal Linux ramdisk image. Login as `root` with the empty password.
  
 ### 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.  
-  
+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.
+
 **This signed image should not be made available for download because it gives access to the EMMC as a block device.**
  
  
@@ -155,4 +154,3 @@ For example:
 * The system should now boot into the OS.
  
 The secure-boot example image can be rebuilt and modified using buildroot. See [raspberrypi-signed-boot buildroot](https://github.com/raspberrypi/buildroot/blob/raspberrypi-signed-boot/README.md)
-