On Mon, Jul 14, 2025 at 11:05:13PM +0530, Sudhakar Kuppusamy wrote:
> This explains how static and dynamic key appended signatures can be used to
> form part of
> a secure boot chain, and documents the commands and variables introduced.
>
> Signed-off-by: Sudhakar Kuppusamy <[email protected]>
> Reviewed-by: Avnish Chouhan <[email protected]>
> ---
> docs/grub.texi | 75 ++++++++++++++++++++++++++++++++++++++------------
> 1 file changed, 58 insertions(+), 17 deletions(-)
>
> diff --git a/docs/grub.texi b/docs/grub.texi
> index 561f301cf..af63fe4f7 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -6420,9 +6420,12 @@ you forget a command, you can run the command
> @command{help}
> * [:: Check file types and compare values
> * acpi:: Load ACPI tables
> * append_add_db_cert:: Add an X.509 certificate to the db list
> -* append_list_db:: List trusted certificates from the db list
> +* append_add_db_sig:: Add an X.509 certificate/binary hash to the
> db list
> +* append_add_dbx_sig:: Add an X.509 certificate/binary hash to the
> dbx list
> +* append_list_db:: List trusted certificates/binary hashes from
> the db list
> +* append_list_dbx:: List certificates and binary/certificate
> hashes from the dbx list
> * append_rm_dbx_cert:: Remove a certificate from the db list
> -* append_verify:: Verify appended digital signature using db
> list
> +* append_verify:: Verify appended digital signature using db
> and dbx list
> * authenticate:: Check whether user is in user list
> * background_color:: Set background color for active terminal
> * background_image:: Load background image for active terminal
> @@ -6563,16 +6566,48 @@ certificates themselves.)
> See @xref{Using appended signatures} for more information.
> @end deffn
>
> +@node append_add_db_sig
> +@subsection append_add_db_sig
> +
> +@deffn Command append_add_db_sig hash_file
s/hash_file/<hash_file>/
> +Read a binary/certificate hash from the file @var{hash_file}
What is <hash_file> format?
> +and add it to GRUB's internal db list. These hash are used to validate linux
> image
> +integrity if appended signatures validation failed when the environment
> variable
> +@code{check_appended_signatures} is set to @code{enforce}.
> +
> +See @xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node append_add_dbx_sig
> +@subsection append_add_dbx_sig
> +
> +@deffn Command append_add_dbx_sig hash_file
s/hash_file/<hash_file>/
> +Read a binary/certificate hash from the file @var{hash_file}
What is <hash_file> format?
> +and add it to GRUB's internal dbx list. These hash are used to restrict
> validation
> +of linux image integrity using db list if appended signatures validation
> failed
> +when the environment variable @code{check_appended_signatures} is set to
> @code{enforce}.
> +
> +See @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 trusted by GRUB for validating appended
> signatures.
> -The output is a numbered list of certificates, showing the certificate's
> serial
> -number and Common Name.
> +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 and Common Name.
> +
> +See @xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node append_list_dbx
> +@subsection append_list_dbx
>
> -The certificate number can be used as an argument to
> -@command{append_rm_dbx_cert} (@pxref{append_rm_dbx_cert}).
> +@deffn Command append_list_dbx
> +List all the distrusted x509 certificates and binary/certificate hashes.
> +The output is a numbered list of certificates and binary/certificate hashes,
> +showing the certificate's serial number and Common Name.
>
> See @xref{Using appended signatures} for more information.
> @end deffn
> @@ -6597,12 +6632,12 @@ information.
> @node append_verify
> @subsection append_verify
>
> -@deffn Command append_verify file
> -Verifies an appended signature on @var{file} against the trusted X.509
> certificates
> -known to GRUB (See @pxref{append_list_db}, @pxref{append_add_db_cert}, and
> -@pxref{append_rm_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.
> +@deffn Command append_verify signed_file
s/hash_file/<signed_file>/
> +Verifies an appended signature on @var{signed_file} against the trusted
> X.509 certificates
> +known to GRUB (See @pxref{append_list_db},@pxref{append_list_dbx},
> @pxref{append_add_db_cert},
> +@pxref{append_add_db_sig}, @pxref{append_add_dbx_sig}, and
> @pxref{append_rm_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.
Daniel
_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel
