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

3efed6
From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
3efed6
From: Daniel Axtens <dja@axtens.net>
3efed6
Date: Thu, 1 Oct 2020 13:02:09 +1000
3efed6
Subject: [PATCH] appended signatures: documentation
3efed6
3efed6
This explains how appended signatures can be used to form part of
3efed6
a secure boot chain, and documents the commands and variables
3efed6
introduced.
3efed6
3efed6
(docs: s/grub/grub2/)
3efed6
Signed-off-by: Daniel Axtens <dja@axtens.net>
3efed6
---
3efed6
 docs/grub.texi | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
3efed6
 1 file changed, 172 insertions(+), 13 deletions(-)
3efed6
3efed6
diff --git a/docs/grub.texi b/docs/grub.texi
b71686
index a833364d5..97f0f47e0 100644
3efed6
--- a/docs/grub.texi
3efed6
+++ b/docs/grub.texi
3efed6
@@ -3160,6 +3160,7 @@ These variables have special meaning to GRUB.
3efed6
 
3efed6
 @menu
3efed6
 * biosnum::
3efed6
+* check_appended_signatures::
3efed6
 * check_signatures::
3efed6
 * chosen::
3efed6
 * cmdpath::
3efed6
@@ -3219,11 +3220,18 @@ For an alternative approach which also changes BIOS drive mappings for the
3efed6
 chain-loaded system, @pxref{drivemap}.
3efed6
 
3efed6
 
3efed6
+@node check_appended_signatures
3efed6
+@subsection check_appended_signatures
3efed6
+
3efed6
+This variable controls whether GRUB enforces appended signature validation on
3efed6
+certain loaded files. @xref{Using appended signatures}.
3efed6
+
3efed6
+
3efed6
 @node check_signatures
3efed6
 @subsection check_signatures
3efed6
 
3efed6
-This variable controls whether GRUB enforces digital signature
3efed6
-validation on loaded files. @xref{Using digital signatures}.
3efed6
+This variable controls whether GRUB enforces GPG-style digital signature
3efed6
+validation on loaded files. @xref{Using GPG-style digital signatures}.
3efed6
 
3efed6
 @node chosen
3efed6
 @subsection chosen
3efed6
@@ -3937,6 +3945,7 @@ you forget a command, you can run the command @command{help}
3efed6
 * date::                        Display or set current date and time
3efed6
 * devicetree::                  Load a device tree blob
3efed6
 * distrust::                    Remove a pubkey from trusted keys
3efed6
+* distrust_certificate::        Remove a certificate from the list of trusted certificates
3efed6
 * drivemap::                    Map a drive to another
3efed6
 * echo::                        Display a line of text
3efed6
 * eval::                        Evaluate agruments as GRUB commands
3efed6
@@ -3953,6 +3962,7 @@ you forget a command, you can run the command @command{help}
3efed6
 * keystatus::                   Check key modifier status
3efed6
 * linux::                       Load a Linux kernel
3efed6
 * linux16::                     Load a Linux kernel (16-bit mode)
3efed6
+* list_certificates::           List trusted certificates
3efed6
 * list_env::                    List variables in environment block
3efed6
 * list_trusted::                List trusted public keys
3efed6
 * load_env::                    Load variables from environment block
3efed6
@@ -3989,9 +3999,11 @@ you forget a command, you can run the command @command{help}
3efed6
 * test::                        Check file types and compare values
3efed6
 * true::                        Do nothing, successfully
3efed6
 * trust::                       Add public key to list of trusted keys
3efed6
+* trust_certificate::           Add an x509 certificate to the list of trusted certificates
3efed6
 * unset::                       Unset an environment variable
3efed6
 * uppermem::                    Set the upper memory size
3efed6
 @comment * vbeinfo::                     List available video modes
3efed6
+* verify_appended::             Verify appended digital signature
3efed6
 * verify_detached::             Verify detached digital signature
3efed6
 * videoinfo::                   List available video modes
3efed6
 @comment * xen_*::              Xen boot commands for AArch64
3efed6
@@ -4282,9 +4294,28 @@ These keys are used to validate signatures when environment variable
3efed6
 @code{check_signatures} is set to @code{enforce}
