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 <[email protected]>
> Signed-off-by: Sudhakar Kuppusamy <[email protected]>
> Reviewed-by: Avnish Chouhan <[email protected]>
> ---
> 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
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
