On Tue, Jun 10, 2025 at 09:20:49PM +0530, Sudhakar 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 | 185 ++++++++++++++++++++++++++++++++++++++++++++-----
> 1 file changed, 167 insertions(+), 18 deletions(-)
>
> diff --git a/docs/grub.texi b/docs/grub.texi
> index cd73ac6bf..473b826eb 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
> +certain loaded files. @xref{Using appended signatures}.
What does a "certain" mean? Please expand that.
> @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
> @@ -6435,6 +6440,7 @@ you forget a command, you can run the command
> @command{help}
> * date:: Display or set current date and time
> * devicetree:: Load a device tree blob
> * distrust:: Remove a pubkey from trusted keys
> +* distrust_certificate:: Remove a certificate from the list of
> trusted certificates
> * drivemap:: Map a drive to another
> * echo:: Display a line of text
> * efitextmode:: Set/Get text output mode resolution
> @@ -6453,6 +6459,7 @@ you forget a command, you can run the command
> @command{help}
> * hexdump:: Show raw contents of a file or memory
> * insmod:: Insert a module
> * keystatus:: Check key modifier status
> +* list_certificates:: List trusted certificates
> * list_env:: List variables in environment block
> * list_trusted:: List trusted public keys
> * load_env:: Load variables from environment block
> @@ -6494,8 +6501,10 @@ you forget a command, you can run the command
> @command{help}
> * tpm2_dump_pcr:: Dump TPM2 PCRs
> * true:: Do nothing, successfully
> * trust:: Add public key to list of trusted keys
> +* trust_certificate:: Add an x509 certificate to the list of
> trusted certificates
> * unset:: Unset an environment variable
> @comment * vbeinfo:: List available video modes
> +* verify_appended:: Verify appended digital signature
> * verify_detached:: Verify detached digital signature
> * videoinfo:: List available video modes
> * wrmsr:: Write values to model-specific registers
> @@ -6854,7 +6863,24 @@ 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 distrust_certificate
> +@subsection distrust_certificate
> +
> +@deffn Command distrust_certificate cert_number
> +Remove the x509 certificate numbered @var{cert_number} from GRUB's keyring of
> +trusted x509 certificates for verifying appended signatures.
> +
> +@var{cert_number} is the certificate number as listed by
> +@command{list_certificates} (@pxref{list_certificates}).
> +
> +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{verify_appended}
> +(@pxref{verify_appended}). See @xref{Using appended signatures} for more
> +information.
> @end deffn
>
> @node drivemap
> @@ -7250,6 +7276,19 @@ without any options, the @command{keystatus} command
> returns true if and
> only if checking key modifier status is supported.
> @end deffn
>
> +@node list_certificates
> +@subsection list_certificates
> +
> +@deffn Command list_certificates
> +List all x509 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{distrust_certificate} (@pxref{distrust_certificate}).
> +
> +See @xref{Using appended signatures} for more information.
> +@end deffn
>
> @node list_env
> @subsection list_env
> @@ -7270,7 +7309,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 +7344,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 +7719,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.
> @end deffn
>
>
> @@ -8167,11 +8209,30 @@ 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
> information.
> @end deffn
>
>
> +@node trust_certificate
> +@subsection trust_certificate
> +
> +@deffn Command trust_certificate x509_certificate
The name of this command is confusing. It is very generic but applies
only to appended signatures. So, maybe "appended_trust_certificate"?
> +Read a DER-formatted x509 certificate from the file @var{x509_certificate}
> +and add it to GRUB's internal list of trusted x509 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{trust_certificate} 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
> +x509 rules: GRUB does not include support for validating signatures within
> x509
> +certificates themselves.)
> +
> +See @xref{Using appended signatures} for more information.
> +@end deffn
Daniel
_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
