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 <g...@suse.com>
---
docs/grub.texi | 188 +++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 166 insertions(+), 22 deletions(-)
diff --git a/docs/grub.texi b/docs/grub.texi
index aba43e35e..5fe705842 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -9044,46 +9044,121 @@ 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 possible.
-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}.
+However, the Linux root user must be careful who she/he gives access to the
+TPM (tss group) since those users will also be able to modify the NV index
+that's holding the key.
-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.
+There are two types of TPM handles supported by NV index mode: persistent
+handle and NV index handle.
+
+@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, such as RSA or EC keys, are accepted.
+Thus, TPM 2.0 Key File format is not supported by persistent handles. The
+following shows 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, the following
+@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 user-defined data,
+so it can easily support both the TPM 2.0 Key File format as well as the raw
+format.
+
+The folloing @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} while
+using the 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 using the following
+tpm2-tools (@url{https://github.com/tpm2-software/tpm2-tools}) commands.
+
+@example
+@group
+# @kbd{tpm2_nvdefine -C o \
+ -a "ownerread|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 in TPM 2.0 Key File format, 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
+The following @command{grub-protect} command allows to remove 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 +10083,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 +10118,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
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
