From 5f8c23365006d689e49d99029ddb3d9713c2c90a Mon Sep 17 00:00:00 2001
From: tim <tim.gover@raspberrypi.org>
Date: Fri, 29 Oct 2021 09:28:42 +0100
Subject: [PATCH] secure-boot: Add more documentation about the RSA signatures and add optional public key argument

---
 Readme.md                              | 19 +++++++++++++++++++
 secure-boot-example/README.md          |  3 +++
 secure-boot-example/example-public.pem |  9 +++++++++
 secure-boot-msd/README.md              | 14 ++++++++++----
 tools/update-pieeprom.sh               | 28 ++++++++++++++++++++++++----
 5 files changed, 65 insertions(+), 8 deletions(-)
 create mode 100644 secure-boot-example/README.md
 create mode 100644 secure-boot-example/example-public.pem

diff --git a/Readme.md b/Readme.md
index e399766..7b2fc7f 100644
--- a/Readme.md
+++ b/Readme.md
@@ -140,9 +140,28 @@ rmdir boot-mount
 ```
 
 #### Sign the boot image
+For secure-boot, `rpi-eeprom-digest` extends the current `.sig` format of
+sha256 + timestamp to include an hex format RSA bit PKCS#1 v1.5 signature. The key length
+must be 2048 bits.
+
 ```bash
 ../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
 ```
+#### Hardware security modules
+`rpi-eeprom-digest` is a shell script that wraps a call to `openssl dgst -sign`.
+If the private key is stored withing a hardware security module instead of
+a .PEM file the `openssl` command will need to be replaced with the appropriate call to the HSM.
+
+`rpi-eeprom-digest` called by `update-pieeprom.sh` to sign the EEPROM config file.
+
+The RSA public key must be stored within the EEPROM so that it can be used by the bootloader.
+By default, the RSA public key is automatically extracted from the private key PEM file. Alternatively,
+the public key may be specified separately via the `-p` argument to `update-pieeprom.sh` and `rpi-eeprom-config`.
+
+To extract the public key in PEM format from a private key PEM file run.
+```bash
+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).
diff --git a/secure-boot-example/README.md b/secure-boot-example/README.md
new file mode 100644
index 0000000..b2709d7
--- /dev/null
+++ b/secure-boot-example/README.md
@@ -0,0 +1,3 @@
+This directory contains an example secure boot image signed with the example private key in this directory.
+
+Clearly, product releases should never be signed with `example-private.pem`.
diff --git a/secure-boot-example/example-public.pem b/secure-boot-example/example-public.pem
new file mode 100644
index 0000000..ea6d4dc
--- /dev/null
+++ b/secure-boot-example/example-public.pem
@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA+l3E+h/QNjrIR1cG6Npz
+P0fBwp2UDpuQAafXDS5yryrfCPDYTO9DvzAfOk9Dz/putDfHV0RTOFXv1tmc4nqO
+gU6nKx7tTdsjTiY4CgG3vXRMuAmDGX5ssJFCVmljGuILt1INlCmtun7Ow35VTxOc
+RDDfrBDKnSitzOTf6KTR7xJhqFFhdMpIg8hW4bDBKMavyt38pRvDaO1o01qaQT/G
+gAPmJm27y5RKNAe6iVTqsm4TMAhKC6P4XyRAbe6OMdFZyEWEk7Asexuc7uZlVHsU
+I6pebSW/07O+5l/U7/3k6r//hO/HDFOBUUW55EjzzC1BhTlWHWfZNI+5+NdN8o32
+3QIDAQAB
+-----END PUBLIC KEY-----
diff --git a/secure-boot-msd/README.md b/secure-boot-msd/README.md
index 3480db8..702f6ce 100644
--- a/secure-boot-msd/README.md
+++ b/secure-boot-msd/README.md
@@ -1,11 +1,17 @@
 # USB MSD device mode drivers for signed-boot
 
-If secure-boot has been enabled then this image must be signed with
-the customer's RSA private key. Otherwise, the SPI EEPROM bootloader
-will refused to load this image.
+If secure-boot mode has been locked (via OTP) then both the
+bootloader and rpiboot `bootcode4.bin` will only load `boot.img`
+files signed with the customer's private key. Therefore, access
+to rpiboot mass storage mode is disabled.
 
-To do this run:
+Mass storage mode can be re-enabled by signing a boot image
+containing the firmware mass storage drivers.
 
