grub2/0006-appendedsig-documentation.patch

From 87831c6ce3536e5e2eeb3e2cd8a6184b9509ee04 Mon Sep 17 00:00:00 2001
From: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
Date: Wed, 17 Apr 2024 23:04:43 +0530
Subject: [PATCH 6/8] appendedsig: documentation

This explains appended signatures static key and dynamic key,
and documents the commands and variables introduced.

Signed-off-by: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
---
 docs/grub.texi | 115 ++++++++++++++++++++++++++++++++++---------------
 1 file changed, 80 insertions(+), 35 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index 00c5fdc44..68d7cbb90 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -4373,7 +4373,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
@@ -4390,7 +4392,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
@@ -4429,7 +4430,9 @@ you forget a command, you can run the command @command{help}
 * test::                        Check file types and compare values
 * 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
@@ -4776,15 +4779,15 @@ 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}
@@ -4793,6 +4796,27 @@ 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
@@ -5069,22 +5093,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
 
@@ -5935,9 +5943,8 @@ and manual booting. @xref{Using GPG-style digital signatures}, for more
 information.
 @end deffn
 
-
-@node trust_certificate
-@subsection trust_certificate
+@node trusted_certificate
+@subsection trusted_certificate
 
 @deffn Command trust_certificate x509_certificate
 Read a DER-formatted x509 certificate from the file @var{x509_certificate}
@@ -5946,7 +5953,7 @@ 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
@@ -5955,6 +5962,32 @@ 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
@@ -5979,8 +6012,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.
@@ -6664,17 +6697,29 @@ with an appended signature ends with the magic string:
 where @code{\n} represents the carriage-return character, @code{0x0a}.
 
 To enable appended signature verification, load the appendedsig module and an
-x509 certificate for verification. Building the appendedsig module into the
+trusted keys 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.
+
+Also, it will not allow to manage add/delete of certificates/signature at boot time using
+@pxref{trusted_certificate} and @pxref{trusted_signature}, @pxref{distrusted_certificate}
+and @pxref{distrusted_signature} commands when the environment variable
+@code{check_appended_signatures} is set to @code{enforce}.
 
 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, SH-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
-- 
2.47.0