On Mon, Jul 14, 2025 at 11:04:55PM +0530, Sudhakar Kuppusamy wrote:
> 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 <d...@axtens.net>
> Signed-off-by: Sudhakar Kuppusamy <sudha...@linux.ibm.com>
> Reviewed-by: Stefan Berger <stef...@linux.ibm.com>
> Reviewed-by: Avnish Chouhan <avn...@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
Please do not pollute /dev directory with randomly generated files.
This applies to all command examples below too...
> +# Get the size of the signature.
> +
> +EMPTY_SIG_SIZE=`stat -c '%s' /dev/empty.sig`
> +
> +# Remove the empty files.
s/empty files/empty file signature/
> +rm -rf /dev/empty.sig
The rm without "-rf" should be enough here. Same comment for rm below...
> +# 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 ..." ...
I suggest to add at least two spaces before "--appended-signature-size"
to make it more visible that it is line continuation.
> +# 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
Ditto.
> +# 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
s/empty files/empty files signatures/
> +# 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 ..." ...
Please add at least two spaces at the beginning here...
> +# 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
Ditto.
Daniel
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
