Blame SOURCES/0196-appended-signatures-documentation.patch

5593c8
From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
5593c8
From: Daniel Axtens <dja@axtens.net>
5593c8
Date: Thu, 1 Oct 2020 13:02:09 +1000
5593c8
Subject: [PATCH] appended signatures: documentation
5593c8
5593c8
This explains how appended signatures can be used to form part of
5593c8
a secure boot chain, and documents the commands and variables
5593c8
introduced.
5593c8
5593c8
Signed-off-by: Daniel Axtens <dja@axtens.net>
5593c8
---
5593c8
 docs/grub.texi | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
5593c8
 1 file changed, 182 insertions(+), 17 deletions(-)
5593c8
5593c8
diff --git a/docs/grub.texi b/docs/grub.texi
d3c3ab
index afbde7c1f7b..4816be85611 100644
5593c8
--- a/docs/grub.texi
5593c8
+++ b/docs/grub.texi
5593c8
@@ -3214,6 +3214,7 @@ These variables have special meaning to GRUB.
5593c8
 
5593c8
 @menu
5593c8
 * biosnum::
5593c8
+* check_appended_signatures::
5593c8
 * check_signatures::
5593c8
 * chosen::
5593c8
 * cmdpath::
5593c8
@@ -3273,11 +3274,18 @@ For an alternative approach which also changes BIOS drive mappings for the
5593c8
 chain-loaded system, @pxref{drivemap}.
5593c8
 
5593c8
 
5593c8
+@node check_appended_signatures
5593c8
+@subsection check_appended_signatures
5593c8
+
5593c8
+This variable controls whether GRUB enforces appended signature validation on
5593c8
+certain loaded files. @xref{Using appended signatures}.
5593c8
+
5593c8
+
5593c8
 @node check_signatures
5593c8
 @subsection check_signatures
5593c8
 
5593c8
-This variable controls whether GRUB enforces digital signature
5593c8
-validation on loaded files. @xref{Using digital signatures}.
5593c8
+This variable controls whether GRUB enforces GPG-style digital signature
5593c8
+validation on loaded files. @xref{Using GPG-style digital signatures}.
5593c8
 
5593c8
 @node chosen
5593c8
 @subsection chosen
5593c8
@@ -3994,6 +4002,7 @@ you forget a command, you can run the command @command{help}
5593c8
 * date::                        Display or set current date and time
5593c8
 * devicetree::                  Load a device tree blob
5593c8
 * distrust::                    Remove a pubkey from trusted keys
5593c8
+* distrust_certificate::        Remove a certificate from the list of trusted certificates
5593c8
 * drivemap::                    Map a drive to another
5593c8
 * echo::                        Display a line of text
5593c8
 * eval::                        Evaluate agruments as GRUB commands
5593c8
@@ -4010,6 +4019,7 @@ you forget a command, you can run the command @command{help}
5593c8
 * keystatus::                   Check key modifier status
5593c8
 * linux::                       Load a Linux kernel
5593c8
 * linux16::                     Load a Linux kernel (16-bit mode)
5593c8
+* list_certificates::           List trusted certificates
5593c8
 * list_env::                    List variables in environment block
5593c8
 * list_trusted::                List trusted public keys
5593c8
 * load_env::                    Load variables from environment block
5593c8
@@ -4047,8 +4057,10 @@ you forget a command, you can run the command @command{help}
5593c8
 * test::                        Check file types and compare values
5593c8
 * true::                        Do nothing, successfully
5593c8
 * trust::                       Add public key to list of trusted keys
5593c8
+* trust_certificate::           Add an x509 certificate to the list of trusted certificates
5593c8
 * unset::                       Unset an environment variable
5593c8
 @comment * vbeinfo::                     List available video modes
5593c8
+* verify_appended::             Verify appended digital signature
5593c8
 * verify_detached::             Verify detached digital signature
5593c8
 * videoinfo::                   List available video modes
5593c8
 @comment * xen_*::              Xen boot commands for AArch64
5593c8
@@ -4376,9 +4388,28 @@ These keys are used to validate signatures when environment variable
5593c8
 @code{check_signatures} is set to @code{enforce}
5593c8
 (@pxref{check_signatures}), and by some invocations of
5593c8
 @command{verify_detached} (@pxref{verify_detached}).  @xref{Using
5593c8
-digital signatures}, for more information.
5593c8
+GPG-style digital signatures}, for more information.
5593c8
 @end deffn
