[PATCH 10/10] docs: Update NV index mode of TPM2 key protector

[Gary Lin]

This commit updates the NV index mode section and the grub-protect
section to reflect the recent changes in TPM2 key protector and
grub-protect.

Signed-off-by: Gary Lin <glin@suse.com>
---
 docs/grub.texi | 185 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 163 insertions(+), 22 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index aba43e35e..06321e96d 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -9044,46 +9044,118 @@ When/After the shim or GRUB are updated, it only 
requires to run the last
 @subsection NV index mode
 
 Instead of storing the sealed key in a file, NV index mode uses the TPM
-non-volatile memory to store the sealed key.
+non-volatile memory to store the sealed key and could be useful when accessing
+the file is not feasible. For example, the GRUB image may be loaded from a raw
+partition in powerpc-ieee1275. If the whole root file system include '/boot'
+is encrypted, then GRUB may have problem to access the key file. With NV index
+mode, GRUB can load the key directly from the TPM non-volatile memory to
+unlock the root file system and continue the boot process.
 
-The following sample commands use tpm2-tools 
(@url{https://github.com/tpm2-software/tpm2-tools})
-commands to seal @file{luks.key} into the specific NV index: @kbd{0x81000000}.
+There are two types of TPM handles supported by NV index mode: persistent
+handle and NV index handle.
 
-First, we need to create the object file for the primary key, i.e. storage
-root key (SRK) with the default key settings in GRUB: SHA256 hash algorithm
-and ECC key algorithm.
+@subsubsection Persistent handle
+
+The range of persistent handles is from @kbd{0x81000000} to @kbd{0x81FFFFFF}.
+The persistent handle is designed to make TPM objects persistent through
+power cycles, and only TPM objects are accepted. Thus, TPM 2.0 Key File format
+is not supported by persistent handles. Here is the @command{grub-protect}
+command to seal the disk key, @file{luks.key}, into the persistent handle
+@kbd{0x81000000} with the PCRs @kbd{0,2,4,7}.
 
 @example
-# @kbd{tpm2_createprimary -C o -g sha256 -G ecc -c primary.ctx}
+@group
+# @kbd{grub-protect \
+             --protector=tpm2 \
+             --action=add \
+             --tpm2-bank=sha256 \
+             --tpm2-pcrs=0,2,4,7 \
+             --tpm2-keyfile=luks.key \
+             --tpm2-nvindex=0x81000000}
+@end group
 @end example
 
-The next commands collect the current values of PCR 0, 2, 4, and 7 and saves
-them in @file{pcr.dat}.
+To unseal the key, we have to specify the mode @kbd{nv}, the persistent handle
+@kbd{0x81000000}, and the PCRs @kbd{0,2,4,7} for the 
@command{tpm2_key_protector_init}
+command.
 
 @example
-# @kbd{tpm2_startauthsession -S session.dat}
-# @kbd{tpm2_policypcr -S session.dat -l sha256:0,2,4,7 -f pcrs.dat -L 
policy.dat}
-# @kbd{tpm2_flushcontext session.dat}
+grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x81000000 
--pcrs=0,2,4,7}
+grub> @kbd{cryptomount -u <UUID> --protector tpm2}
 @end example
 
-The last commands seal @file{luks.key} with the primary key and stores the
-result in @kbd{0x81000000}.
+If the key in the persistent handle becomes unwanted, this 
@command{grub-protect}
+removes the specified persistent handle @kbd{0x81000000}.
 
 @example
-# @kbd{cat luks.key | tpm2_create -C primary.ctx -u key.pub -r key.priv -L 
policy.dat -i-}
-# @kbd{tpm2_load -C primary.ctx -u key.pub -r key.priv -n sealing.name -c 
sealing.ctx}
-# @kbd{tpm2_evictcontrol -C o -c sealing.ctx 0x81000000}
+@group
+# @kbd{grub-protect \
+             --protector=tpm2 \
+             --action=remove \
+             --tpm2-evict \
+             --tpm2-nvindex=0x81000000}
+@end group
 @end example
 
-To unseal the key, we have to specify the mode @kbd{nv}, the NV index
-@kbd{0x81000000}, and the PCRs @kbd{0,2,4,7} for the 
@command{tpm2_key_protector_init}
-command.
+@subsubsection NV index handle
+
+The range of NV index handles is from @kbd{0x1000000} to @kbd{0x1FFFFFF}.
+Unlike the persistent handle, the NV index handle allows the user-defined data,
+so it can easily support both TPM 2.0 Key File format and the raw format.
+
+This @kbd{grub-protect} command seals the disk key, @file{luks.key}, into the
+NV index handle @kbd{0x1000000} with the PCRs @kbd{0,2,4,7} in TPM 2.0 Key
+File format.
 
 @example
-grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x81000000 
--pcrs=0,2,4,7}
+@group
+# @kbd{grub-protect \
+             --protector=tpm2 \
+             --action=add \
+             --tpm2key \
+             --tpm2-bank=sha256 \
+             --tpm2-pcrs=0,2,4,7 \
+             --tpm2-keyfile=luks.key \
+             --tpm2-nvindex=0x1000000}
+@end group
+@end example
+
+Furthermore, it is also possible to insert an existing key file,
+@file{sealed.tpm}, into the specific NV index handle with the tpm2-tools
+(@url{https://github.com/tpm2-software/tpm2-tools}) commands.
+
+@example
+@group
+# @kbd{tpm2_nvdefine -C o \
+             -a "ownerread|policywrite|ownerwrite" \
+             -s $(stat -c %s sealed.tpm) \
+             0x1000000}
+@end group
+# @kbd{tpm2_nvwrite -C o -i sealed.tpm 0x1000000}
+@end example
+
+When unsealing the key, if TPM 2.0 Key File format is used, only the mode
+@kbd{nv} and the NV index handle @kbd{0x1000000} have to be specified for
+the @command{tpm2_key_protector_init} command.
+
+@example
+grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x1000000}
 grub> @kbd{cryptomount -u <UUID> --protector tpm2}
 @end example
 
+If the key in the NV index handle becomes unwanted, this @command{grub-protect}
+command removes the specified NV index handle @kbd{0x1000000}.
+
+@example
+@group
+# @kbd{grub-protect \
+             --protector=tpm2 \
+             --action=remove \
+             --tpm2-evict \
+             --tpm2-nvindex=0x1000000}
+@end group
+@end example
+
 @subsection Setting up software TPM for EMU platform
 
 In order to test TPM2 key protector and TPM2 Software Stack (TSS2), it is
@@ -10008,11 +10080,16 @@ unsealing. (default: @samp{7})
 @item --tpm2-srk=@var{handle}
 Set the SRK handle, e.g. @samp{0x81000000}, if the SRK is to be made 
persistent.
 
+@item --tpm2-nvindex=@var{handle}
+Set the handle, e.g. @samp{0x81000000} or @samp{0x1000000}, for NV index mode.
+
 @item --tpm2key
 Use TPM 2.0 Key File format.
 
 @end table
 
+@subsection 'Add' action
+
 Before sealing the key, please check the TPM PCR usage
 (@pxref{TPM2 key protector, TPM PCR usage}) to choose a proper set of PCRs.
 
@@ -10038,12 +10115,76 @@ grub> @kbd{tpm2_key_protector_init -T 
(hd0,gpt1)/efi/grub/sealed.tpm}
 grub> @kbd{cryptomount -u <UUID> -P tpm2}
 @end example
 
+Besides sealing the key into the file, @command{grub-protect} can seal the
+key into the TPM non-volatile memory. Here is the @command{grub-protect}
+command to seal the key into the NV index handle @samp{0x1000000}.
+
+@example
+@group
+# @kbd{grub-protect --action=add \
+               --protector=tpm2 \
+               --tpm2-pcrs=0,2,4,7 \
+               --tpm2key \
+               --tpm2-keyfile=luks.key \
+               --tpm2-nvindex=0x1000000}
+@end group
+@end example
+
+Later, GRUB can fetch and unseal the key from @samp{0x1000000}.
+
+@example
+grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x1000000}
+grub> @kbd{cryptomount -u <UUID> -P tpm2}
+@end example
+
 In most of cases, the user only needs to create the key with the `add' action.
 If auto-unlocking is unwanted, just remove the file and the
 @command{tpm2_key_protector_init} command and invoke the @command{cryptomount}
 command without @kbd{-P tpm2}.
 
-The only use case for the `remove' action is when the SRK is made persistent.
+@subsection 'Remove' action
+
+The `remove' action is used to remove the handles for NV index mode and the
+persistent SRK.
+
+@subsubsection Handles for NV index mode
+
+There are two types of TPM handles supported by NV index mode: persistent
+handles and NV index handles, and @command{tpm2_getcap} can be used to
+check the existing handles.
+
+To get the existing persistent handles:
+
+@example
+@group
+# @kbd{tpm2_getcap handles-persistent}
+- 0x81000000
+@end group
+@end example
+
+Similarly, to get the existing nv-index handles:
+
+@example
+@group
+# @kbd{tpm2_getcap handles-nv-index}
+- 0x1000000
+@end group
+@end example
+
+If the sealed key in the handle is not needed anymore, the user can remove
+the handle with @kbd{--tpm2-nvindex} and @kbd{--tpm2-evict}. For example,
+this command removes the data from @samp{0x1000000}
+
+@example
+@group
+# @kbd{grub-protect --action=remove \
+               --protector=tpm2 \
+               --tpm2-evict \
+               --tpm2-nvindex 0x1000000} \
+@end group
+@end example
+
+@subsubsection Persistent SRK
 
 There are two supported SRKs in @command{grub-protect}: @samp{RSA} and 
@samp{ECC}.
 Due to slower key generation, some users of the @samp{RSA} SRK may prefer
-- 
2.43.0