> On 16 Jul 2025, at 4:36 PM, Daniel Kiper <dki...@net-space.pl> wrote:
>
> On Mon, Jul 14, 2025 at 11:05:05PM +0530, Sudhakar Kuppusamy wrote:
>> From: Daniel Axtens <d...@axtens.net>
>>
>> This explains how appended signatures can be used to form part of
>> a secure boot chain, and documents the commands and variables
>> introduced.
>>
>> 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 | 189 +++++++++++++++++++++++++++++++++++++++++++------
>> 1 file changed, 168 insertions(+), 21 deletions(-)
>>
>> diff --git a/docs/grub.texi b/docs/grub.texi
>> index d594e29bd..494e2eada 100644
>> --- a/docs/grub.texi
>> +++ b/docs/grub.texi
>> @@ -3281,6 +3281,7 @@ These variables have special meaning to GRUB.
>>
>> @menu
>> * biosnum::
>> +* check_appended_signatures::
>> * check_signatures::
>> * chosen::
>> * cmdpath::
>> @@ -3343,12 +3344,16 @@ this.
>> For an alternative approach which also changes BIOS drive mappings for the
>> chain-loaded system, @pxref{drivemap}.
>>
>> +@node check_appended_signatures
>> +@subsection check_appended_signatures
>> +This variable controls whether GRUB enforces appended signature validation
>> on
>> +loaded vmlinux file. @xref{Using appended signatures}.
>>
>> @node check_signatures
>> @subsection check_signatures
>>
>> -This variable controls whether GRUB enforces digital signature
>> -validation on loaded files. @xref{Using digital signatures}.
>> +This variable controls whether GRUB enforces GPG-style digital signature
>> +validation on loaded files. @xref{Using GPG-style digital signatures}.
>>
>> @node chosen
>> @subsection chosen
>> @@ -6414,6 +6419,10 @@ you forget a command, you can run the command
>> @command{help}
>> @menu
>> * [:: Check file types and compare values
>> * acpi:: Load ACPI tables
>> +* append_add_db_cert:: Add an X.509 certificate to the db list
>> +* append_list_db:: List trusted certificates from the db list
>> +* append_rm_dbx_cert:: Remove a certificate from the db list
>> +* append_verify:: Verify appended digital signature using db
>> list
>> * authenticate:: Check whether user is in user list
>> * background_color:: Set background color for active terminal
>> * background_image:: Load background image for active terminal
>> @@ -6535,6 +6544,68 @@ Note: The command is not allowed when lockdown is
>> enforced (@pxref{Lockdown}).
>> unsigned code.
>> @end deffn
>>
>> +@node append_add_db_cert
>> +@subsection append_add_db_cert
>> +
>> +@deffn Command append_add_db_cert X509_certificate
>> +Read a DER-formatted X.509 certificate from the file @var{X509_certificate}
>> +and add it to GRUB's internal db list of trusted X.509 certificates. These
>> +certificates are used to validate appended signatures when the environment
>> +variable @code{check_appended_signatures} is set to @code{enforce}.
>> +
>> +Note that if @code{check_appended_signatures} is set to @code{enforce}
>> +when @command{append_add_db_cert} is executed, then @var{X509_certificate}
>> +must itself bear an appended signature. (It is not sufficient that
>> +@var{X509_certificate} be signed by a trusted certificate according to the
>> +X.509 rules: GRUB does not include support for validating signatures within
>> X.509
>> +certificates themselves.)
>> +
>> +See @xref{Using appended signatures} for more information.
>> +@end deffn
>> +
>> +@node append_list_db
>> +@subsection append_list_db
>> +
>> +@deffn Command append_list_db
>> +List all X.509 certificates trusted by GRUB for validating appended
>> signatures.
>> +The output is a numbered list of certificates, showing the certificate's
>> serial
>> +number and Common Name.
>> +
>> +The certificate number can be used as an argument to
>> +@command{append_rm_dbx_cert} (@pxref{append_rm_dbx_cert}).
>> +
>> +See @xref{Using appended signatures} for more information.
>> +@end deffn
>> +
>> +@node append_rm_dbx_cert
>> +@subsection append_rm_dbx_cert
>> +
>> +@deffn Command append_rm_dbx_cert cert_number
>> +Remove the X.509 certificate numbered @var{cert_number} from GRUB's keyring
>> of
>> +db for verifying appended signatures.
>> +
>> +@var{cert_number} is the certificate number as listed by
>> +@command{append_list_db} (@pxref{append_list_db}).
>> +
>> +These certificates are used to validate appended signatures when environment
>> +variable @code{check_appended_signatures} is set to @code{enforce}
>> +(@pxref{check_appended_signatures}), and by @command{append_verify}
>> +(@pxref{append_verify}). See @xref{Using appended signatures} for more
>> +information.
>> +@end deffn
>> +
>> +@node append_verify
>> +@subsection append_verify
>> +
>> +@deffn Command append_verify file
>
> I suggest to use "<>" to mark arguments which gets a value, e.g.:
> append_verify <file>
> Please fix this in whole documentation…
Will do it.
>
>> +Verifies an appended signature on @var{file} against the trusted X.509
>> certificates
>
> s/file/<file>
Will do it.
>
>> +known to GRUB (See @pxref{append_list_db}, @pxref{append_add_db_cert}, and
>> +@pxref{append_rm_dbx_cert}).
>> +Exit code @code{$?} is set to 0 if the signature validates
>> +successfully. If validation fails, it is set to a non-zero value.
>> +
>> +See @xref{Using appended signatures}, for more information.
>> +@end deffn
>>
>> @node authenticate
>> @subsection authenticate
>> @@ -6854,7 +6925,7 @@ These keys are used to validate signatures when
>> environment variable
>> @code{check_signatures} is set to @code{enforce}
>> (@pxref{check_signatures}), and by some invocations of
>> @command{verify_detached} (@pxref{verify_detached}). @xref{Using
>> -digital signatures}, for more information.
>> +GPG-style digital signatures}, for more information.
>> @end deffn
>>
>> @node drivemap
>> @@ -7250,7 +7321,6 @@ without any options, the @command{keystatus} command
>> returns true if and
>> only if checking key modifier status is supported.
>> @end deffn
>>
>> -
>> @node list_env
>> @subsection list_env
>>
>> @@ -7270,7 +7340,7 @@ The output is in GPG's v4 key fingerprint format
>> (i.e., the output of
>> @code{gpg --fingerprint}). The least significant four bytes (last
>> eight hexadecimal digits) can be used as an argument to
>> @command{distrust} (@pxref{distrust}).
>> -@xref{Using digital signatures}, for more information about uses for
>> +@xref{Using GPG-style digital signatures}, for more information about uses
>> for
>> these keys.
>> @end deffn
>>
>> @@ -7305,8 +7375,11 @@ When used with care, @option{--skip-sig} and the
>> whitelist enable an
>> administrator to configure a system to boot only signed
>> configurations, but to allow the user to select from among multiple
>> configurations, and to enable ``one-shot'' boot attempts and
>> -``savedefault'' behavior. @xref{Using digital signatures}, for more
>> +``savedefault'' behavior. @xref{Using GPG-style digital signatures}, for
>> more
>> information.
>> +Extra care should be taken when combining this command with appended
>> signatures
>> +(@pxref{Using appended signatures}), as this file is not validated by an
>> +appended signature and could set @code{check_appended_signatures=no}.
>> @end deffn
>>
>>
>> @@ -7677,7 +7750,7 @@ read. It is possible to modify a digitally signed
>> environment block
>> file from within GRUB using this command, such that its signature will
>> no longer be valid on subsequent boots. Care should be taken in such
>> advanced configurations to avoid rendering the system
>> -unbootable. @xref{Using digital signatures}, for more information.
>> +unbootable. @xref{Using GPG-style digital signatures}, for more information.
>
> I suggest to move all GPG documentation changes to separate patch.
Will do it.
>
>> @end deffn
>>
>>
>> @@ -8167,11 +8240,10 @@ signatures when environment variable
>> @code{check_signatures} is set to
>> must itself be properly signed. The @option{--skip-sig} option can be
>> used to disable signature-checking when reading @var{pubkey_file}
>> itself. It is expected that @option{--skip-sig} is useful for testing
>> -and manual booting. @xref{Using digital signatures}, for more
>> +and manual booting. @xref{Using GPG-style digital signatures}, for more
>
> Ditto and below...
>
>> information.
>> @end deffn
>>
>> -
>
> This and similar cleanups can be a part of GPG change set but they have
> to be mentioned in the commit message.
Will do it.
>
>> @node unset
>> @subsection unset
>>
>> @@ -8190,7 +8262,6 @@ only on PC BIOS platforms.
>> @end deffn
>> @end ignore
>>
>> -
>
> Ditto...
>
>> @node verify_detached
>> @subsection verify_detached
>>
>> @@ -8208,7 +8279,7 @@ tried.
>>
>> Exit code @code{$?} is set to 0 if the signature validates
>> successfully. If validation fails, it is set to a non-zero value.
>> -@xref{Using digital signatures}, for more information.
>> +@xref{Using GPG-style digital signatures}, for more information.
>> @end deffn
>>
>> @node videoinfo
>> @@ -8668,14 +8739,15 @@ environment variables and commands are listed in the
>> same order.
>> @chapter Security
>>
>> @menu
>> -* Authentication and authorisation:: Users and access control
>> -* Using digital signatures:: Booting digitally signed code
>> -* UEFI secure boot and shim:: Booting digitally signed PE files
>> -* Secure Boot Advanced Targeting:: Embedded information for generation
>> number based revocation
>> -* Measured Boot:: Measuring boot components
>> -* Lockdown:: Lockdown when booting on a secure setup
>> -* TPM2 key protector:: Managing disk key with TPM2 key
>> protector
>> -* Signing GRUB itself:: Ensuring the integrity of the GRUB
>> core image
>> +* Authentication and authorisation:: Users and access control
>> +* Using GPG-style digital signatures:: Booting digitally signed code
>> +* Using appended signatures:: An alternative approach to booting
>> digitally signed code
>> +* UEFI secure boot and shim:: Booting digitally signed PE files
>> +* Secure Boot Advanced Targeting:: Embedded information for generation
>> number based revocation
>> +* Measured Boot:: Measuring boot components
>> +* Lockdown:: Lockdown when booting on a secure
>> setup
>> +* TPM2 key protector:: Managing disk key with TPM2 key
>> protector
>> +* Signing GRUB itself:: Ensuring the integrity of the GRUB
>> core image
>> @end menu
>>
>> @node Authentication and authorisation
>> @@ -8751,8 +8823,8 @@ generating configuration files with authentication.
>> You can use
>> adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
>> commands.
>>
>> -@node Using digital signatures
>> -@section Using digital signatures in GRUB
>> +@node Using GPG-style digital signatures
>> +@section Using GPG-style digital signatures in GRUB
>>
>> GRUB's @file{core.img} can optionally provide enforcement that all files
>> subsequently read from disk are covered by a valid digital signature.
>> @@ -8835,6 +8907,81 @@ or BIOS) configuration to cause the machine to boot
>> from a different
>> (attacker-controlled) device. GRUB is at best only one link in a
>> secure boot chain.
>>
>> +@node Using appended signatures
>> +@section Using appended signatures in GRUB
>> +
>> +GRUB supports verifying Linux-style 'appended signatures' for secure boot.
>> +Appended signatures are PKCS#7 messages containing a signature over the
>> +contents of a file, plus some metadata, appended to the end of a file. A
>> file
>> +with an appended signature ends with the magic string:
>> +
>> +@example
>> +~Module signature appended~\n
>> +@end example
>> +
>> +where @code{\n} represents the line feed character, @code{0x0a}.
>> +
>> +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.
>
> s/grub/GRUB/…
Will do it.
>
>> +Certificates can be managed at boot time using the
>> @pxref{append_add_db_cert},
>> +@pxref{append_rm_dbx_cert} and @pxref{append_list_db} 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 explicitly verified using the @pxref{append_verify} 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
>
> s/Grub/GRUB/…
Will do it.
>
>> +@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
>
> May I ask you to put all documentation patches in one group at the end
> of the patch set? Same applies to tests patches. I think they should land
> before documentation patches…
Will do it.
Thank you Daniel.
Thanks,
Sudhakar
>
> Daniel
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
