Re: [PATCH v22 33/33] docs: Document TPM2 key protector

[Gary Lin]

On Mon, Nov 11, 2024 at 11:39:11AM -0500, Stefan Berger wrote:
> 
> 
> On 11/11/24 2:45 AM, Gary Lin via Grub-devel wrote:
> > Update the user manual to address TPM2 key protector including the two
> > related commands, tpm2_key_protector_init and tpm2_key_protector_clear,
> > and the user-space utility: grub-protect.
> > 
> > Signed-off-by: Gary Lin <glin@suse.com>
> > Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
> 
> Reviewed-by: Stefan  Berger <stefanb@linux.ibm.com>
> 
> > ---
> >   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}.
> 
> At least in the version I used there are no files with passwords in them
> involved but passwords are on the command line directly:
> 
> tpm2_changeauth -c owner newpass   -- set the owner hierachy password to
> 'newpass'
> 
> tpm2_changeauth -c owner -p newpass -- remove password from owner hierarchy
> current password is 'newpass'
> 
> tpm2_changeauth -c owner -p newpass newpass2 -- change password from
> 'newpass' to 'newpass2'
> 
Right, the password file requires the "file:" prefix for '-p'.
I'll modify the sentence a bit like this:

"
..., the following command removes the password protection with existing
password.

@example
# @kbd{tpm2_changeauth -c owner -p password}
@end example

"

Thanks,

Gary Lin

> 
> With your text adapted:
> 
> Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
>