[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH v2 21/22] appended signatures: documentation

From: Daniel Axtens
Subject: Re: [PATCH v2 21/22] appended signatures: documentation
Date: Thu, 21 Apr 2022 17:15:17 +1000

>> +@example
>> +~Module signature appended~\n
>> +@end example
>> +
>> +where @code{\n} represents the carriage-return character, @code{0x0a}.
> \n is 0xa but it's called line-feed.

D'oh, you're completely right, of course. Fixed.

>> +
>> +To enable appended signature verification, load the appendedsig module and 
>> an
>> +x509 certificate for verification. Building the appendedsig module into the
>> +core grub image is recommended.
>> +
>> +Certificates can be managed at boot time using the 
>> @pxref{trust_certificate},
>> +@pxref{distrust_certificate} and @pxref{list_certificates} commands.
>> +Certificates can also be built in to the core image using the @code{--x509}
>> +parameter to @command{grub-install} or @command{grub-mkimage}.
>> +
>> +A file can be explictly verified using the @pxref{verify_appended} command.
>> +
>> +Only signatures made with the SHA-256 or SHA-512 hash algorithm are 
>> supported,
>> +and only RSA signatures are supported.
>> +
>> +A file can be signed with the @command{sign-file} utility supplied with the
>> +Linux kernel source. For example, if you have @code{signing.key} as the 
>> private
>> +key and @code{certificate.der} as the x509 certificate containing the 
>> public key:
>> +
>> +@example
>> +sign-file SHA256 signing.key certificate.der vmlinux vmlinux.signed
>> +@end example
>> +
>> +Enforcement of signature verification is controlled by the
>> +@code{check_appended_signatures} variable. Verification will only take place
>> +when files are loaded if the variable is set to @code{enforce}. If a
>> +certificate is built into the grub core image with the @code{--x509} 
>> parameter,
>> +the variable will be automatically set to @code{enforce} when the 
>> appendedsig
>> +module is loaded.
>> +
>> +Unlike GPG-style signatures, not all files loaded by GRUB are required to be
>> +signed. Once verification is turned on, the following file types must carry
>> +appended signatures:
>> +
>> +@enumerate
>> +@item Linux, Multiboot, BSD, XNU and Plan9 kernels
>> +@item Grub modules, except those built in to the core image
>> +@item Any new certificate files to be trusted
>> +@end enumerate
>> +
>> +ACPI tables and Device Tree images will not be checked for appended 
>> signatures
>> +but must be verified by another mechanism such as GPG-style signatures 
>> before
>> +they will be loaded.
>> +
>> +No attempt is made to validate any other file type. In particular,
>> +chain-loaded binaries are not verified - if your platform supports
>> +chain-loading and this cannot be disabled, consider an alternative secure
>> +boot mechanism.
>> +
>> +As with GPG-style appended signatures, signature checking does @strong{not}
>> +stop an attacker with console access from dropping manually to the GRUB
>> +console and executing:
>> +
>> +@example
>> +set check_appended_signatures=no
>> +@end example
>> +
>> +Refer to the section on password-protecting GRUB (@pxref{Authentication
>> +and authorisation}) for more information on preventing this.
>> +
>> +Additionally, special care must be taken around the @command{loadenv} 
>> command,
>> +which can be used to turn off @code{check_appended_signature}.
>> +
>>   @node UEFI secure boot and shim
>>   @section UEFI secure boot and shim support
> With this nit fixed: Reviewed-by: Stefan Berger <>


Kind regards,
Daniel Axtens

reply via email to

[Prev in Thread] Current Thread [Next in Thread]