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