---
docs/grub.texi | 525 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 525 insertions(+)
diff --git a/docs/grub.texi b/docs/grub.texi
index fdd49d62e..71bd6d932 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -6443,6 +6443,8 @@ you forget a command, you can run the command
@command{help}
* smbios:: Retrieve SMBIOS information
* source:: Read a configuration file in same context
* test:: Check file types and compare values
+* tpm2_key_protector_init:: Initialize the TPM2 key protector
+* tpm2_key_protector_clear:: Clear the TPM2 key protector
* true:: Do nothing, successfully
* trust:: Add public key to list of trusted keys
* unset:: Unset an environment variable
@@ -8001,6 +8003,58 @@ either @var{expression1} or @var{expression2} is true
@end table
@end deffn
+@node tpm2_key_protector_init
+@subsection tpm2_key_protector_init
+
+@deffn Command tpm2_key_protector_init [@option{-m} mode] | [@option{-p}
pcrlist] | [@option{-b} pcrbank] | [ [@option{-T} tpm2key_file] | [@option{-k}
keyfile] ] | [@option{-s} handle] | [@option{-a} srk_type] | [@option{-n}
nv_index]
+Initialize the TPM2 key protector to unseal the key for the
@command{cryptomount}
+(@pxref{cryptomount}) command. There are two supported modes,
+SRK(@kbd{srk}) and NV index(@kbd{nv}), to be specified by the option
+@option{-m}. The default mode is SRK. The main difference between SRK mode
+and NV index mode is the storage of the sealed key. For SRK mode, the sealed
+key is stored in a file while NV index mode stores the sealed key in the
+non-volatile memory inside TPM with a given NV index.
+
+The @option{-p} and @option{-b} options are used to supply the PCR list and
+bank that the key is sealed with. The PCR list is a comma-separated list, e.g.,
+'0,2,4,7,9', to represent the involved PCRs, and the default is '7'. The PCR
+bank is chosen by selecting a hash algorithm. The current supported PCR banks
+are SHA1, SHA256, SHA384, and SHA512, and the default is SHA256.
+
+Some options are only available for the specific mode. The SRK-specific
+options are @option{-T}, @option{-k}, @option{-a}, and @option{-s}. On the
+other hand, the NV index-specific option is @option{-n}.
+
+The key file for SRK mode can be supplied with either @option{-T} or
+@option{-k}. The @option{-T} option is for the path to the key file in
+TPM 2.0 Key File format. Since the parameters for the TPM commands are written
+in the file, there is no need to set the PCR list(@option{-p}) and
+bank(@option{-b}) when using the @option{-T} option. The @option{-k} option
+is for the key file in the raw format, and the @option{-p} and @option{-b}
+options are necessary for the non-default PCR list or bank. In general,
+TPM 2.0 Key File format is preferred due to the simplified GRUB command
+options and the authorized policy support
+
+Besides the key file, there are two options, @option{-a} and @option{-s}, to
+tweak the TPM Storage Root Key (SRK). The SRK can be either created at
+runtime or stored in the non-volatile memory. When creating SRK at runtime,
+GRUB provides the SRK template to the TPM to create the key. There are two SRK
+templates for the @option{-a} option, ECC and RSA, and the default is ECC.
+If the SRK is stored in a specific handle, e.g. @code{0x81000001}, the
+@option{-s} option can be used to set the handle to notify GRUB to load
+the SRK from the given handle.
+
+The only NV index-specific option is the @option{-n} option which is used to
+set the NV index containing the sealed key. Then GRUB can load the sealed
+key and unseal it with the given PCR list and bank.
+@end deffn
+
+@node tpm2_key_protector_clear
+@subsection tpm2_key_protector_clear
+
+@deffn Command tpm2_key_protector_clear
+Clear the TPM2 key protector if previously initialized.
+@end deffn
@node true
@subsection true
@@ -8529,6 +8583,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
+* TPM2 key protector:: Managing disk key with TPM2 key protector
@end menu
@node Authentication and authorisation
@@ -8772,6 +8827,310 @@ be restricted and some operations/commands cannot be
executed.
The @samp{lockdown} variable is set to @samp{y} when the GRUB is locked down.
Otherwise it does not exit.
+@node TPM2 key protector
+@section TPM2 key protector in GRUB
+
+TPM2 key protector extends measured boot to unlock the encrypted partition
+without user intervention. It uses the TPM Storage Root Key (SRK) to seal
+the disk key with a given set of PCR values. If the system state matches,
+i.e. PCR values match the sealed PCR set, TPM2 key protector unseals the
+disk key for @command{cryptomount} (@pxref{cryptomount}) to unlock the
+encrypted partition. In case the unsealed key fails to unlock the
+partition, @command{cryptomount} falls back to the passphrase prompt.
+
+Please note that TPM2 key protector uses the SRK in the owner hierarchy
+@emph{without} authorization. If the owner hierarchy is password-protected,
+TPM2 key protector may fail to unseal the key due to the absence of the
+password. For the systems that already enable the password protection for the
+owner hierarchy, the following command removes the password protection with
+the existing password stored in @file{passfile}.