3efed6
 (@pxref{check_signatures}), and by some invocations of
3efed6
 @command{verify_detached} (@pxref{verify_detached}).  @xref{Using
3efed6
-digital signatures}, for more information.
3efed6
+GPG-style digital signatures}, for more information.
3efed6
 @end deffn
3efed6
 
3efed6
+
3efed6
+@node distrust_certificate
3efed6
+@subsection distrust_certificate
3efed6
+
3efed6
+@deffn Command distrust_certificate cert_number
3efed6
+Remove the x509 certificate numbered @var{cert_number} from GRUB's keyring of
3efed6
+trusted x509 certificates for verifying appended signatures.
3efed6
+
3efed6
+@var{cert_number} is the certificate number as listed by
3efed6
+@command{list_certificates} (@pxref{list_certificates}).
3efed6
+
3efed6
+These certificates are used to validate appended signatures when environment
3efed6
+variable @code{check_appended_signatures} is set to @code{enforce}
3efed6
+(@pxref{check_appended_signatures}), and by @command{verify_appended}
3efed6
+(@pxref{verify_appended}). See @xref{Using appended signatures} for more
3efed6
+information.
3efed6
+@end deffn
3efed6
+
3efed6
+
3efed6
 @node drivemap
3efed6
 @subsection drivemap
3efed6
 
3efed6
@@ -4542,6 +4573,21 @@ This command is only available on x86 systems.
3efed6
 @end deffn
3efed6
 
3efed6
 
3efed6
+@node list_certificates
3efed6
+@subsection list_certificates
3efed6
+
3efed6
+@deffn Command list_certificates
3efed6
+List all x509 certificates trusted by GRUB for validating appended signatures.
3efed6
+The output is a numbered list of certificates, showing the certificate's serial
3efed6
+number and Common Name.
3efed6
+
3efed6
+The certificate number can be used as an argument to
3efed6
+@command{distrust_certificate} (@pxref{distrust_certificate}).
3efed6
+
3efed6
+See @xref{Using appended signatures} for more information.
3efed6
+@end deffn
3efed6
+
3efed6
+
3efed6
 @node list_env
3efed6
 @subsection list_env
3efed6
 
3efed6
@@ -4561,7 +4607,7 @@ The output is in GPG's v4 key fingerprint format (i.e., the output of
3efed6
 @code{gpg --fingerprint}).  The least significant four bytes (last
3efed6
 eight hexadecimal digits) can be used as an argument to
3efed6
 @command{distrust} (@pxref{distrust}).
3efed6
-@xref{Using digital signatures}, for more information about uses for
3efed6
+@xref{Using GPG-style digital signatures}, for more information about uses for
3efed6
 these keys.
3efed6
 @end deffn
3efed6
 
3efed6
@@ -4596,8 +4642,12 @@ When used with care, @option{--skip-sig} and the whitelist enable an
3efed6
 administrator to configure a system to boot only signed
3efed6
 configurations, but to allow the user to select from among multiple
3efed6
 configurations, and to enable ``one-shot'' boot attempts and
3efed6
-``savedefault'' behavior.  @xref{Using digital signatures}, for more
3efed6
+``savedefault'' behavior.  @xref{Using GPG-style digital signatures}, for more
3efed6
 information.
3efed6
+
3efed6
+Extra care should be taken when combining this command with appended signatures
3efed6
+(@pxref{Using appended signatures}), as this file is not validated by an
3efed6
+appended signature and could set @code{check_appended_signatures=no}.
3efed6
 @end deffn
3efed6
 
3efed6
 
3efed6
@@ -4883,7 +4933,7 @@ read.  It is possible to modify a digitally signed environment block
3efed6
 file from within GRUB using this command, such that its signature will
3efed6
 no longer be valid on subsequent boots.  Care should be taken in such
3efed6
 advanced configurations to avoid rendering the system
3efed6
-unbootable. @xref{Using digital signatures}, for more information.
3efed6
+unbootable. @xref{Using GPG-style digital signatures}, for more information.
3efed6
 @end deffn
3efed6
 
3efed6
 
3efed6
@@ -5208,11 +5258,31 @@ signatures when environment variable @code{check_signatures} is set to
3efed6
 must itself be properly signed.  The @option{--skip-sig} option can be
