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 <g...@suse.com>
> > Reviewed-by: Daniel Kiper <daniel.ki...@oracle.com>
>
> Reviewed-by: Stefan Berger <stef...@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 <stef...@linux.ibm.com>
>
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