+N.B. The signed image should normally be kept secure because can
+be used on any device signed with the same customer key.
+
+To sign the mass storage mode boot image run:-
 ```bash
 KEY_FILE=$HOME/private.pem
 ../tools/rpi-eeprom-digest -i boot.img -o boot.sig -k "${KEY_FILE}"
diff --git a/tools/update-pieeprom.sh b/tools/update-pieeprom.sh
index bc4146d..3433a9f 100755
--- a/tools/update-pieeprom.sh
+++ b/tools/update-pieeprom.sh
@@ -16,6 +16,7 @@ SRC_IMAGE="pieeprom.original.bin"
 CONFIG="boot.conf"
 DST_IMAGE="pieeprom.bin"
 PEM_FILE=""
+PUBLIC_PEM_FILE=""
 TMP_CONFIG_SIG=""
 
 die() {
@@ -43,12 +44,19 @@ cat <<EOF
     -c Bootloader config file - default: "${SRC_IMAGE}"
     -i Source EEPROM image - default: "${CONFIG}"
     -o Output EEPROM image - default: "${DST_IMAGE}"
-    -k Optional RSA private PEM file - default: "${PEM_FILE}"
+    -k Optional RSA private key PEM file.
+    -p Optional RSA public key PEM file.
 
 The -k argument signs the EEPROM configuration using the specified RSA 2048
 bit private key in PEM format. It also embeds the public portion of the RSA
 key pair in the EEPROM image so that the bootloader can verify the signed OS
 image.
+
+If the public key is not specified then rpi-eeprom-config will extract this
+automatically from the private key. Typically, the [-p] public key argument
+would only be used if rpi-eeprom-digest has been modified to use a hardware
+security module instead of a private key file.
+
 EOF
 }
 
@@ -57,6 +65,7 @@ update_eeprom() {
     config="$2"
     dst_image="$3"
     pem_file="$4"
+    public_pem_file="$5"
     sign_args=""
 
     if [ -n "${pem_file}" ]; then
@@ -83,14 +92,16 @@ update_eeprom() {
         # PEM file. It will also accept just the public key so it's possible
         # to tweak this script so that rpi-eeprom-config never sees the private
         # key.
-        sign_args="-d ${TMP_CONFIG_SIG} -p ${pem_file}"
+        sign_args="-d ${TMP_CONFIG_SIG} -p ${public_pem_file}"
     fi
 
     rm -f "${dst_image}"
+    set -x
     ${script_dir}/rpi-eeprom-config \
         --config "${config}" \
         --out "${dst_image}" ${sign_args} \
         "${src_image}" || die "Failed to update EEPROM image"
+    set +x
 
 cat <<EOF
 new-image: ${dst_image}
@@ -106,7 +117,7 @@ image_digest() {
 
 trap cleanup EXIT
 
-while getopts "c:hi:o:k:" option; do
+while getopts "c:hi:o:k:p:" option; do
     case "${option}" in
         c) CONFIG="${OPTARG}"
             ;;
@@ -116,6 +127,8 @@ while getopts "c:hi:o:k:" option; do
             ;;
         k) PEM_FILE="${OPTARG}"
             ;;
+        p) PUBLIC_PEM_FILE="${OPTARG}"
+            ;;
         h) usage
             ;;
         *) echo "Unknown argument \"${option}\""
@@ -130,8 +143,15 @@ if [ -n "${PEM_FILE}" ]; then
     [ -f "${PEM_FILE}" ] || die "RSA key file \"${PEM_FILE}\" not found"
 fi
 
+# If a public key is specified then use it. Otherwise, if just the private
+# key is specified then let rpi-eeprom-config automatically extract the
+# public key from the private key PEM file.
+if [ -z "${PUBLIC_PEM_FILE}" ]; then
+    PUBLIC_PEM_FILE="${PEM_FILE}"
+fi
+
 DST_IMAGE_SIG="$(echo "${DST_IMAGE}" | sed 's/\..*//').sig"
 
-update_eeprom "${SRC_IMAGE}" "${CONFIG}" "${DST_IMAGE}" "${PEM_FILE}"
+update_eeprom "${SRC_IMAGE}" "${CONFIG}" "${DST_IMAGE}" "${PEM_FILE}" "${PUBLIC_PEM_FILE}"
 image_digest "${DST_IMAGE}" "${DST_IMAGE_SIG}"
 
--
libgit2 0.21.4