Re: [PATCH v1 21/21] appendedsig: documentation

[Avnish Chouhan <avnish@linux.ibm.com>]

Reviewed-by: Avnish Chouhan <avnish@linux.ibm.com>

On 2024-12-18 20:26, 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 <sudhakar@linux.ibm.com>
> ---
>  docs/grub.texi | 110 +++++++++++++++++++++++++++++++++++--------------
>  1 file changed, 78 insertions(+), 32 deletions(-)
> 
> diff --git a/docs/grub.texi b/docs/grub.texi
> index 6b634f111..477e25376 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -6382,7 +6382,9 @@ you forget a command, you can run the command
> @command{help}
>  * date::                        Display or set current date and time
>  * devicetree::                  Load a device tree blob
>  * distrust::                    Remove a pubkey from trusted keys
> -* distrust_certificate::        Remove a certificate from the list of
> trusted certificates
> +* distrusted_certificate::      Remove a certificate from the trusted 
> list
> +* distrusted_list::             List distrusted certificates and
> binary/certificate hashes
> +* distrusted_signature::        Add a binary hash to the distrusted 
> list
>  * drivemap::                    Map a drive to another
>  * echo::                        Display a line of text
>  * efitextmode::                 Set/Get text output mode resolution
> @@ -6401,7 +6403,6 @@ you forget a command, you can run the command
> @command{help}
>  * hexdump::                     Show raw contents of a file or memory
>  * insmod::                      Insert a module
>  * keystatus::                   Check key modifier status
> -* list_certificates::           List trusted certificates
>  * list_env::                    List variables in environment block
>  * list_trusted::                List trusted public keys
>  * load_env::                    Load variables from environment block
> @@ -6442,7 +6443,9 @@ you forget a command, you can run the command
> @command{help}
>  * tpm2_key_protector_clear::    Clear the TPM2 key protector
>  * true::                        Do nothing, successfully
>  * trust::                       Add public key to list of trusted keys
> -* trust_certificate::           Add an x509 certificate to the list
> of trusted certificates
> +* trusted_certificate::         Add an x509 certificate to the trusted 
> list
> +* trusted_list::                List trusted certificates and binary 
> hashes
> +* trusted_signature::           Add a binary hash to the trusted list.
>  * unset::                       Unset an environment variable
>  @comment * vbeinfo::                     List available video modes
>  * verify_appended::             Verify appended digital signature
> @@ -6790,15 +6793,15 @@ These keys are used to validate signatures
> when environment variable
>  GPG-style digital signatures}, for more information.
>  @end deffn
> 
> -@node distrust_certificate
> -@subsection distrust_certificate
> +@node distrusted_certificate
> +@subsection distrusted_certificate
> 
> -@deffn Command distrust_certificate cert_number
> +@deffn Command distrusted_certificate cert_number
>  Remove the x509 certificate numbered @var{cert_number} from GRUB's 
> keyring of
>  trusted x509 certificates for verifying appended signatures.
> 
>  @var{cert_number} is the certificate number as listed by
> -@command{list_certificates} (@pxref{list_certificates}).
> +@command{trusted_list} (@pxref{trusted_list}).
> 
>  These certificates are used to validate appended signatures when 
> environment
>  variable @code{check_appended_signatures} is set to @code{enforce}
> @@ -6807,6 +6810,28 @@ variable @code{check_appended_signatures} is
> set to @code{enforce}
>  information.
>  @end deffn
> 
> +@node distrusted_list
> +@subsection distrusted_list
> +
> +@deffn Command distrusted_list
> +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.
> +@end deffn
> +
> +@node distrusted_signature
> +@subsection distrusted_signature
> +
> +@deffn Command distrusted_signature
> +Read a binary hash from the file @var{binary hash file}
> +and add it to GRUB's internal distrusted list. These hash are used to
> +restrict validation of linux image integrity using trusted 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 drivemap
>  @subsection drivemap
> 
> @@ -7195,20 +7220,6 @@ without any options, the @command{keystatus}
> command returns true if and
>  only if checking key modifier status is supported.
>  @end deffn
> 
> -@node list_certificates
> -@subsection list_certificates
> -
> -@deffn Command list_certificates
> -List all x509 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.
> -
> -The certificate number can be used as an argument to
> -@command{distrust_certificate} (@pxref{distrust_certificate}).
> -
> -See @xref{Using appended signatures} for more information.
> -@end deffn
> -
>  @node list_env
>  @subsection list_env
> 
> @@ -8111,17 +8122,17 @@ information.
>  @end deffn
> 
> 
> -@node trust_certificate
> -@subsection trust_certificate
> +@node trusted_certificate
> +@subsection trusted_certificate
> 
> -@deffn Command trust_certificate x509_certificate
> +@deffn Command trusted_certificate x509_certificate
>  Read a DER-formatted x509 certificate from the file 
> @var{x509_certificate}
>  and add it to GRUB's internal list of trusted x509 certificates. These
>  certificates are used to validate appended signatures when the 
> environment
>  variable @code{check_appended_signatures} is set to @code{enforce}.
> 
>  Note that if @code{check_appended_signatures} is set to @code{enforce}
> -when @command{trust_certificate} is executed, then 
> @var{x509_certificate}
> +when @command{trusted_certificate} is executed, then 
> @var{x509_certificate}
>  must itself bear an appended signature. (It is not sufficient that
>  @var{x509_certificate} be signed by a trusted certificate according to 
> the
>  x509 rules: grub does not include support for validating signatures 
> within x509
> @@ -8130,6 +8141,33 @@ certificates themselves.)
>  See @xref{Using appended signatures} for more information.
>  @end deffn
> 
> +@node trusted_list
> +@subsection trusted_list
> +
> +@deffn Command trusted_list
> +List all x509 certificates and binary hases 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.
> +
> +The certificate number can be used as an argument to
> +@command{distrusted_certificate} (@pxref{distrusted_certificate}).
> +
> +See @xref{Using appended signatures} for more information.
> +@end deffn
> +
> +@node trusted_signature
> +@subsection trusted_signature
> +
> +@deffn Command trust_signature
> +Read a binary hash from the file @var{binary hash file}
> +and add it to GRUB's internal trusted list. These binary 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 unset
>  @subsection unset
> 
> @@ -8153,8 +8191,8 @@ only on PC BIOS platforms.
> 
>  @deffn Command verify_appended file
>  Verifies an appended signature on @var{file} against the trusted 
> certificates
> -known to GRUB (See @pxref{list_certificates}, 
> @pxref{trust_certificate}, and
> -@pxref{distrust_certificate}).
> +known to GRUB (See @pxref{trusted_list}, @pxref{trusted_certificate}, 
> and
> +@pxref{distrusted_certificate}).
>  Exit code @code{$?} is set to 0 if the signature validates
>  successfully.  If validation fails, it is set to a non-zero value.
> 
> @@ -8824,13 +8862,21 @@ To enable appended signature verification,
> load the appendedsig module and an
>  x509 certificate for verification. Building the appendedsig module 
> into the
>  core grub image is recommended.
> 
> -Certificates can be managed at boot time using the 
> @pxref{trust_certificate},
> -@pxref{distrust_certificate} and @pxref{list_certificates} commands.
> -Certificates can also be built in to the core image using the 
> @code{--x509}
> -parameter to @command{grub-install} or @command{grub-mkimage}.
> +For static key, Certificates will be built in to the core image using
> +the @code{--x509} parameter to @command{grub-install} or
> @command{grub-mkimage}.
> +it can allow to list the trusted certificates and binary hashes at
> boot time using
> +@pxref{trusted_list} and list distrusted certificates and
> binary/certificate hashes
> +at boot time using @pxref{distrusted_list} commands.
> +
> +For dynamic key, loads the signature database (DB) and forbidden
> +signature database (DBX) from platform keystore (PKS) and it can allow 
> to list
> +the trusted certificates and binary hashes at boot time using
> @pxref{trusted_list}
> +and list distrusted certificates and binary/certificate hashes at
> boot time using
> +@pxref{distrusted_list} commands.
> +
>  A file can be explictly verified using the @pxref{verify_appended} 
> command.
> 
> -Only signatures made with the SHA-256 or SHA-512 hash algorithm are 
> supported,
> +Only signatures made with the SHA-256, SHA-384 and SHA-512 hash
> algorithm are supported,
>  and only RSA signatures are supported.
> 
>  A file can be signed with the @command{sign-file} utility supplied 
> with the

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