Thank you Daniel.
> On 14 Aug 2025, at 7:50 PM, Daniel Kiper <dki...@net-space.pl> wrote:
>
> 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…
Sure, will add it.
>
>> @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?
When the appended signature verification is enforced and executes
append_add_db_cert from the GRUB console,
the x509 certificate must be signed with a sign-file utility, and
it will be verified by the appended signature module. If signature validation
succeeds, then add it to the db.
>
>> +@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...
Here the hash file will contain hash data in ASCII text format, not DER or PEM
format.
Also, the DER or PEM format is only used for x509 certificates.
When executing the append_add_db_hash command from the GRUB console,
it read the binary hash data in ASCII text format and added it to db.
>
> And I am not sure why sometimes you use PEM and sometimes DER. Is it
> possible to stick to one format to avoid confusion?
Sure, will stick to one format.
>
>> +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...
Sure, will do it.
>
>> +@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…
Will do it.
>
>> +@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…
Will do it.
>
>> +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?
These files are generated using secvarctl tool
(https://github.com/open-power/secvarctl) and which are in ASCII text format.
>
>> +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/
Will do it.
>
>> +@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…
Sure, will rephrase it.
>
>> @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/
Sorry will do it
>
> 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/?
Here enforced mode
>
>> +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…
Sure, will do it.
>
>> +@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?
Added to db list
>
>> +@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…
Added to dbx list
>
>> +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…
Added to dbx list
>
>> +(@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/
Will do it.
>
>> +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…
Shall I drop it.
Thanks,
Sudhakar
>
> Daniel
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
