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 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 > 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  
... ...