On Tue, Jul 29, 2025 at 08:21:56PM +0530, Sudhakar Kuppusamy wrote:
> 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: Avnish Chouhan <avn...@linux.ibm.com>
> ---
>  docs/grub.texi | 232 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 232 insertions(+)
>
> diff --git a/docs/grub.texi b/docs/grub.texi
> index 2ff867cc5..0301b164b 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,6 +3344,10 @@ 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 kernel and GRUB module files. @xref{Using appended signatures}.

What are valid values for this variable and what are they meaning?
OK, I can see this below. Though I think at least listing allowed
values makes sense here...

>  @node check_signatures
>  @subsection check_signatures
> @@ -6414,6 +6419,13 @@ 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 trusted certificate to the db list
> +* append_add_db_hash::          Add trusted certificate/binary hash to the 
> db list
> +* append_add_dbx_cert::         Add distrusted certificate to the dbx list
> +* append_add_dbx_hash::         Add distrusted certificate/binary hash to 
> the dbx list
> +* append_list_db::              List all trusted certificates from the db 
> list
> +* append_list_dbx::             List all distrusted certificates and 
> binary/certificate hashes from the dbx list
> +* append_verify::               Verify appended digital signature using db 
> and dbx lists
>  * 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 +6547,120 @@ 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 DER-formatted X.509 certificate from the file @var{X509_certificate}
> +and add it to GRUB's internal db list of trusted certificates.
> +These certificates are used to validate appended signatures when the
> +environment variable @code{check_appended_signatures} 
> (@pxref{check_appended_signatures})
> +is set to @code{enforce} or the @command{append_verify} 
> (@pxref{append_verify})
> +command is executed from the GRUB console.
> +
> +Note that if @code{check_appended_signatures} is set to @code{enforce}
> +when @command{append_add_db_cert} executes, then @var{X509_certificate} must
> +be properly signed.

What does it mean "properly signed"? By whom? How the signature is
verified and when it is considered valid?

> +@xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node append_add_db_hash
> +@subsection append_add_db_hash
> +
> +@deffn Command append_add_db_hash <hash_file>
> +Read ASCII text formatted binary hash from the file @var{hash_file}

What do you mean by "ASCII text formatted"? PEM? If yes then use phrase
"in PEM format" or something like that...

And I am not sure why sometimes you use PEM and sometimes DER. Is it
possible to stick to one format to avoid confusion?

> +and add it to GRUB's internal db list of trusted binary hashes. These
> +hashes are used to validate the Linux kernel binary hashes when the
> +environment variable @code{check_appended_signatures}
> +(@pxref{check_appended_signatures}) is set to @code{enforce} or the
> +@command{append_verify} (@pxref{append_verify}) command is executed
> +from the GRUB console.
> +
> +Note that if @code{check_appended_signatures} is set to @code{enforce}
> +when @command{append_add_db_hash} executes, then @var{hash_file}
> +must be properly signed.

Again, I think you should be precise what "properly signed" means.
Though it is OK to write it down once and refer to it later in the
documentation...

> +@xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node append_add_dbx_cert
> +@subsection append_add_dbx_cert
> +
> +@deffn Command append_add_dbx_cert <X509_certificate>
> +Read DER-formatted X.509 certificate from the file @var{X509_certificate}
> +and add it to GRUB's internal dbx list of distrusted certificates.
> +These certificates are used to block adding the distrusted certificates to
> +the db list in the future and also ensure that the distrusted certificates
> +are not used for appended signatures validation when the environment variable

s/not used for/rejected during/

And I think rejection should be mentioned first...

> +@code{check_appended_signatures} is set to @code{enforce}
> +(@pxref{check_appended_signatures}) or the @command{append_verify}
> +(@pxref{append_verify}) command is executed from the GRUB console.
> +
> +Note that if @code{check_appended_signatures} is set to @code{enforce}
> +when @command{append_add_dbx_cert} executes, then @var{X509_certificate} must
> +be properly signed.
> +
> +@xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node append_add_dbx_hash
> +@subsection append_add_dbx_hash
> +
> +@deffn Command append_add_dbx_hash [@option{-b}|@option{-c}] <hash_file>
> +Read ASCII text formatted binary/certificate hash from the file 
> @var{hash_file}

