OpenSystemsDevelopment / usbboot

Commit 3e47e26fdcbbcf7022d1c06ea68b9dbf017e24d6

Authored by andrum99
Committed by GitHub
1 parent 314a141d

Update README.md

Inline Side-by-side
Showing 1 changed file with 29 additions and 29 deletions
secure-boot-example/README.md
  View file @3e47e26
1 -# Secure-boot quickstart 1 +# Secure Boot Quickstart
2 2
3 ## Overview 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 other files required during boot by storing them in a signed ramdisk image. 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 and overlays. 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 ## Example OS 15 ## Example OS
16 This example includes a simple buildroot image for Compute Module 4 in order 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 [secure-boot-recovery/README](../secure-boot-recovery/README.md) guides for 24 [secure-boot-recovery/README](../secure-boot-recovery/README.md) guides for
25 more information. 25 more information.
26 26
@@ -51,7 +51,7 @@ make @@ -51,7 +51,7 @@ make
51 See the top-level [README](../Readme.md) for build instructions. 51 See the top-level [README](../Readme.md) for build instructions.
52 52
53 ### Hardware setup for `rpiboot` mode 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 * Set the `nRPIBOOT` jumper which is labelled `Fit jumper to disable eMMC Boot' on the Compute Module 4 IO board. 56 * Set the `nRPIBOOT` jumper which is labelled `Fit jumper to disable eMMC Boot' on the Compute Module 4 IO board.
57 * Connect the micro USB cable to the `USB slave` port on the CM4 IO board. 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,20 +59,20 @@ Prepare the Compute Module for `rpiboot` mode.
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. 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 ### Reset the Compute Module EEPROM 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 ```bash 63 ```bash
64 ./rpiboot -d recovery 64 ./rpiboot -d recovery
65 ``` 65 ```
66 66
67 ### Boot the example image 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 ```bash 69 ```bash
70 ./rpiboot -d secure-boot-example 70 ./rpiboot -d secure-boot-example
71 ``` 71 ```
72 The OS should load and show activity on the boot UART and HDMI console. 72 The OS should load and show activity on the boot UART and HDMI console.
73 73
74 ### Generate a signing key 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 key or generate an specific key for this example. The `KEY_FILE` environment variable 76 key or generate an specific key for this example. The `KEY_FILE` environment variable
77 used in the following instructions must contain the absolute path to the RSA private key in 77 used in the following instructions must contain the absolute path to the RSA private key in
78 PEM format. 78 PEM format.
@@ -82,10 +82,10 @@ openssl genrsa 2048 > private.pem @@ -82,10 +82,10 @@ openssl genrsa 2048 > private.pem
82 export KEY_FILE=$(pwd)/private.pem 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 ### Update the EEPROM to require signed OS images 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 The `boot.conf` file sets the `SIGNED_BOOT` property `1` which instructs the bootloader to only 90 The `boot.conf` file sets the `SIGNED_BOOT` property `1` which instructs the bootloader to only
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. 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,7 +113,7 @@ cd ..
113 113
114 ### Launch the signed OS image 114 ### Launch the signed OS image
115 Enable `rpiboot` mode and run the example OS as before. However, if the 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 load the OS. 117 load the OS.
118 118
119 ```bash 119 ```bash
@@ -124,35 +124,35 @@ This example OS image is minimal Linux ramdisk image. Login as `root` with the e @@ -124,35 +124,35 @@ This example OS image is minimal Linux ramdisk image. Login as `root` with the e
124 124
125 ### Mount the CM4 SD/EMMC after enabling secure-boot 125 ### Mount the CM4 SD/EMMC after enabling secure-boot
126 Now that `SIGNED_BOOT` is enabled the bootloader will only load images signed with private key generated earlier. 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 #### Sign the mass storage firmware image 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 ```bash 134 ```bash
135 cd secure-boot-msd 135 cd secure-boot-msd
136 ../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}" 136 ../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
137 cd .. 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 ```bash 142 ```bash
143 ./rpiboot -d secure-boot-msd 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 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. 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 * Boot the CM4 in MSD mode as explained in the previous step. 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 * Remove the `nRPIBOOT` jumper. 153 * Remove the `nRPIBOOT` jumper.
154 * Power cycle the CM4 IO board. 154 * Power cycle the CM4 IO board.
155 * The system should now boot into the OS. 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