[PATCH v6 20/20] docs/grub: Document appended signature

[Sudhakar Kuppusamy <sudhakar@linux.ibm.com>]

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 <dja@axtens.net>
Signed-off-by: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
Reviewed-by: Avnish Chouhan <avnish@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}.
 
 @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.
+
+@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}
+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.
+
+@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
+@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}
+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
+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..
+
+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},
+@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}
+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.
 @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.
+@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}.
+
+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}
+(@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
+@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
+@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
+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}
+(@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
+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
+
 @node UEFI secure boot and shim
 @section UEFI secure boot and shim support
 
-- 
2.39.5 (Apple Git-154)


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