5593c8
 
5593c8
+
5593c8
+@node distrust_certificate
5593c8
+@subsection distrust_certificate
5593c8
+
5593c8
+@deffn Command distrust_certificate cert_number
5593c8
+Remove the x509 certificate numbered @var{cert_number} from GRUB's keyring of
5593c8
+trusted x509 certificates for verifying appended signatures.
5593c8
+
5593c8
+@var{cert_number} is the certificate number as listed by
5593c8
+@command{list_certificates} (@pxref{list_certificates}).
5593c8
+
5593c8
+These certificates are used to validate appended signatures when environment
5593c8
+variable @code{check_appended_signatures} is set to @code{enforce} or
5593c8
+@code{forced} (@pxref{check_appended_signatures}), and by
5593c8
+@command{verify_appended} (@pxref{verify_appended}). See
5593c8
+@xref{Using appended signatures} for more information.
5593c8
+@end deffn
5593c8
+
5593c8
+
5593c8
 @node drivemap
5593c8
 @subsection drivemap
5593c8
 
5593c8
@@ -4636,6 +4667,21 @@ This command is only available on x86 systems.
5593c8
 @end deffn
5593c8
 
5593c8
 
5593c8
+@node list_certificates
5593c8
+@subsection list_certificates
5593c8
+
5593c8
+@deffn Command list_certificates
5593c8
+List all x509 certificates trusted by GRUB for validating appended signatures.
5593c8
+The output is a numbered list of certificates, showing the certificate's serial
5593c8
+number and Common Name.
5593c8
+
5593c8
+The certificate number can be used as an argument to
5593c8
+@command{distrust_certificate} (@pxref{distrust_certificate}).
5593c8
+
5593c8
+See @xref{Using appended signatures} for more information.
5593c8
+@end deffn
5593c8
+
5593c8
+
5593c8
 @node list_env
5593c8
 @subsection list_env
5593c8
 
5593c8
@@ -4655,7 +4701,7 @@ The output is in GPG's v4 key fingerprint format (i.e., the output of
5593c8
 @code{gpg --fingerprint}).  The least significant four bytes (last
5593c8
 eight hexadecimal digits) can be used as an argument to
5593c8
 @command{distrust} (@pxref{distrust}).
5593c8
-@xref{Using digital signatures}, for more information about uses for
5593c8
+@xref{Using GPG-style digital signatures}, for more information about uses for
5593c8
 these keys.
5593c8
 @end deffn
5593c8
 
5593c8
@@ -4690,8 +4736,13 @@ When used with care, @option{--skip-sig} and the whitelist enable an
5593c8
 administrator to configure a system to boot only signed
5593c8
 configurations, but to allow the user to select from among multiple
5593c8
 configurations, and to enable ``one-shot'' boot attempts and
5593c8
-``savedefault'' behavior.  @xref{Using digital signatures}, for more
5593c8
+``savedefault'' behavior.  @xref{Using GPG-style digital signatures}, for more
5593c8
 information.
5593c8
+
5593c8
+Extra care should be taken when combining this command with appended signatures
5593c8
+(@pxref{Using appended signatures}), as this file is not validated by an
5593c8
+appended signature and could set @code{check_appended_signatures=no} if GRUB is
5593c8
+not in @pxref{Lockdown} mode.
5593c8
 @end deffn
5593c8
 
5593c8
 
5593c8
@@ -4987,7 +5038,7 @@ read.  It is possible to modify a digitally signed environment block
5593c8
 file from within GRUB using this command, such that its signature will
5593c8
 no longer be valid on subsequent boots.  Care should be taken in such
5593c8
 advanced configurations to avoid rendering the system
5593c8
-unbootable. @xref{Using digital signatures}, for more information.
5593c8
+unbootable. @xref{Using GPG-style digital signatures}, for more information.
5593c8
 @end deffn
5593c8
 
5593c8
 
5593c8
@@ -5387,11 +5438,32 @@ signatures when environment variable @code{check_signatures} is set to
5593c8
 must itself be properly signed.  The @option{--skip-sig} option can be
5593c8
 used to disable signature-checking when reading @var{pubkey_file}
5593c8
 itself. It is expected that @option{--skip-sig} is useful for testing
5593c8
-and manual booting. @xref{Using digital signatures}, for more
5593c8
+and manual booting. @xref{Using GPG-style digital signatures}, for more
5593c8
 information.