3efed6
 used to disable signature-checking when reading @var{pubkey_file}
3efed6
 itself. It is expected that @option{--skip-sig} is useful for testing
3efed6
-and manual booting. @xref{Using digital signatures}, for more
3efed6
+and manual booting. @xref{Using GPG-style digital signatures}, for more
3efed6
 information.
3efed6
 @end deffn
3efed6
 
3efed6
 
3efed6
+@node trust_certificate
3efed6
+@subsection trust_certificate
3efed6
+
3efed6
+@deffn Command trust_certificate x509_certificate
3efed6
+Read an DER-formatted x509 certificate from the file @var{x509_certificate}
3efed6
+and add it to GRUB's internal list of trusted x509 certificates. These
3efed6
+certificates are used to validate appended signatures when the environment
3efed6
+variable @code{check_appended_signatures} is set to @code{enforce}.
3efed6
+
3efed6
+Note that if @code{check_appended_signatures} is set to @code{enforce}
3efed6
+when @command{trust_certificate} is executed, then @var{x509_certificate}
3efed6
+must itself bear an appended signature. (It is not sufficient that
3efed6
+@var{x509_certificate} be signed by a trusted certificate according to the
3efed6
+x509 rules: grub does not include support for validating signatures within x509
3efed6
+certificates themselves.)
3efed6
+
3efed6
+See @xref{Using appended signatures} for more information.
3efed6
+@end deffn
3efed6
+
3efed6
+
3efed6
 @node unset
3efed6
 @subsection unset
3efed6
 
3efed6
@@ -5237,6 +5307,18 @@ only on PC BIOS platforms.
3efed6
 @end deffn
3efed6
 @end ignore
3efed6
 
3efed6
+@node verify_appended
3efed6
+@subsection verify_appended
3efed6
+
3efed6
+@deffn Command verify_appended file
3efed6
+Verifies an appended signature on @var{file} against the trusted certificates
3efed6
+known to GRUB (See @pxref{list_certificates}, @pxref{trust_certificate}, and
3efed6
+@pxref{distrust_certificate}).
3efed6
+
3efed6
+Exit code @code{$?} is set to 0 if the signature validates
3efed6
+successfully.  If validation fails, it is set to a non-zero value.
3efed6
+See @xref{Using appended signatures}, for more information.
3efed6
+@end deffn
3efed6
 
3efed6
 @node verify_detached
3efed6
 @subsection verify_detached
3efed6
@@ -5255,7 +5337,7 @@ tried.
3efed6
 
3efed6
 Exit code @code{$?} is set to 0 if the signature validates
3efed6
 successfully.  If validation fails, it is set to a non-zero value.
3efed6
-@xref{Using digital signatures}, for more information.
3efed6
+@xref{Using GPG-style digital signatures}, for more information.
3efed6
 @end deffn
3efed6
 
3efed6
 @node videoinfo
3efed6
@@ -5601,9 +5683,10 @@ environment variables and commands are listed in the same order.
3efed6
 @chapter Security
3efed6
 
3efed6
 @menu
3efed6
-* Authentication and authorisation:: Users and access control
3efed6
-* Using digital signatures::         Booting digitally signed code
3efed6
-* Signing GRUB itself::              Ensuring the integrity of the GRUB core image
3efed6
+* Authentication and authorisation::   Users and access control
3efed6
+* Using GPG-style digital signatures:: Booting digitally signed code
3efed6
+* Using appended signatures::          An alternative approach to booting digitally signed code
3efed6
+* Signing GRUB itself::                Ensuring the integrity of the GRUB core image
3efed6
 @end menu
3efed6
 
3efed6
 @node Authentication and authorisation
3efed6
@@ -5676,8 +5759,8 @@ generating configuration files with authentication.  You can use
3efed6
 adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
3efed6
 commands.
3efed6
 
3efed6
-@node Using digital signatures
3efed6
-@section Using digital signatures in GRUB
3efed6
+@node Using GPG-style digital signatures
3efed6
+@section Using GPG-style digital signatures in GRUB
3efed6
 
3efed6
 GRUB's @file{core.img} can optionally provide enforcement that all files
3efed6
 subsequently read from disk are covered by a valid digital signature.
