[PATCH v4 03/23] docs/grub: Document signing GRUB with an appended signature

[Sudhakar Kuppusamy <sudhakar@linux.ibm.com>]

Signing GRUB for firmware that verifies an appended signature is a
bit fiddly. I don't want people to have to figure it out from scratch
so document it here.

Signed-off-by: Daniel Axtens <dja@axtens.net>
Signed-off-by: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Avnish Chouhan <avnish@linux.ibm.com>
---
 docs/grub.texi | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/docs/grub.texi b/docs/grub.texi
index 320fa2124..d594e29bd 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -9379,6 +9379,92 @@ image works under UEFI secure boot and can maintain the secure-boot chain. It
 will also be necessary to enroll the public key used into a relevant firmware
 key database.
 
+@section Signing GRUB with an appended signature
+The @file{core.img} itself can be signed with a Linux kernel module-style
+appended signature.
+To support IEEE1275 platforms where the boot image is often loaded directly
+from a disk partition rather than from a file system, the @file{core.img}
+can specify the size and location of the appended signature with an ELF
+note added by @command{grub-install}.
+An image can be signed this way using the @command{sign-file} command from
+the Linux kernel:
+@example
+@group
+# Signing a GRUB image with only one signer key in the appended signature:
+# The grub.key is your private key and certificate.der is your GRUB signing public key
+# kernel.der is your kernel signing public key.
+#
+# Determine the size of the appended signature. It depends on the signing certificate
+# and the hash algorithm.
+#
+# Signing the /dev/null with an appended signature.
+
+sign-file SHA256 grub.key certificate.der /dev/null /dev/empty.sig
+
+# Get the size of the signature.
+
+EMPTY_SIG_SIZE=`stat -c '%s' /dev/empty.sig`
+
+# Remove the empty files.
+
+rm -rf /dev/empty.sig
+
+# Build a GRUB image with $EMPTY_SIG_SIZE reserved for the signature.
+
+grub-install --appended-signature-size $EMPTY_SIG_SIZE --modules="appendedsig ..." ...
+                      or
+grub-mkimage -O powerpc-ieee1275 -o core.elf.unsigned -x kernel.der -p /grub2 \
+--appended-signature-size $EMPTY_SIG_SIZE --modules="appendedsig ..." ...
+
+# Signing a GRUB image with an appended signature.
+
+sign-file SHA256 grub.key certificate.der core.elf.unsigned core.elf.signed
+
+#
+# Signing a GRUB image with more than one signer key in the appended signature:
+# The grub1.key and grub2.key are your private keys, certificate1.der and certificate2.der
+# are your GRUB signing public keys. kernel.der and Kernel2.der are your kernel signing public key.
+
+# Generate a raw signature for /dev/null signing using OpenSSL.
+
+openssl cms -sign -binary -nocerts -in /dev/null -signer certificate1.pem -inkey grub1.key \
+-signer certificate2.pem -inkey grub2.key -out /dev/empty.p7s -outform DER -noattr -md sha256
+
+# Signing the /dev/null with an appended signature.
+
+sign-file -s /dev/empty.p7s sha256 /dev/null /dev/null /dev/empty.signed
+
+# Get the size of the signature.
+
+EMPTY_SIG_SIZE=`stat -c '%s' /dev/empty.signed`
+
+# Remove the empty files.
+
+rm -rf /dev/empty.signed /dev/empty.p7s
+
+# Build a GRUB image with $EMPTY_SIG_SIZE reserved for the signature.
+
+grub-install --appended-signature-size $EMPTY_SIG_SIZE --modules="appendedsig ..." ...
+                         or
+grub-mkimage -O powerpc-ieee1275 -o core.elf.unsigned -x kernel.der -p /grub2 \
+--appended-signature-size $EMPTY_SIG_SIZE --modules="appendedsig ..." ...
+
+# Generate a raw signature for GRUB image signing using OpenSSL.
+
+openssl cms -sign -binary -nocerts -in core.elf.unsigned -signer certificate.pem \
+-inkey grub.key -signer certificate1.pem -inkey grub1.key -out core.p7s -outform DER -noattr -md sha256
+
+# Signing a GRUB image with an appended signature.
+
+sign-file -s core.p7s sha256 /dev/null core.elf.unsigned core.elf.signed
+
+# Don't forget to install the signed image as required (e.g. on powerpc-ieee1275, to the PReP partition)
+
+@end group
+@end example
+As with UEFI secure boot, it is necessary to build-in the required modules,
+or sign them separately.
+
 @node Platform limitations
 @chapter Platform limitations
 
-- 
2.39.5 (Apple Git-154)


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel