Re: [PATCH v2 21/22] appended signatures: documentation

[Stefan Berger <stefanb@linux.ibm.com>]

On 6/30/21 4:40 AM, Daniel Axtens wrote:
> 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>

One small thing below.


>
> ---
>
> v2: fix a grammar issue, thanks Stefan Berger.
> ---
>   docs/grub.texi | 193 ++++++++++++++++++++++++++++++++++++++++++++-----
>   1 file changed, 176 insertions(+), 17 deletions(-)
>
> diff --git a/docs/grub.texi b/docs/grub.texi
> index bed565371460..02fcda11e3bd 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -3209,6 +3209,7 @@ These variables have special meaning to GRUB.
>   
>   @menu
>   * biosnum::
> +* check_appended_signatures::
>   * check_signatures::
>   * chosen::
>   * cmdpath::
> @@ -3268,11 +3269,18 @@ 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
> +certain loaded files. @xref{Using appended signatures}.
> +
> +
>   @node check_signatures
>   @subsection check_signatures
>   
> -This variable controls whether GRUB enforces digital signature
> -validation on loaded files. @xref{Using digital signatures}.
> +This variable controls whether GRUB enforces GPG-style digital signature
> +validation on loaded files. @xref{Using GPG-style digital signatures}.
>   
>   @node chosen
>   @subsection chosen
> @@ -3989,6 +3997,7 @@ 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
>   * drivemap::                    Map a drive to another
>   * echo::                        Display a line of text
>   * eval::                        Evaluate agruments as GRUB commands
> @@ -4005,6 +4014,7 @@ you forget a command, you can run the command @command{help}
>   * keystatus::                   Check key modifier status
>   * linux::                       Load a Linux kernel
>   * linux16::                     Load a Linux kernel (16-bit mode)
> +* 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
> @@ -4042,8 +4052,10 @@ 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
>   * unset::                       Unset an environment variable
>   @comment * vbeinfo::                     List available video modes
> +* verify_appended::             Verify appended digital signature
>   * verify_detached::             Verify detached digital signature
>   * videoinfo::                   List available video modes
>   @comment * xen_*::              Xen boot commands for AArch64
> @@ -4371,9 +4383,28 @@ These keys are used to validate signatures when environment variable
>   @code{check_signatures} is set to @code{enforce}
>   (@pxref{check_signatures}), and by some invocations of
>   @command{verify_detached} (@pxref{verify_detached}).  @xref{Using
> -digital signatures}, for more information.
> +GPG-style digital signatures}, for more information.
> +@end deffn
> +
> +
> +@node distrust_certificate
> +@subsection distrust_certificate
> +
> +@deffn Command distrust_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}).
> +
> +These certificates are used to validate appended signatures when environment
> +variable @code{check_appended_signatures} is set to @code{enforce}
> +(@pxref{check_appended_signatures}), and by @command{verify_appended}
> +(@pxref{verify_appended}). See @xref{Using appended signatures} for more
> +information.
>   @end deffn
>   
> +
>   @node drivemap
>   @subsection drivemap
>   
> @@ -4631,6 +4662,21 @@ This command is only available on x86 systems.
>   @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
>   
> @@ -4650,7 +4696,7 @@ The output is in GPG's v4 key fingerprint format (i.e., the output of
>   @code{gpg --fingerprint}).  The least significant four bytes (last
>   eight hexadecimal digits) can be used as an argument to
>   @command{distrust} (@pxref{distrust}).
> -@xref{Using digital signatures}, for more information about uses for
> +@xref{Using GPG-style digital signatures}, for more information about uses for
>   these keys.
>   @end deffn
>   
> @@ -4685,8 +4731,12 @@ When used with care, @option{--skip-sig} and the whitelist enable an
>   administrator to configure a system to boot only signed
>   configurations, but to allow the user to select from among multiple
>   configurations, and to enable ``one-shot'' boot attempts and
> -``savedefault'' behavior.  @xref{Using digital signatures}, for more
> +``savedefault'' behavior.  @xref{Using GPG-style digital signatures}, for more
>   information.
> +
> +Extra care should be taken when combining this command with appended signatures
> +(@pxref{Using appended signatures}), as this file is not validated by an
> +appended signature and could set @code{check_appended_signatures=no}.
>   @end deffn
>   
>   
> @@ -4982,7 +5032,7 @@ read.  It is possible to modify a digitally signed environment block
>   file from within GRUB using this command, such that its signature will
>   no longer be valid on subsequent boots.  Care should be taken in such
>   advanced configurations to avoid rendering the system
> -unbootable. @xref{Using digital signatures}, for more information.
> +unbootable. @xref{Using GPG-style digital signatures}, for more information.
>   @end deffn
>   
>   
> @@ -5382,11 +5432,31 @@ signatures when environment variable @code{check_signatures} is set to
>   must itself be properly signed.  The @option{--skip-sig} option can be
>   used to disable signature-checking when reading @var{pubkey_file}
>   itself. It is expected that @option{--skip-sig} is useful for testing
> -and manual booting. @xref{Using digital signatures}, for more
> +and manual booting. @xref{Using GPG-style digital signatures}, for more
>   information.
>   @end deffn
>   
>   
> +@node trust_certificate
> +@subsection trust_certificate
> +
> +@deffn Command trust_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}
> +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
> +certificates themselves.)
> +
> +See @xref{Using appended signatures} for more information.
> +@end deffn
> +
> +
>   @node unset
>   @subsection unset
>   
> @@ -5405,6 +5475,18 @@ only on PC BIOS platforms.
>   @end deffn
>   @end ignore
>   
> +@node verify_appended
> +@subsection verify_appended
> +
> +@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}).
> +
> +Exit code @code{$?} is set to 0 if the signature validates
> +successfully.  If validation fails, it is set to a non-zero value.
> +See @xref{Using appended signatures}, for more information.
> +@end deffn
>   
>   @node verify_detached
>   @subsection verify_detached
> @@ -5423,7 +5505,7 @@ tried.
>   
>   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 digital signatures}, for more information.
> +@xref{Using GPG-style digital signatures}, for more information.
>   @end deffn
>   
>   @node videoinfo
> @@ -5789,13 +5871,14 @@ environment variables and commands are listed in the same order.
>   @chapter Security
>   
>   @menu
> -* Authentication and authorisation:: Users and access control
> -* Using digital signatures::         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
> -* Lockdown::                         Lockdown when booting on a secure setup
> -* Signing GRUB itself::              Ensuring the integrity of the GRUB core image
> +* 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
> +* Lockdown::                           Lockdown when booting on a secure setup
> +* Signing GRUB itself::                Ensuring the integrity of the GRUB core image
>   @end menu
>   
>   @node Authentication and authorisation
> @@ -5869,8 +5952,8 @@ generating configuration files with authentication.  You can use
>   adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
>   commands.
>   
> -@node Using digital signatures
> -@section Using digital signatures in GRUB
> +@node Using GPG-style digital signatures
> +@section Using GPG-style digital signatures in GRUB
>   
>   GRUB's @file{core.img} can optionally provide enforcement that all files
>   subsequently read from disk are covered by a valid digital signature.
> @@ -5953,6 +6036,82 @@ 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 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 carriage-return character, @code{0x0a}.