3efed6
@@ -5760,6 +5843,82 @@ or BIOS) configuration to cause the machine to boot from a different
3efed6
 (attacker-controlled) device.  GRUB is at best only one link in a
3efed6
 secure boot chain.
3efed6
 
3efed6
+@node Using appended signatures
3efed6
+@section Using appended signatures in GRUB
3efed6
+
3efed6
+GRUB supports verifying Linux-style 'appended signatures' for secure boot.
3efed6
+Appended signatures are PKCS#7 messages containing a signature over the
3efed6
+contents of a file, plus some metadata, appended to the end of a file. A file
3efed6
+with an appended signature ends with the magic string:
3efed6
+
3efed6
+@example
3efed6
+~Module signature appended~\n
3efed6
+@end example
3efed6
+
3efed6
+where @code{\n} represents the carriage-return character, @code{0x0a}.
3efed6
+
3efed6
+To enable appended signature verification, load the appendedsig module and an
3efed6
+x509 certificate for verification. Building the appendedsig module into the
3efed6
+core grub image is recommended.
3efed6
+
3efed6
+Certificates can be managed at boot time using the @pxref{trust_certificate},
3efed6
+@pxref{distrust_certificate} and @pxref{list_certificates} commands.
3efed6
+Certificates can also be built in to the core image using the @code{--x509}
3efed6
+parameter to @command{grub-install} or @command{grub-mkimage}.
3efed6
+
3efed6
+A file can be explictly verified using the @pxref{verify_appended} command.
3efed6
+
3efed6
+Only signatures made with the SHA-256 or SHA-512 hash algorithm are supported,
3efed6
+and only RSA signatures are supported.
3efed6
+
3efed6
+A file can be signed with the @command{sign-file} utility supplied with the
3efed6
+Linux kernel source. For example, if you have @code{signing.key} as the private
3efed6
+key and @code{certificate.der} as the x509 certificate containing the public key:
3efed6
+
3efed6
+@example
3efed6
+sign-file SHA256 signing.key certificate.der vmlinux vmlinux.signed
3efed6
+@end example
3efed6
+
3efed6
+Enforcement of signature verification is controlled by the
3efed6
+@code{check_appended_signatures} variable. Verification will only take place
3efed6
+when files are loaded if the variable is set to @code{enforce}. If a
3efed6
+certificate is built into the grub core image with the @code{--x509} parameter,
3efed6
+the variable will be automatically set to @code{enforce} when the appendedsig
3efed6
+module is loaded.
3efed6
+
3efed6
+Unlike GPG-style signatures, not all files loaded by GRUB are required to be
3efed6
+signed. Once verification is turned on, the following file types must carry
3efed6
+appended signatures:
3efed6
+
3efed6
+@enumerate
3efed6
+@item Linux, Multiboot, BSD, XNU and Plan9 kernels
3efed6
+@item Grub modules, except those built in to the core image
3efed6
+@item Any new certificate files to be trusted
3efed6
+@end enumerate
3efed6
+
3efed6
+ACPI tables and Device Tree images will not be checked for appended signatures
3efed6
+but must be verified by another mechanism such as GPG-style signatures before
3efed6
+they will be loaded.
3efed6
+
3efed6
+No attempt is made to validate any other file type. In particular,
3efed6
+chain-loaded binaries are not verified - if your platform supports
3efed6
+chain-loading and this cannot be disabled, consider an alternative secure
3efed6
+boot mechanism.
3efed6
+
3efed6
+As with GPG-style appended signatures, signature checking does @strong{not}
3efed6
+stop an attacker with console access from dropping manually to the GRUB
3efed6
+console and executing:
3efed6
+
3efed6
+@example
3efed6
+set check_appended_signatures=no
3efed6
+@end example
3efed6
+
3efed6
+Refer to the section on password-protecting GRUB (@pxref{Authentication
3efed6
+and authorisation}) for more information on preventing this.
3efed6
+
3efed6
+Additionally, special care must be taken around the @command{loadenv} command,
3efed6
+which can be used to turn off @code{check_appended_signature}.
3efed6
+
3efed6
 @node Signing GRUB itself
3efed6
 @section Signing GRUB itself
3efed6