Again, PEM...

> +and add it to GRUB's internal dbx list of distrusted binary/certificate 
> hashes.
> +These hashes are used to block adding the distrusted binary hashes and
> +certificates to the db list in the future, and also ensure that the 
> distrusted
> +binary hashes/certificates are not used for Linux kernel binary hashes and

s/not used for/rejected during/

And I think rejection should be mentioned first...

> +appended signatures validation when the environment variable
> +@code{check_appended_signatures} (@pxref{check_appended_signatures}) is set 
> to
> +@code{enforce} or the @command{append_verify} (@pxref{append_verify}) command
> +is executed from the GRUB console.
> +
> +The @option{-b} (@option{--binary-hash}) can be used to specify binary hash 
> file and
> +@option{-c} (@option{--cert-hash}) can be used to specify certificate hash 
> file..

What are the formats for these files and how they should be generated?

> +Note that if @code{check_appended_signatures} is set to @code{enforce}
> +when @command{append_add_dbx_sig} executes, then @var{hash_file} must be 
> properly signed.
> +
> +@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 and binary hashes trusted by GRUB for validating
> +appended signatures. The output is a numbered list of certificates and 
> binary hashes,
> +showing the certificate's serial number, issuer and Common Name.
> +
> +@xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node append_list_dbx
> +@subsection append_list_dbx
> +
> +@deffn Command append_list_dbx
> +List all the distrusted X.509 certificates and binary/certificate hashes.
> +The output is a numbered list of certificates and binary/certificate hashes,
> +showing the certificate's serial number, issuer and Common Name.
> +
> +@xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node append_verify
> +@subsection append_verify
> +
> +@deffn Command append_verify <signed_file>
> +Verifies an appended signature on @var{signed_file} against the trusted 
> X.509 certificates
> +known to GRUB (@pxref{append_list_db},@pxref{append_list_dbx}, 
> @pxref{append_add_db_cert},

s/known/and hashes known/

> +@pxref{append_add_db_hash}, @pxref{append_add_dbx_hash}, and 
> @pxref{append_add_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.
> +
> +@xref{Using appended signatures}, for more information.
> +@end deffn
>
>  @node authenticate
>  @subsection authenticate
> @@ -7307,6 +7433,13 @@ configurations, but to allow the user to select from 
> among multiple
>  configurations, and to enable ``one-shot'' boot attempts and
>  ``savedefault'' behavior.  @xref{Using GPG-style digital signatures}, for 
> more
>  information.
> +
> +When combining this command with appended signatures (@pxref{Using appended 
> signatures}),
> +not allowed to change the value of environment variable 
> @code{check_appended_signatures}

??? "not allowed"??? Something is missing here...

> +to @code{no} or @code{enforce} even with the @option{--skip-sig} option
> +when the environment variable @code{check_appended_signatures}
> +(@pxref{check_appended_signatures}) is set to @code{enforce} and GRUB is 
> locked down.
> +However, the environment block file is not validated by an appended 
> signature.

I am not sure what you mean here. I think this paragraph should be rephrased...

>  @end deffn
>
>
> @@ -8670,6 +8803,7 @@ environment variables and commands are listed in the 
> same order.
>  @menu
>  * 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
> @@ -8835,6 +8969,104 @@ 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 Linux on Power 
> LPAR
> +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}.
> +
> +Linux on Power LPAR secure boot is controlled by @strong{'ibm,secure-boot'}
> +device tree property and if this property is set to @code{2} (@samp{2 - 
> enforced}),
> +GRUB enters lockdown. There are three secure boot modes. They are
> +
> +@itemize
> +@item @samp{0 - disabled}: Secure boot is disabled. This is the default.
> +@item @samp{1 - audit}: Enforce signature verification by setting
> +      @code{check_appended_signatures} (@pxref{check_appended_signatures}) to
> +      @code{enforce} and not to lockdown the GRUB.

s/and not/and do not/

I think you are sometimes missing verbs... 🤔

> +@item @samp{2 - enforced}: Lockdown the GRUB and enforce signature 
> verification by setting
> +      @code{check_appended_signatures} (@pxref{check_appended_signatures}) 
> to @code{enforce}.
> +@end itemize
> +
> +Note that Linux on Power LPAR only @strong{supports disabled and enforced}.

s/enforced/enforce/?

> +To enable appended signature verification, load the appendedsig module and an
> +X.509 certificate for verification. Building the appendedsig module into the
> +core GRUB image is recommended.
> +
> +In static key management mode, certificates will be built into the core 
> image using
> +the @code{--x509} parameter to @command{grub-install} or 
> @command{grub-mkimage}.
> +It allows listing the trusted certificates at boot time using 
> @command{append_list_db}

You can list the trusted certificates available at boot time using...

> +(@pxref{append_list_db}).
> +
> +In dynamic key management mode, db and dbx are read from the Platform 
> KeyStore(PKS). If
> +db is not present in PKS, static key (built-in keys) is used as the default 
> key.
> +It allows listing the trusted certificates and binary hashes at boot time 
> using

s/allows listing/is possible to list/...
s/at boot/available at boot/

Similar changes are worth doing here and there...

> +@command{append_list_dbx} (@pxref{append_list_db}) and listing distrusted
> +certificates and binary/certificate hashes at boot time using 
> @command{append_list_dbx}
> +(@pxref{append_list_dbx}).
> +
> +Enforcement of signature verification is controlled by the
> +@code{check_appended_signatures} (@pxref{check_appended_signatures}) 
> variable.
> +
> +@itemize
> +@item @samp{no}: No verification is performed. This is the default.
> +@item @samp{enforce}: Signature verification is performed and if signature 
> verification fails,
> +      post the errors and stop the boot. Signature verification cannot be 
> disabled by setting
> +      the @code{check_appended_signatures} variable back to @samp{no}.
> +@end itemize
> +
> +A file can be explicitly verified using the @command{append_verify} 
> (@pxref{append_verify}).
> +The trusted certificates and binary hashes can be explicitly added using the

"added" to what?

> +@command{append_add_db_cert} (@pxref{append_add_db_cert}) and 
> @command{append_add_db_hash}
> +(@pxref{append_add_db_hash}). The distrusted certificates can be explicitly 
> added using

Ditto...

> +the @command{append_add_dbx_cert} (@pxref{append_add_dbx_cert}) and the 
> distrusted
> +certificate/binary hases can be explicitly addded using 
> @command{append_add_dbx_hash}

Ditto...

> +(@pxref{append_add_dbx_hash}).
> +
> +Only signatures generated using SHA-256 or SHA-512 hash algorithms are 
> supported,
> +and only RSA signatures generated using 2048, 3076, or 4096 bit key are 
> supported.
> +Only binary/certificate hash generated using SHA-256, SHA-384, or SHA-512 
> hash

s/SHA-512 hash/SHA-512/

> +algorithms 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 X.509 certificate containing the 
> public key:
> +
> +@example
> +sign-file SHA256 signing.key certificate.der vmlinux vmlinux.signed
> +@end example
> +
> +Once signature verification is turned on, the following file types must carry
> +appended signatures:
> +
> +@enumerate
> +@item Linux kernels
> +@item GRUB modules, except those built in to the core image
> +@item Any new certificate and binary hash files to be trusted
> +@item Any new certificate/binary hash files to be distrusted
> +@end enumerate
> +
> +When GRUB is locked down (when secure boot modes is @code{enforced}),
> +signature verification cannot be @strong{disabled} by setting the
> +@code{check_appended_signatures} (@pxref{check_appended_signatures}) variable
> +to @code{no} or using the @command{load_env} (@pxref{load_env}) command from
> +the GRUB console.
> +
> +@example
> +set check_appended_signatures=no
> +        or
> +load_env --file grubenv --skip-sig
> +@end example

This example does not make a lot of sense for me...

Daniel

_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

Reply via email to