On Mon, Jul 14, 2025 at 11:05:05PM +0530, Sudhakar Kuppusamy wrote:
> From: Daniel Axtens <[email protected]>
>
> 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 <[email protected]>
> Signed-off-by: Sudhakar Kuppusamy <[email protected]>
> Reviewed-by: Stefan Berger <[email protected]>
> Reviewed-by: Avnish Chouhan <[email protected]>
> ---
> 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...
> +Verifies an appended signature on @var{file} against the trusted X.509
> certificates
s/file/<file>
> +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.
> @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.
> @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/...
> +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/...
> +@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...
Daniel
_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