5593c8
 @end deffn
5593c8
 
5593c8
 
5593c8
+@node trust_certificate
5593c8
+@subsection trust_certificate
5593c8
+
5593c8
+@deffn Command trust_certificate x509_certificate
5593c8
+Read an DER-formatted x509 certificate from the file @var{x509_certificate}
5593c8
+and add it to GRUB's internal list of trusted x509 certificates. These
5593c8
+certificates are used to validate appended signatures when the environment
5593c8
+variable @code{check_appended_signatures} is set to @code{enforce} or
5593c8
+@code{forced}.
5593c8
+
5593c8
+Note that if @code{check_appended_signatures} is set to @code{enforce} or
5593c8
+@code{forced} when @command{trust_certificate} is executed, then
5593c8
+@var{x509_certificate} must itself bear an appended signature. (It is not
5593c8
+sufficient that @var{x509_certificate} be signed by a trusted certificate
5593c8
+according to the x509 rules: grub does not include support for validating
5593c8
+signatures within x509 certificates themselves.)
5593c8
+
5593c8
+See @xref{Using appended signatures} for more information.
5593c8
+@end deffn
5593c8
+
5593c8
+
5593c8
 @node unset
5593c8
 @subsection unset
5593c8
 
5593c8
@@ -5410,6 +5482,18 @@ only on PC BIOS platforms.
5593c8
 @end deffn
5593c8
 @end ignore
5593c8
 
5593c8
+@node verify_appended
5593c8
+@subsection verify_appended
5593c8
+
5593c8
+@deffn Command verify_appended file
5593c8
+Verifies an appended signature on @var{file} against the trusted certificates
5593c8
+known to GRUB (See @pxref{list_certificates}, @pxref{trust_certificate}, and
5593c8
+@pxref{distrust_certificate}).
5593c8
+
5593c8
+Exit code @code{$?} is set to 0 if the signature validates
5593c8
+successfully.  If validation fails, it is set to a non-zero value.
5593c8
+See @xref{Using appended signatures}, for more information.
5593c8
+@end deffn
5593c8
 
5593c8
 @node verify_detached
5593c8
 @subsection verify_detached
5593c8
@@ -5428,7 +5512,7 @@ tried.
5593c8
 
5593c8
 Exit code @code{$?} is set to 0 if the signature validates
5593c8
 successfully.  If validation fails, it is set to a non-zero value.
5593c8
-@xref{Using digital signatures}, for more information.
5593c8
+@xref{Using GPG-style digital signatures}, for more information.
5593c8
 @end deffn
5593c8
 
5593c8
 @node videoinfo
5593c8
@@ -5811,13 +5895,14 @@ environment variables and commands are listed in the same order.
5593c8
 @chapter Security
5593c8
 
5593c8
 @menu
5593c8
-* Authentication and authorisation:: Users and access control
5593c8
-* Using digital signatures::         Booting digitally signed code
5593c8
-* UEFI secure boot and shim::        Booting digitally signed PE files
5593c8
-* Secure Boot Advanced Targeting::   Embedded information for generation number based revocation
5593c8
-* Measured Boot::                    Measuring boot components
5593c8
-* Lockdown::                         Lockdown when booting on a secure setup
5593c8
-* Signing GRUB itself::              Ensuring the integrity of the GRUB core image
5593c8
+* Authentication and authorisation::   Users and access control
5593c8
+* Using GPG-style digital signatures:: Booting digitally signed code
5593c8
+* Using appended signatures::          An alternative approach to booting digitally signed code
5593c8
+* UEFI secure boot and shim::          Booting digitally signed PE files
5593c8
+* Secure Boot Advanced Targeting::     Embedded information for generation number based revocation
5593c8
+* Measured Boot::                      Measuring boot components
5593c8
+* Lockdown::                           Lockdown when booting on a secure setup
5593c8
+* Signing GRUB itself::                Ensuring the integrity of the GRUB core image
5593c8
 @end menu
5593c8
 
5593c8
 @node Authentication and authorisation
5593c8
@@ -5891,8 +5976,8 @@ generating configuration files with authentication.  You can use
5593c8
 adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
5593c8
 commands.
5593c8
 
5593c8
-@node Using digital signatures
5593c8
-@section Using digital signatures in GRUB
5593c8
+@node Using GPG-style digital signatures
5593c8
+@section Using GPG-style digital signatures in GRUB
5593c8
 