\n is 0xa but it's called line-feed.


> +
> +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}.
> +
> +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,
> +and only RSA signatures 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 x509 certificate containing the public key:
> +
> +@example
> +sign-file SHA256 signing.key certificate.der vmlinux vmlinux.signed
> +@end example
> +
> +Enforcement of signature verification is controlled by the
> +@code{check_appended_signatures} variable. Verification will only take place
> +when files are loaded if the variable is set to @code{enforce}. If a
> +certificate is built into the grub core image with the @code{--x509} parameter,
> +the variable will be automatically set to @code{enforce} when the appendedsig
> +module is loaded.
> +
> +Unlike GPG-style signatures, not all files loaded by GRUB are required to be
> +signed. Once verification is turned on, the following file types must carry
> +appended signatures:
> +
> +@enumerate
> +@item Linux, Multiboot, BSD, XNU and Plan9 kernels
> +@item Grub modules, except those built in to the core image
> +@item Any new certificate files to be trusted
> +@end enumerate
> +
> +ACPI tables and Device Tree images will not be checked for appended signatures
> +but must be verified by another mechanism such as GPG-style signatures before
> +they will be loaded.
> +
> +No attempt is made to validate any other file type. In particular,
> +chain-loaded binaries are not verified - if your platform supports
> +chain-loading and this cannot be disabled, consider an alternative secure
> +boot mechanism.
> +
> +As with GPG-style appended signatures, signature checking does @strong{not}
> +stop an attacker with console access from dropping manually to the GRUB
> +console and executing:
> +
> +@example
> +set check_appended_signatures=no
> +@end example
> +
> +Refer to the section on password-protecting GRUB (@pxref{Authentication
> +and authorisation}) for more information on preventing this.
> +
> +Additionally, special care must be taken around the @command{loadenv} command,
> +which can be used to turn off @code{check_appended_signature}.
> +
>   @node UEFI secure boot and shim
>   @section UEFI secure boot and shim support
>   


With this nit fixed: Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>