secure-boot-example: Update boot.img and docs for cryptsetup example

Tim Gover
1 parent 4a21a619
Showing 4 changed files with 47 additions and 29 deletions
Readme.md
secure-boot-example/README.md
secure-boot-example/boot.img
secure-boot-example/boot.sig
@@ -93,6 +93,7 @@ This section describes how to diagnose common `rpiboot` failures for Compute Mod
  
 ### Product Information Portal
 The [Product Information Portal](https://pip.raspberrypi.com/) contains the official documentation for hardware revision changes for Raspberry Pi computers.
+Please check this first to check that the software is up to date.
  
 ### Hardware
 * Inspect the Compute Module pins and connector for signs of damage and verify that the socket is free from debris.
@@ -137,7 +138,7 @@ Secure Boot requires a recent bootloader stable image e.g. the version in this r
 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
-Secure boot require a 2048 bit RSA asymmetric keypair and the Python `pycrytodomex` module to sign the EEPROM config and boot image.
+Secure boot require a 2048 bit RSA asymmetric keypair and the Python `pycrytodomex` module to sign the bootloader EEPROM config and boot image.
  
 #### Install Python Crypto Support (the pycryptodomex module)
 ```bash
@@ -171,37 +172,27 @@ The `boot.img` file should contain:-
  
  
 ### 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.
+Secure-boot is responsible for loading the Kernel + initramfs and loads all of the data
+from a single `boot.img` file stored on an unencrypted FAT/EFI partition.
  
-If a custom OS image needs to use an encrypted file-system then this would normally be implement
+**There is no support in the ROM or firmware for full-disk encryption.**
+
+If a custom OS image needs to use an encrypted file-system then this would normally be implemented
 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
+in OTP. The key is accessible to any process with access to `/dev/vcio` (`vcmailbox`), therefore, 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**
+**It is not possible to prevent code running in ARM supervisor mode (e.g. kernel code) from accessing OTP hardware 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}"
-```
+The [secure boot tutorial](secure-boot-example/README.md) contains a `boot.img` that supports cryptsetup and a simple example.
  
 ### Building `boot.img` using buildroot
  
@@ -278,4 +269,5 @@ openssl rsa -in private.pem -pubout -out public.pem
 ```
  
 #### Copy the secure boot image to the boot partition on the Raspberry Pi.
-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).
+Copy `boot.img` and `boot.sig` to the boot filesystem.
+Secure boot images can be loaded from any of the normal boot modes (e.g. SD, USB, Network).
@@ -16,12 +16,10 @@ This example includes a simple buildroot image for Compute Module 4 in order
 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;
- the code signing can be disabled by reflashing the default bootloader EEPROM.
+the code signing can be disabled by reflashing the default bootloader EEPROM.
  
-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.
+Please see the top level [README](../Readme.md#building) and [secure-boot-recovery/README](../secure-boot-recovery/README.md) guides for
+instructions about how to permanently enable secure-boot by programming OTP.
  
 ### Requirements for running this example
 * A Raspberry Pi Compute Module 4
@@ -121,6 +119,33 @@ load the OS.
  
 This example OS image is minimal Linux ramdisk image. Login as `root` with the empty password.
  
+#### Disk encryption example
+Example script which uses a device-specific private key to create/mount an encrypted file-system.
+
+Generating a 256-bit random key for test purposes.
+```bash
+export KEY_FILE=$(mktemp -d)/key.bin
+openssl rand -hex 32 | xxd -rp > ${KEY_FILE}
+```
+
+Using [rpi-otp-private-key](../tools/rpi-otp-private-key) to extract the device private key (if programmed).
+```bash
+export KEY_FILE=$(mktemp -d)/key.bin
+rpi-otp-private-key -b > "${KEY_FILE}"
+```
+
+Creating an encrypted disk on a specified block device.
+```bash
+export BLK_DEV=/dev/mmcblk0p3
+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}"
+```
+
 ### 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.
@@ -153,4 +178,5 @@ For example:
 * Power cycle the CM4 IO board.
 * 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)
+### Modifying / rebuilding `boot.img`
+The secure-boot example image can be rebuilt and modified using buildroot. See [raspberrypi-signed-boot](https://github.com/raspberrypi/buildroot/blob/raspberrypi-signed-boot/README.md) buildroot configuration.
-eaf0471182874f0b80e6fdfa2c801bd3ea6f7bdc21a807d2c616bad8d88fc417
-ts: 1666183916
-rsa2048: bbb15b0d7f90c8f022b8fad9766258dadb7a0a0aad5af7daf846cccccf49b8d0bc72ef3fb2551f630786642b7fbe9e3e11328b72bc41698ffc8928bd058b6b37d09cb6d35ecc427be1f4b1a897bcf480b80dc1eb109526f512cad23d2744c8e3538447e45156c6bf3dd5b89401ee9d933b8dcb3d20ada352d18312f42b7bae54131eb0a33449fe2a5cf4bf0b5c7f1f3f94d683e76806465d903156bab19542fe2e96a2d99f1b8d1332962109dd7a0b317add8448fa43beb7ecb1f333303a989d6534ef653e9f1466ce0beac620759fbcc22ad1b622a8dc9bd2c278886b117c038f0f7edfd1b580d44ddfc4303e0c41c9819ffa3afff7361e84a2b964bb2b01cd
+946e19fa1396e99aaee32259deeaeb130396f2fc32b240d0a690bee7e25c5a0a
+ts: 1668104408
+rsa2048: afe8c8a8b150d8d317858c24175a942ca10ee47df9e3f546a0fa1bee9fb0e276036c1ed03151de15b048f782e98800a0c17ccda4a7605be9c8585e88c007fd0803545e138d3b537afc7b85696b330617322605a91fa066ae9cdcbd6946ef14be9f00ef0539dcd490af0a87c91e02c82e6fde122fdf3f904c09a6fd9cfbc5c31f0ab4fd5f5aa584c1c9f7a3d46dc298ad164a86c853eaedc3d8822f9a0102e7d4929579d8c90e000dba5b69ca2d52d18e2a5239d86a178ffd07521821dda626a517c7368ad12d44c42df22e7fe589d5b9cd0f49ecd4367e270f2891043fd313ea0bcfcda28ef87f8e2a0ada7db32ae04d2aa44dc03cf9ce6e83dda339deba8241