5593c8
 GRUB's @file{core.img} can optionally provide enforcement that all files
5593c8
 subsequently read from disk are covered by a valid digital signature.
5593c8
@@ -5985,6 +6070,86 @@ or BIOS) configuration to cause the machine to boot from a different
5593c8
 (attacker-controlled) device.  GRUB is at best only one link in a
5593c8
 secure boot chain.
5593c8
 
5593c8
+@node Using appended signatures
5593c8
+@section Using appended signatures in GRUB
5593c8
+
5593c8
+GRUB supports verifying Linux-style 'appended signatures' for secure boot.
5593c8
+Appended signatures are PKCS#7 messages containing a signature over the
5593c8
+contents of a file, plus some metadata, appended to the end of a file. A file
5593c8
+with an appended signature ends with the magic string:
5593c8
+
5593c8
+@example
5593c8
+~Module signature appended~\n
5593c8
+@end example
5593c8
+
5593c8
+where @code{\n} represents the line-feed character, @code{0x0a}.
5593c8
+
5593c8
+Certificates can be managed at boot time using the @pxref{trust_certificate},
5593c8
+@pxref{distrust_certificate} and @pxref{list_certificates} commands.
5593c8
+Certificates can also be built in to the core image using the @code{--x509}
5593c8
+parameter to @command{grub-install} or @command{grub-mkimage}.
5593c8
+
5593c8
+A file can be explictly verified using the @pxref{verify_appended} command.
5593c8
+
5593c8
+Only signatures made with the SHA-256 or SHA-512 hash algorithm are supported,
5593c8
+and only RSA signatures are supported.
5593c8
+
5593c8
+A file can be signed with the @command{sign-file} utility supplied with the
5593c8
+Linux kernel source. For example, if you have @code{signing.key} as the private
5593c8
+key and @code{certificate.der} as the x509 certificate containing the public key:
5593c8
+
5593c8
+@example
5593c8
+sign-file SHA256 signing.key certificate.der vmlinux vmlinux.signed
5593c8
+@end example
5593c8
+
5593c8
+Enforcement of signature verification is controlled by the
5593c8
+@code{check_appended_signatures} variable.
5593c8
+
5593c8
+@itemize
5593c8
+@item @samp{no}: no verification is performed. This is the default when GRUB
5593c8
+      is not in @pxref{Lockdown} mode.
5593c8
+@item @samp{enforce}: verification is performed. Verification can be disabled
5593c8
+      by setting the variable back to @samp{no}.
5593c8
+@item @samp{forced}: verification is performed and cannot be disabled. This is
5593c8
+      set when GRUB is in Lockdown when the appendedsig module is loaded.
5593c8
+@end itemize
5593c8
+
5593c8
+Unlike GPG-style signatures, not all files loaded by GRUB are required to be
5593c8
+signed. Once verification is turned on, the following file types will have
5593c8
+appended signatures verified:
5593c8
+
5593c8
+@itemize
5593c8
+@item Linux kernels
5593c8
+@item GRUB modules, except those built into the core image
5593c8
+@item Any new certificate files to be trusted
5593c8
+@end itemize
5593c8
+
5593c8
+ACPI tables and Device Tree images will not be checked for appended signatures
5593c8
+but must be verified by another mechanism such as GPG-style signatures before
5593c8
+they will be loaded.
5593c8
+
5593c8
+Unless lockdown mode is enabled, signature checking does @strong{not}
5593c8
+stop an attacker with console access from dropping manually to the GRUB
5593c8
+console and executing:
5593c8
+
5593c8
+@example
5593c8
+set check_appended_signatures=no
5593c8
+@end example
5593c8
+
5593c8
+Refer to the section on password-protecting GRUB (@pxref{Authentication
5593c8
+and authorisation}) for more information on preventing this.
5593c8
+
5593c8
+Additionally, unless lockdown mode is enabled:
5593c8
+
5593c8
+@itemize
5593c8
+@item Special care must be taken around the @command{loadenv} command, which
5593c8
+      can be used to turn off @code{check_appended_signature}.
5593c8
+
5593c8
+@item If the grub configuration file is loaded from the disk, anyone who can
5593c8
+      modify the file on disk can turn off @code{check_appended_signature}.
5593c8
+      Consider embedding the configuration into the core grub image.
5593c8
+@end itemize
5593c8
+
5593c8
 @node UEFI secure boot and shim
5593c8
 @section UEFI secure boot and shim support
5593c8