466 lines
21 KiB
Diff
466 lines
21 KiB
Diff
From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
|
|
From: Sudhakar Kuppusamy <sudhakar@linux.ibm.com>
|
|
Date: Mon, 6 Oct 2025 12:55:05 +0530
|
|
Subject: [PATCH] docs/grub: Document appended signature
|
|
|
|
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: Stefan Berger <stefanb@linux.ibm.com>
|
|
Reviewed-by: Avnish Chouhan <avnish@linux.ibm.com>
|
|
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
|
|
---
|
|
docs/grub.texi | 355 +++++++++++++++++++++++++++++++++++++++++++++++----------
|
|
1 file changed, 293 insertions(+), 62 deletions(-)
|
|
|
|
diff --git a/docs/grub.texi b/docs/grub.texi
|
|
index 0b1c9d1..e4f36df 100644
|
|
--- a/docs/grub.texi
|
|
+++ b/docs/grub.texi
|
|
@@ -3274,6 +3274,7 @@ GRUB. Others may be used freely in GRUB configuration files.
|
|
These variables have special meaning to GRUB.
|
|
|
|
@menu
|
|
+* appendedsig_key_mgmt::
|
|
* biosnum::
|
|
* check_appended_signatures::
|
|
* check_signatures::
|
|
@@ -3327,6 +3328,19 @@ These variables have special meaning to GRUB.
|
|
@end menu
|
|
|
|
|
|
+@node appendedsig_key_mgmt
|
|
+@subsection appendedsig_key_mgmt
|
|
+
|
|
+This variable controls whether GRUB enforces appended signature validation
|
|
+using either @code{static} or @code{dynamic} key management. It is automatically
|
|
+set by GRUB to either @code{static} or @code{dynamic} based on the
|
|
+@strong{'ibm,secure-boot'} device tree property and Platform KeyStore (PKS).
|
|
+Also, it can be explicitly set to either @code{static} or @code{dynamic} by
|
|
+setting the @code{appendedsig_key_mgmt} variable from the GRUB console
|
|
+when the GRUB is not locked down.
|
|
+
|
|
+@xref{Using appended signatures} for more information.
|
|
+
|
|
@node biosnum
|
|
@subsection biosnum
|
|
|
|
@@ -3339,13 +3353,17 @@ 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
|
|
-certain loaded files. @xref{Using appended signatures}.
|
|
+loaded kernel and GRUB module files. It is automatically set by GRUB
|
|
+to either @code{no} or @code{yes} based on the @strong{'ibm,secure-boot'} device
|
|
+tree property. Also, it can be explicitly set to either @code{no} or @code{yes} by
|
|
+setting the @code{check_appended_signatures} variable from the GRUB console
|
|
+when the GRUB is not locked down.
|
|
|
|
+@xref{Using appended signatures} for more information.
|
|
|
|
@node check_signatures
|
|
@subsection check_signatures
|
|
@@ -4350,6 +4368,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
|
|
@@ -4469,6 +4494,140 @@ 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 an 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{yes} or the @command{append_verify} (@pxref{append_verify})
|
|
+command is executed from the GRUB console.
|
|
+
|
|
+@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 a 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/GRUB module binary hashes when the
|
|
+environment variable @code{check_appended_signatures}
|
|
+(@pxref{check_appended_signatures}) is set to @code{yes} or the
|
|
+@command{append_verify} (@pxref{append_verify}) command is executed
|
|
+from the GRUB console.
|
|
+
|
|
+Here is an example for how to generate a SHA-256 hash for a file. The hash
|
|
+will be in binary format:
|
|
+
|
|
+@example
|
|
+
|
|
+# The vmlinux (kernel image) file is your binary file, and
|
|
+# it should be unsigned.
|
|
+#
|
|
+# Generate the binary_hash.bin file from the vmlinux file
|
|
+# using OpenSSL command
|
|
+
|
|
+openssl dgst -binary -sha256 -out binary_hash.bin vmlinux
|
|
+
|
|
+@end example
|
|
+
|
|
+@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 an 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 ensure that the distrusted certificates
|
|
+are rejected during appended signatures validation when the environment
|
|
+variable @code{check_appended_signatures} is set to @code{yes}
|
|
+(@pxref{check_appended_signatures}) or the @command{append_verify}
|
|
+(@pxref{append_verify}) command is executed from the GRUB console.
|
|
+Also, these certificates are used to prevent distrusted certificates from
|
|
+being added to the db list later on.
|
|
+
|
|
+@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 a binary/certificate hash from the file @var{hash_file}
|
|
+and add it to GRUB's internal dbx list of distrusted binary/certificate hashes.
|
|
+When the environment variable @code{check_appended_signatures} (@pxref{check_appended_signatures})
|
|
+is set to @code{yes} or the @command{append_verify} (@pxref{append_verify}) command
|
|
+is executed from the GRUB console, then matching distrusted binary hashes or the signature
|
|
+validation with distrusted certificates may lead to the rejection of the Linux kernel or GRUB modules.
|
|
+Also, these hashes are used to prevent distrusted certificates and binary hashes from being
|
|
+added to the db list later on.
|
|
+
|
|
+The @option{-b} (@option{--binary-hash}) can be used to specify a binary hash file and
|
|
+@option{-c} (@option{--cert-hash}) can be used to specify a certificate hash file.
|
|
+
|
|
+Here is an example for how to generate a SHA-256 hash for a binary and a
|
|
+certificate file. The hash will be in binary format:
|
|
+
|
|
+@example
|
|
+
|
|
+# The vmlinux (kernel image) file is your binary file, and
|
|
+# it should be unsigned. The kernel.der is your certificate file.
|
|
+#
|
|
+# Generate the cert_hash.bin file from the kernel.der file
|
|
+
|
|
+openssl dgst -binary -sha256 -out cert_hash.bin kernel.der
|
|
+
|
|
+# Generate the binary_hash.bin file from the vmlinux file
|
|
+
|
|
+openssl dgst -binary -sha256 -out binary_hash.bin vmlinux
|
|
+
|
|
+@end example
|
|
+
|
|
+@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 version, serial number, issuer, subject,
|
|
+public key algorithm, RSA public key size, and certificate fingerprint.
|
|
+
|
|
+@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 version, serial number, issuer, subject,
|
|
+public key algorithm, RSA public key size, and certificate fingerprint.
|
|
+
|
|
+@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
|
|
+and hashes 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
|
|
@@ -5139,10 +5298,12 @@ configurations, and to enable ``one-shot'' boot attempts and
|
|
``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} if GRUB is
|
|
-not in @pxref{Lockdown} mode.
|
|
+If the environment variable @code{check_appended_signatures} value is set to
|
|
+@code{yes} and GRUB is in lockeddown mode, the user is not allowed to set
|
|
+@code{check_appended_signatures} to @code{no} and @code{appendedsig_key_mgmt}
|
|
+to @code{static} or @code{dynamic} either directly using @command{load_env}
|
|
+command or via environment block file. @xref{Using appended signatures}, for
|
|
+more information.
|
|
@end deffn
|
|
|
|
|
|
@@ -6488,6 +6649,7 @@ environment variables and commands are listed in the same order.
|
|
* 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 certificate and hash files:: Certificate and hash file signing
|
|
* Signing GRUB itself:: Ensuring the integrity of the GRUB core image
|
|
@end menu
|
|
|
|
@@ -6661,8 +6823,8 @@ 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
|
|
+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:
|
|
|
|
@@ -6670,73 +6832,114 @@ with an appended signature ends with the magic string:
|
|
~Module signature appended~\n
|
|
@end example
|
|
|
|
-where @code{\n} represents the line-feed character, @code{0x0a}.
|
|
+where @code{\n} represents the line feed character, @code{0x0a}.
|
|
|
|
-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}.
|
|
+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{enforce}),
|
|
+GRUB enters lockdown mode. There are three secure boot modes. They are
|
|
|
|
-A file can be explictly verified using the @pxref{verify_appended} command.
|
|
+@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{yes} and do not enter lockdown mode. Signature verification
|
|
+ is performed and if signature verification fails, display the errors and
|
|
+ allow the boot to continue.
|
|
+@item @samp{2 - enforce}: Enter lockdown mode and enforce signature verification by setting
|
|
+ @code{check_appended_signatures} (@pxref{check_appended_signatures}) to @code{yes}.
|
|
+@end itemize
|
|
|
|
-Only signatures made with the SHA-256 or SHA-512 hash algorithm are supported,
|
|
-and only RSA signatures are supported.
|
|
+Note that Linux on Power LPAR only supports @samp{0 - disabled} and @samp{2 - enforce},
|
|
+and @samp{1 - audit} is considered as secure boot being disabled.
|
|
+
|
|
+Enforcement of signature verification is controlled by the environment variable
|
|
+@code{check_appended_signatures} (@pxref{check_appended_signatures}).
|
|
+
|
|
+@itemize
|
|
+@item @samp{no}: No verification is performed. This is the default.
|
|
+@item @samp{yes}: Signature verification is performed and if signature verification fails,
|
|
+ display 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
|
|
+
|
|
+To enable appended signature verification, load the appendedsig module and an
|
|
+X.509 certificate for verification. It is recommended to build the appendedsig module
|
|
+into the core GRUB image.
|
|
+
|
|
+Key management is controlled by the environment variable @code{appendedsig_key_mgmt}
|
|
+(@pxref{appendedsig_key_mgmt}).
|
|
+
|
|
+@itemize
|
|
+@item @samp{static}: Enforce static key management signature verification. This is the default.
|
|
+ When GRUB is in lockdown mode, then the user cannot change the value of the
|
|
+ @code{appendedsig_key_mgmt}.
|
|
+@item @samp{dynamic}: Enforce dynamic key management signature verification. When GRUB is in
|
|
+ lockdown mode, then the user cannot change the value of the @code{appendedsig_key_mgmt}.
|
|
+@end itemize
|
|
+
|
|
+In static key management mode, certificates will be built into the core image using
|
|
+the @code{--x509} parameter to @command{grub-mkimage}. The list of trusted certificates
|
|
+available at boot time can be shown using @command{append_list_db} (@pxref{append_list_db}).
|
|
+Distrusted certificates can be explicitly removed from the db using @command{append_add_dbx_cert}
|
|
+(@pxref{append_add_dbx_cert}). Also, trusted certificates can be explicitly added to the db using
|
|
+@command{append_add_db_cert} (@pxref{append_add_db_cert}).
|
|
+
|
|
+In dynamic key management mode, db and dbx are read from the Platform KeyStore (PKS). If
|
|
+db does not exist in PKS, static keys (built-in keys) are used as the default keys.
|
|
+The list of trusted certificates and binary hashes available at boot time can be shown using
|
|
+@command{append_list_db} (@pxref{append_list_db}) and the list of distrusted certificates and
|
|
+binary/certificate hashes available at boot time can be shown using @command{append_list_dbx}
|
|
+(@pxref{append_list_dbx}). The trusted certificates and binary hashes can be explicitly added
|
|
+to the db using @command{append_add_db_cert} (@pxref{append_add_db_cert}) and
|
|
+@command{append_add_db_hash} (@pxref{append_add_db_hash}). Distrusted certificates can be explicitly
|
|
+added to the dbx using @command{append_add_dbx_cert} (@pxref{append_add_dbx_cert}) and distrusted
|
|
+certificate/binary hashes can be explicitly added to the dbx using @command{append_add_dbx_hash}
|
|
+(@pxref{append_add_dbx_hash}).
|
|
+
|
|
+A file can be explicitly verified using @command{append_verify} (@pxref{append_verify}).
|
|
+
|
|
+Note that when the environment variable @code{check_appended_signatures} is set to @code{yes},
|
|
+the @command{append_add_db_cert} and @command{append_add_dbx_cert} commands only accept
|
|
+the file @samp{@var{X509_certificate}} that is signed with an appended signature
|
|
+(@pxref{Signing certificate and hash files}), and the @command{append_add_db_hash} and
|
|
+@command{append_add_dbx_hash} commands only accept the file @samp{@var{hash_file}} that is
|
|
+signed with an appended signature (@pxref{Signing certificate and hash files}).
|
|
+The signature is verified by the appendedsig module.
|
|
+When the environment variable @code{check_appended_signatures} is set to @code{no},
|
|
+these commands accept files without an appended signature.
|
|
+
|
|
+Also, note that @samp{@var{X509_certificate}} should be in DER-format and @samp{@var{hash_file}}
|
|
+should be in binary format. Only SHA-256, SHA-384, or SHA-512 hashes of binary/certificate are allowed.
|
|
+Certificates/hashes of certificates/binaries added through @command{append_add_db_cert},
|
|
+@command{append_add_dbx_cert}, @command{append_add_db_hash}, and @command{append_add_dbx_hash}
|
|
+will not be persisted across boots.
|
|
+
|
|
+Only signatures created using SHA-256 or SHA-512 hash algorithm along with RSA keys of size 2048,
|
|
+3072, or 4096 bits 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:
|
|
+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
|
|
|
|
-Enforcement of signature verification is controlled by the
|
|
-@code{check_appended_signatures} variable.
|
|
+Once signature verification is turned on, the following file types must carry
|
|
+appended signatures:
|
|
|
|
-@itemize
|
|
-@item @samp{no}: no verification is performed. This is the default when GRUB
|
|
- is not in @pxref{Lockdown} mode.
|
|
-@item @samp{enforce}: verification is performed. Verification can be disabled
|
|
- by setting the variable back to @samp{no}.
|
|
-@item @samp{forced}: verification is performed and cannot be disabled. This is
|
|
- set when GRUB is in Lockdown when the appendedsig module is loaded.
|
|
-@end itemize
|
|
-
|
|
-Unlike GPG-style signatures, not all files loaded by GRUB are required to be
|
|
-signed. Once verification is turned on, the following file types will have
|
|
-appended signatures verified:
|
|
-
|
|
-@itemize
|
|
+@enumerate
|
|
@item Linux kernels
|
|
-@item GRUB modules, except those built into the core image
|
|
-@item Any new certificate files to be trusted
|
|
-@end itemize
|
|
-
|
|
-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.
|
|
-
|
|
-Unless lockdown mode is enabled, 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, unless lockdown mode is enabled:
|
|
-
|
|
-@itemize
|
|
-@item Special care must be taken around the @command{loadenv} command, which
|
|
- can be used to turn off @code{check_appended_signature}.
|
|
-
|
|
-@item If the grub configuration file is loaded from the disk, anyone who can
|
|
- modify the file on disk can turn off @code{check_appended_signature}.
|
|
- Consider embedding the configuration into the core grub image.
|
|
-@end itemize
|
|
+@item GRUB modules, except those built in to the core image
|
|
+@item Any new certificate or binary hash files to be trusted
|
|
+@item Any new certificate/binary hash files to be distrusted
|
|
+@end enumerate
|
|
+
|
|
+When GRUB is in lockdown mode (when secure boot mode is set to @code{enforce}),
|
|
+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.
|
|
|
|
@node UEFI secure boot and shim
|
|
@section UEFI secure boot and shim support
|
|
@@ -6912,6 +7115,34 @@ which increases the risk of password leakage during the process. Moreover, the
|
|
superuser list must be well maintained, and the password used cannot be
|
|
synchronized with LUKS key rotation.
|
|
|
|
+@node Signing certificate and hash files
|
|
+@section Signing certificate and hash files
|
|
+X.509 certificate (public key) files and hash files (binary/certificate hash files)
|
|
+can be signed with a Linux kernel module-style appended signature.
|
|
+
|
|
+The signer.key is a private key used for signing and signer.der is the corresponding
|
|
+public key (certificate) used for appended signature verification. Note that the
|
|
+signer.der (certificate) should exist in the db (@pxref{Using appended signatures}).
|
|
+
|
|
+@itemize
|
|
+@item Signing the X.509 certificate file using @file{sign-file}.
|
|
+The kernel.der is an X.509 certificate file.
|
|
+@example
|
|
+
|
|
+sign-file SHA256 signer.key signer.der kernel.der \
|
|
+ kernel.der.signed
|
|
+
|
|
+@end example
|
|
+@item Signing the hash file using @file{sign-file}.
|
|
+The binary_hash.bin is a binary hash file.
|
|
+@example
|
|
+
|
|
+sign-file SHA256 signer.key signer.der binary_hash.bin \
|
|
+ binary_hash.signed
|
|
+
|
|
+@end example
|
|
+@end itemize
|
|
+
|
|
@node Signing GRUB itself
|
|
@section Signing GRUB itself
|
|
To ensure a complete secure-boot chain, there must be a way for the code that
|