OpenSystemsDevelopment / usbboot

Commit c4e2d6e9e1142c79b07847a4527e316afca6c879

Authored by Tim Gover
Committed by GitHub
2 parents 02f4e89a 3e47e26f

Merge pull request #141 from andrum99/patch-1 

Copy edit
Inline Side-by-side
Showing 2 changed files with 42 additions and 42 deletions
Readme.md
  View file @c4e2d6e
1   -# USB device boot code
  1 +# USB Device Boot Code
2 2  
3   -This is the USB MSD boot code which should work on the Raspberry Pi model A, Compute Module, Compute
  3 +This is the USB MSD boot code which supports the Raspberry Pi 1A, Compute Module, Compute
4 4 Module 3, Compute Module 4 and Raspberry Pi Zero.
5 5  
6 6 The default behaviour when run with no arguments is to boot the Raspberry Pi with
7 7 special firmware so that it emulates USB Mass Storage Device (MSD). The host OS
8   -will treat this as a normal USB mass storage device allowing the file-system
  8 +will treat this as a normal USB mass storage device allowing the file system
9 9 to be accessed. If the storage has not been formatted yet (default for Compute Module)
10 10 then the [Raspberry Pi Imager App](https://www.raspberrypi.com/software/) can be
11 11 used to install a new operating system.
12 12  
13   -Since `RPIBOOT` is a generic firmware loading interface it is possible to load
  13 +Since `RPIBOOT` is a generic firmware loading interface, it is possible to load
14 14 other versions of the firmware by passing the `-d` flag to specify the directory
15 15 where the firmware should be loaded from.
16 16 E.g. The firmware in the [msd](msd/README.md) can be replaced with newer/older versions.
17 17  
18   -For more information run `rpiboot -h`
  18 +For more information run `rpiboot -h`.
19 19  
20 20 ## Building
21 21  
22 22 ### Linux / Cygwin / WSL
23   -Clone this on your Pi or a Linux machine.
  23 +Clone this repository on your Pi or other Linux machine.
24 24 Make sure that the system date is set correctly, otherwise Git may produce an error.
25 25  
26 26 ```
... ... @@ -31,7 +31,7 @@ make
31 31 sudo ./rpiboot
32 32 ```
33 33  
34   -sudo isn't required if you have write permissions for the `/dev/bus/usb` device.
  34 +`sudo` isn't required if you have write permissions for the `/dev/bus/usb` device.
35 35  
36 36 ### macOS
37 37 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.
63 63  
64 64  
65 65 <a name="extensions"></a>
66   -## Compute Module 4 extensions
  66 +## Compute Module 4 Extensions
67 67 In addition to the MSD functionality, there are a number of other utilities that can be loaded
68 68 via RPIBOOT on Compute Module 4.
69 69  
... ... @@ -79,7 +79,7 @@ via RPIBOOT on Compute Module 4.
79 79 **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`**
80 80  
81 81 ## Booting Linux
82   -The `RPIBOOT` protocol provides a virtual file-system to the Raspberry Pi bootloader and GPU firmware. It's therefore possible to
  82 +The `RPIBOOT` protocol provides a virtual file system to the Raspberry Pi bootloader and GPU firmware. It's therefore possible to
83 83 boot Linux. To do this, you will need to copy all of the files from a Raspberry Pi boot partition plus create your own
84 84 initramfs.
85 85 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
92 92 not be possible to downgrade to a bootloader older than 2022-01-06 OR disable secure-boot mode.
93 93  
94 94 ### Tutorial
95   -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.
  95 +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.
96 96  
97   -### Host setup
  97 +### Host Setup
98 98 Secure boot require a 2048 bit RSA asymmetric keypair and the Python `pycrytodomex` module to sign the EEPROM config and boot image.
99 99  
100   -#### Install Python Crypto support (the pycryptodomex module)
  100 +#### Install Python Crypto Support (the pycryptodomex module)
101 101 ```bash
102 102 python3 -m pip install pycryptodomex
103 103 # or
... ... @@ -130,7 +130,7 @@ package supports secure boot. To download the firmware files directly.
130 130 A helper script (`make-boot-image`) is provided to automate the image creation process. This
131 131 script depends upon the `mkfs.fat` and `losetup` tools and only runs on Linux.
132 132  
133   -### Root file-system
  133 +### Root File System
134 134 Normally, the Kernel modules and overlays for a secure-boot system would be provided
135 135 in an [initramfs](https://www.raspberrypi.com/documentation/computers/config_txt.html#initramfs)
136 136 and built with [buildroot](https://buildroot.org/) or [yocto](https://www.yoctoproject.org/).
... ...
secure-boot-example/README.md
  View file @c4e2d6e
1   -# Secure-boot quickstart
  1 +# Secure Boot Quickstart
2 2  
3 3 ## Overview
4   -Secure-boot is a mechanism for verifying the integrity of the kernel image and
  4 +Secure boot is a mechanism for verifying the integrity of the kernel image and
5 5 other files required during boot by storing them in a signed ramdisk image.
6   -These files include the GPU firmware (start.elf etc), Kernel, initrd, device-tree tree
  6 +These files include the GPU firmware (start.elf etc), kernel, initrd, Device Tree
7 7 and overlays.
8   -Secure-boot does not depend on particular OS, nor does it provide services
9   -to the OS after startup. However, since the secure-boot will only load trusted
10   -kernel + initrd images the kernel/initrd can safely verify or mount an
11   -an encrypted file-system e.g. by using a TPM.
  8 +Secure boot does not depend on a particular OS, nor does it provide services
  9 +to the OS after startup. However, since secure boot will only load trusted
  10 +kernel and initrd images, the kernel/initrd can safely verify or mount an
  11 +an encrypted file system e.g. by using a TPM.
12 12  
13   -N.B The memory for the secure ramdisk is reclaimed as soon as the CPU is started.
  13 +N.B. The memory for the secure ramdisk is reclaimed as soon as the CPU is started.
14 14  
15 15 ## Example OS
16 16 This example includes a simple buildroot image for Compute Module 4 in order
17   -to demonstrate secure-boot on a simple but functional OS.
  17 +to demonstrate secure boot on a simple but functional OS.
18 18  
19   -The example does NOT modify the OTP or make other permanent changes to the system
20   -and the code-signing can be disabled by reflashing the default bootloader EEPROM.
  19 +The example does NOT modify the OTP or make other permanent changes to the system;
  20 + the code signing can be disabled by reflashing the default bootloader EEPROM.
21 21  
22   -The tutorial does not cover how to create the `boot.img` file or permanently
23   -require secure-boot in OTP. Please see the top level [README](../Readme.md#building) and
  22 +This tutorial does not cover how to create the `boot.img` file or permanently
  23 +require secure boot in OTP. Please see the top level [README](../Readme.md#building) and
24 24 [secure-boot-recovery/README](../secure-boot-recovery/README.md) guides for
25 25 more information.
26 26  
... ... @@ -51,7 +51,7 @@ make
51 51 See the top-level [README](../Readme.md) for build instructions.
52 52  
53 53 ### Hardware setup for `rpiboot` mode
54   -Prepare the Compute Module for `rpiboot` mode.
  54 +Prepare the Compute Module for `rpiboot` mode:
55 55  
56 56 * Set the `nRPIBOOT` jumper which is labelled `Fit jumper to disable eMMC Boot' on the Compute Module 4 IO board.
57 57 * 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.
59 59 * 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.
60 60  
61 61 ### Reset the Compute Module EEPROM
62   -Enable `rpiboot` mode and flash the latest EEPROM image
  62 +Enable `rpiboot` mode and flash the latest EEPROM image:
63 63 ```bash
64 64 ./rpiboot -d recovery
65 65 ```
66 66  
67 67 ### Boot the example image
68   -Enable `rpiboot` mode and load the OS via `rpiboot` without enabling code-signing.
  68 +Enable `rpiboot` mode and load the OS via `rpiboot` without enabling code-signing:
69 69 ```bash
70 70 ./rpiboot -d secure-boot-example
71 71 ```
72 72 The OS should load and show activity on the boot UART and HDMI console.
73 73  
74 74 ### Generate a signing key
75   -Secure-boot requires a 2048 bit RSA private key. You can either use a pre-existing
  75 +Secure boot requires a 2048 bit RSA private key. You can either use a pre-existing
76 76 key or generate an specific key for this example. The `KEY_FILE` environment variable
77 77 used in the following instructions must contain the absolute path to the RSA private key in
78 78 PEM format.
... ... @@ -82,10 +82,10 @@ openssl genrsa 2048 &gt; private.pem
82 82 export KEY_FILE=$(pwd)/private.pem
83 83 ```
84 84  
85   -**In a production environment it's essential that this key-file is stored privately and securely.**
  85 +**In a production environment it's essential that this key file is stored privately and securely.**
86 86  
87 87 ### Update the EEPROM to require signed OS images
88   -Enable `rpiboot` mode and flash the bootloader EEPROM with updated setting enables code-signing.
  88 +Enable `rpiboot` mode and flash the bootloader EEPROM with updated setting enables code signing.
89 89  
90 90 The `boot.conf` file sets the `SIGNED_BOOT` property `1` which instructs the bootloader to only
91 91 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 ..
113 113  
114 114 ### Launch the signed OS image
115 115 Enable `rpiboot` mode and run the example OS as before. However, if the
116   -`boot.sig` signature does not match `boot.img` the bootloader will refuse to
  116 +`boot.sig` signature does not match `boot.img`, the bootloader will refuse to
117 117 load the OS.
118 118  
119 119 ```bash
... ... @@ -124,35 +124,35 @@ This example OS image is minimal Linux ramdisk image. Login as `root` with the e
124 124  
125 125 ### Mount the CM4 SD/EMMC after enabling secure-boot
126 126 Now that `SIGNED_BOOT` is enabled the bootloader will only load images signed with private key generated earlier.
127   -To boot the Compute Module in mass-storage mode a signed version of this code must be generated.
  127 +To boot the Compute Module in mass storage mode a signed version of this code must be generated.
128 128  
129   -**This signed-image should not be made available for download because it gives access to the EMMC as a block device**
  129 +**This signed image should not be made available for download because it gives access to the EMMC as a block device.**
130 130  
131 131  
132 132 #### Sign the mass storage firmware image
133   -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.
  133 +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.
134 134 ```bash
135 135 cd secure-boot-msd
136 136 ../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
137 137 cd ..
138 138 ```
139 139  
140   -#### Enable MSD mode.
141   -A new mass-storage device should now be visible on the host-OS. On Linux check `dmesg` for something like '/dev/sda'
  140 +#### Enable MSD mode
  141 +A new mass storage device should now be visible on the host OS. On Linux check `dmesg` for something like '/dev/sda'.
142 142 ```bash
143 143 ./rpiboot -d secure-boot-msd
144 144 ```
145 145  
146   -### Loading `boot.img` from SD/EMMC.
  146 +### Loading `boot.img` from SD/EMMC
147 147 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.
148 148  
149   -For example.
  149 +For example:
150 150  
151 151 * Boot the CM4 in MSD mode as explained in the previous step.
152   -* Copy the `boot.img` and `boot.sig` files from the `secure-boot-example` stage to the mass-storage-drive. No other files are required.
  152 +* Copy the `boot.img` and `boot.sig` files from the `secure-boot-example` stage to the mass storage drive: No other files are required.
153 153 * Remove the `nRPIBOOT` jumper.
154 154 * Power cycle the CM4 IO board.
155 155 * The system should now boot into the OS.
156 156  
157   -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.
  157 +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.
158 158  
... ...