[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 00/10] TPM2 key protector follow-up patches
|
From: |
Gary Lin |
|
Subject: |
[PATCH v2 00/10] TPM2 key protector follow-up patches |
|
Date: |
Thu, 9 Jan 2025 11:58:25 +0800 |
git: https://github.com/lcp/grub2/tree/tpm2-follow-up-v2
This patchset is the collection of several enhancements for TPM2 key
protector.
* Patch 1 introduces the PCR dump to help debugging policy fail.
* Patch 2~3 adds the new command to dump PCRs in GRUB shell and the
* documentation of the command.
* Patch 4 fixes a minor issue in tss2.
* Patch 5~8 extends the NV index mode to support 'NV index' handles
and TPM 2.0 Key File format.
- Thanks to James Bottomley for how to detect TPM 2.0 Key File format.
https://lists.gnu.org/archive/html/grub-devel/2024-11/msg00078.html
* Patch 9~10 update the test cases and the documentation for NV index
mode.
v2:
- Amending the commit messages and the error messages
- Fixing the return values and the checks for 'bool'
- Removing 'policywrite' when defining the NV index handle
- Fixing the typo and the stray whitespace
- Removing grub_tpm2_flushcontext() from the functions to remove
the persistent handle and the NV index handle
- Avoiding one failure test case to stop the whole test
- Improving the document
Gary Lin (10):
tpm2_key_protector: dump PCRs on policy fail
tpm2_key_protector: Add 'tpm2_dump_pcr' command
docs: Document tpm2_dump_pcr
tss2: Fix the missing authCommand
tss2: Add TPM 2.0 NV index commands
tpm2_key_protector: Unseal key from a buffer
tpm2_key_protector: Support NV index handles
util/grub-protect: Support NV index mode
tests/tpm2_key_protector_test: Amend the NV index mode test
docs: Update NV index mode of TPM2 key protector
docs/grub.texi | 201 ++++++++--
.../commands/tpm2_key_protector/module.c | 345 +++++++++++++++---
grub-core/lib/tss2/tpm2_cmd.c | 211 ++++++++++-
grub-core/lib/tss2/tpm2_cmd.h | 32 ++
grub-core/lib/tss2/tss2_mu.c | 39 ++
grub-core/lib/tss2/tss2_mu.h | 12 +
grub-core/lib/tss2/tss2_types.h | 6 +
tests/tpm2_key_protector_test.in | 155 +++-----
util/grub-protect.c | 343 ++++++++++++++---
9 files changed, 1112 insertions(+), 232 deletions(-)
Range-diff against v1:
-: --------- > 1: cf2be1c66 tpm2_key_protector: dump PCRs on policy fail
1: c39ea8971 ! 2: 052089a84 tpm2_key_protector: Add 'tpm2_dump_pcr' command
@@ Commit message
specified bank.
Signed-off-by: Gary Lin <glin@suse.com>
+ Tested-by: Stefan Berger <stefanb@linux.ibm.com>
## grub-core/commands/tpm2_key_protector/module.c ##
@@ grub-core/commands/tpm2_key_protector/module.c: static grub_extcmd_t
tpm2_protector_init_cmd;
2: f78c78801 ! 3: 01f27df8a docs: Document tpm2_dump_pcr
@@ Commit message
Update the documentation to address tpm2_dump_pcr.
Signed-off-by: Gary Lin <glin@suse.com>
+ Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
## docs/grub.texi ##
@@ docs/grub.texi: you forget a command, you can run the command
@command{help}
3: f08c7a04c ! 4: 242483c87 tss2: Fix the missing authCommand
@@ Commit message
Also fix a few pointer checks.
Signed-off-by: Gary Lin <glin@suse.com>
+ Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
## grub-core/lib/tss2/tpm2_cmd.c ##
@@ grub-core/lib/tss2/tpm2_cmd.c: grub_tpm2_readpublic (const
TPMI_DH_OBJECT_t objectHandle,
4: 3ec885d51 ! 5: 3f0aca8af tss2: Add TPM 2.0 NV index commands
@@ Commit message
The related marshal/unmarshal functions are also introduced.
Signed-off-by: Gary Lin <glin@suse.com>
+ Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
## grub-core/lib/tss2/tpm2_cmd.c ##
@@ grub-core/lib/tss2/tpm2_cmd.c: grub_tpm2_testparms (const
TPMT_PUBLIC_PARMS_t *parms,
5: 60ffe8b5e ! 6: 0e7b6fe17 tpm2_key_protector: Unseal key from a buffer
@@ Metadata
## Commit message ##
tpm2_key_protector: Unseal key from a buffer
- As the preparation to load the sealed key from the NV index handle,
- the logic to handle the file buffer is extracted as an independent
- function and the SRK recover function only reads the file and sends the
- file buffer to the new function. Besides, the file format is detected
+ Extract the logic to handle the file buffer from the SRK recover
+ function to prepare to load the sealed key from the NV index handle.
+ The SRK recover function now only reads the file and sends the file
+ buffer to the new function. Besides this, the file format is detected
automatically before unmarshalling the data, so there is no need to use
the command option to specify the file format anymore. In other words,
'--tpm2key' and '--keyfile' are the same now.
Signed-off-by: Gary Lin <glin@suse.com>
+ Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
## grub-core/commands/tpm2_key_protector/module.c ##
@@ grub-core/commands/tpm2_key_protector/module.c:
tpm2_protector_srk_read_file (const char *filepath, void **buffer, grub_size_t *
@@ grub-core/commands/tpm2_key_protector/module.c:
tpm2_protector_srk_read_file (co
+
+ /* Need at least the first two bytes to check the tag and the length */
+ if (buffer_size < 2)
-+ return 0;
++ return false;
+
+ /* The first byte is always 0x30 (SEQUENCE). */
+ if (buffer[0] != 0x30)
-+ return 0;
++ return false;
+
+ /*
+ * Get the bytes of the length
@@ grub-core/commands/tpm2_key_protector/module.c:
tpm2_protector_srk_read_file (co
+
+ /* Make sure the buffer is large enough to contain id-sealedkey OID */
+ if (buffer_size < skip + sizeof (sealed_key_oid))
-+ return 0;
++ return false;
+
+ /* Check id-sealedkey OID */
+ if (grub_memcmp (buffer + skip, sealed_key_oid, sizeof
(sealed_key_oid)) != 0)
-+ return 0;
++ return false;
+
-+ return 1;
++ return true;
+}
+
static grub_err_t
6: 31d96a633 ! 7: 1afe60a7e tpm2_key_protector: Support NV index handles
@@ Commit message
tpm2_key_protector: Support NV index handles
Previously, NV index mode only supported persistent handles which are
- only for the TPM objects. Without introducing new parameters, it is
- difficult to support authorized policy.
+ only for TPM objects.
On the other hand, the "NV index" handle allows the user-defined data,
so it can be an alternative to the key file and support TPM 2.0 Key
File format immediately.
- The following tpm2-tools commands stores the given key file,
sealed.tpm,
+ The following tpm2-tools commands store the given key file, sealed.tpm,
in either TPM 2.0 Key File format or the raw format into the NV index
- handle, 0x1000000.
+ handle 0x1000000.
# tpm2_nvdefine -C o \
- -a "ownerread|policywrite|ownerwrite" \
+ -a "ownerread|ownerwrite" \
-s $(stat -c %s sealed.tpm) \
0x1000000
# tpm2_nvwrite -C o -i sealed.tpm 0x1000000
@@ grub-core/commands/tpm2_key_protector/module.c:
tpm2_protector_nv_recover (const
tpm2_protector_recover (const tpm2_protector_context_t *ctx,
grub_uint8_t **key, grub_size_t *key_size)
@@ grub-core/commands/tpm2_key_protector/module.c:
tpm2_protector_check_args (tpm2_protector_context_t *ctx)
- return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in SRK mode, please
specify a key file with only --tpm2key/-T or --keyfile/-k"));
-
- if (ctx->mode == TPM2_PROTECTOR_MODE_SRK && ctx->nv != 0)
-- return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in SRK mode, an NV
Index cannot be specified"));
-+ return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in SRK mode, a NV Index
cannot be specified"));
-
- /* Checks for NV mode */
- if (ctx->mode == TPM2_PROTECTOR_MODE_NV && ctx->nv == 0)
-- return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode, an NV
Index must be specified: --nvindex or -n"));
-+ return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode, a NV
Index must be specified: --nvindex or -n"));
if (ctx->mode == TPM2_PROTECTOR_MODE_NV &&
(ctx->tpm2key != NULL || ctx->keyfile != NULL))
- return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode, a
keyfile cannot be specified"));
+- return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode, a
keyfile cannot be specified"));
++ return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("a key file cannot be
specified when using NV index mode"));
- if (ctx->mode == TPM2_PROTECTOR_MODE_NV && ctx->srk != 0)
- return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode, an
SRK cannot be specified"));
+ if (ctx->mode == TPM2_PROTECTOR_MODE_NV && TPM_HT_IS_PERSISTENT
(ctx->nv) == true &&
+ (ctx->srk != 0 || ctx->srk_type.type != TPM_ALG_ERROR))
-+ return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode with a
persistent handle, a SRK cannot be specified"));
++ return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("an SRK cannot be
specified when using NV index mode with a persistent handle"));
if (ctx->mode == TPM2_PROTECTOR_MODE_NV &&
- ctx->srk_type.type != TPM_ALG_ERROR)
- return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode, an
asymmetric key type cannot be specified"));
+ (TPM_HT_IS_PERSISTENT (ctx->nv) == false && TPM_HT_IS_NVINDEX
(ctx->nv) == false))
-+ return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("in NV Index mode, a NV
index must be a persistent or NV index handle"));
++ return grub_error (GRUB_ERR_BAD_ARGUMENT, N_("an NV index must be
either a persistent handle or an NV index handle when using NV index mode"));
/* Defaults assignment */
if (ctx->bank == TPM_ALG_ERROR)
@@ grub-core/commands/tpm2_key_protector/module.c:
tpm2_protector_check_args (tpm2_
- if (ctx->mode == TPM2_PROTECTOR_MODE_SRK &&
- ctx->srk_type.type == TPM_ALG_ERROR)
+ /*
-+ * Set ECC_NIS_P256 as the default SRK when using SRK mode or NV mode
with
-+ * a NV index handle
++ * Set ECC_NIST_P256 as the default SRK when using SRK mode or NV mode
with
++ * an NV index handle
+ */
+ if (ctx->srk_type.type == TPM_ALG_ERROR &&
+ (ctx->mode == TPM2_PROTECTOR_MODE_SRK ||
7: c7fc5bd22 ! 8: e6e7982d5 util/grub-protect: Support NV index mode
@@ Commit message
1. Persistent handle (0x81000000~0x81FFFFFF)
TPM 2.0 Key File format (--tpm2key) is not supported due to the
limitation of persistent handles. This 'grub-protect' command
- seals the key into the persistent handle, 0x81000000.
+ seals the key into the persistent handle 0x81000000.
# grub-protect \
--protector=tpm2 \
@@ Commit message
2. NV index handle (0x1000000~0x1FFFFFF)
Both TPM 2.0 Key File format and the raw format are supported by NV
index handles. Here is the 'grub-protect' command to seal the key in
- TPM 2.0 Key File format into the NV index handle, 0x1000000.
+ TPM 2.0 Key File format into the NV index handle 0x1000000.
# grub-protect \
--protector=tpm2 \
@@ Commit message
Besides the 'add' action, the corresponding 'remove' action is also
introduced. To remove the data from a persistent or NV index handle,
just use '--tpm2-nvindex=HANDLE' combining with '--tpm2-evict'. This
- sample command removes the data from the NV index handle, 0x1000000.
+ sample command removes the data from the NV index handle 0x1000000.
# grub-protect \
--protector=tpm2 \
@@ util/grub-protect.c: protect_tpm2_export_sealed_key (const char
*filepath,
+
+ pub_info.nvPublic.nvIndex = args->tpm2_nvindex;
+ pub_info.nvPublic.nameAlg = TPM_ALG_SHA256;
-+ pub_info.nvPublic.attributes = TPMA_NV_POLICYWRITE | TPMA_NV_OWNERWRITE
| TPMA_NV_OWNERREAD;
++ pub_info.nvPublic.attributes = TPMA_NV_OWNERWRITE | TPMA_NV_OWNERREAD;
+ pub_info.nvPublic.dataSize = (grub_uint16_t) data_size;
+
+ authCmd.sessionHandle = TPM_RS_PW;
@@ util/grub-protect.c: protect_tpm2_add (protect_args_t *args)
+ }
+ }
+
-+ if (TPM_HT_IS_NVINDEX (args->tpm2_nvindex))
++ if (TPM_HT_IS_NVINDEX (args->tpm2_nvindex) == true)
+ {
+ err = protect_tpm2_export_nvindex (args, out_buf, out_buf_size);
+ if (err != GRUB_ERR_NONE)
+ goto exit3;
+ }
-+ else if (TPM_HT_IS_PERSISTENT (args->tpm2_nvindex))
++ else if (TPM_HT_IS_PERSISTENT (args->tpm2_nvindex) == true)
+ {
+ err = protect_tpm2_export_persistent (args, srk, &sealed_key);
+ if (err != GRUB_ERR_NONE)
@@ util/grub-protect.c: protect_tpm2_add (protect_args_t *args)
TPM2B_PUBLIC_t public;
- TPMS_AUTH_COMMAND_t authCommand = {0};
+ TPMS_AUTH_COMMAND_t authCmd = {0};
-+ grub_err_t err;
+
+ /* Find the persistent handle */
+ rc = grub_tpm2_readpublic (handle, NULL, &public);
+ if (rc != TPM_RC_SUCCESS)
+ {
+ fprintf (stderr, "Handle 0x%x not found.\n", handle);
-+ return GRUB_ERR_BAD_ARGUMENT;;
++ return GRUB_ERR_BAD_ARGUMENT;
+ }
+
+ /* Evict the persistent handle */
@@ util/grub-protect.c: protect_tpm2_add (protect_args_t *args)
+ if (rc != TPM_RC_SUCCESS)
+ {
+ fprintf (stderr, "Failed to evict handle 0x%x (TPM2_EvictControl:
0x%x).\n", handle, rc);
-+ err = GRUB_ERR_BAD_DEVICE;
-+ goto exit;
++ return GRUB_ERR_BAD_DEVICE;
+ }
+
-+ err = GRUB_ERR_NONE;
-+
-+ exit:
-+ grub_tpm2_flushcontext (handle);
-+
-+ return err;
++ return GRUB_ERR_NONE;
+}
+
+static grub_err_t
@@ util/grub-protect.c: protect_tpm2_add (protect_args_t *args)
+ TPM2B_NV_PUBLIC_t nv_public;
+ TPMS_AUTH_COMMAND_t authCmd = {0};
+ TPM2B_NAME_t nv_name;
-+ grub_err_t err;
+
+ /* Find the nvindex handle */
+ rc = grub_tpm2_nv_readpublic (handle, NULL, &nv_public, &nv_name);
@@ util/grub-protect.c: protect_tpm2_add (protect_args_t *args)
+ if (rc != TPM_RC_SUCCESS)
+ {
+ fprintf (stderr, "Failed to undefine handle 0x%x
(TPM2_NV_UndefineSpace: 0x%x).\n", handle, rc);
-+ err = GRUB_ERR_BAD_DEVICE;
-+ goto exit;
++ return GRUB_ERR_BAD_DEVICE;
+ }
+
-+ err = GRUB_ERR_NONE;
-+
-+ exit:
-+ grub_tpm2_flushcontext (handle);
-+
-+ return err;
++ return GRUB_ERR_NONE;
+}
+
+static grub_err_t
@@ util/grub-protect.c: protect_tpm2_remove (protect_args_t *args)
- fprintf (stderr, "Failed to evict SRK with handle 0x%x
(TPM2_EvictControl: 0x%x).\n", args->tpm2_srk, rc);
- err = GRUB_ERR_BAD_DEVICE;
- goto exit2;
-+ if (TPM_HT_IS_PERSISTENT (args->tpm2_nvindex))
++ if (TPM_HT_IS_PERSISTENT (args->tpm2_nvindex) == true)
+ {
+ err = protect_tpm2_evict (args->tpm2_nvindex);
+ if (err != GRUB_ERR_NONE)
+ goto exit;
+ }
-+ else if (TPM_HT_IS_NVINDEX (args->tpm2_nvindex))
++ else if (TPM_HT_IS_NVINDEX (args->tpm2_nvindex) == true)
+ {
+ err = protect_tpm2_nv_undefine (args->tpm2_nvindex);
+ if (err != GRUB_ERR_NONE)
@@ util/grub-protect.c: protect_tpm2_args_verify (protect_args_t *args)
+ return GRUB_ERR_BAD_ARGUMENT;
+ }
+
-+ if (!TPM_HT_IS_PERSISTENT (args->tpm2_nvindex) && TPM_HT_IS_NVINDEX
(args->tpm2_nvindex) == false)
++ if (TPM_HT_IS_PERSISTENT (args->tpm2_nvindex) == false &&
TPM_HT_IS_NVINDEX (args->tpm2_nvindex) == false)
+ {
+ fprintf (stderr, N_("--tpm2-nvindex must be a persistent or NV
index handle.\n"));
+ return GRUB_ERR_BAD_ARGUMENT;
@@ util/grub-protect.c: protect_tpm2_args_verify (protect_args_t *args)
return GRUB_ERR_BAD_ARGUMENT;
}
-@@ util/grub-protect.c: protect_tpm2_args_verify (protect_args_t *args)
- if (args->tpm2_bank == TPM_ALG_ERROR)
- args->tpm2_bank = TPM_ALG_SHA256;
-
-+
- break;
-
- case PROTECT_ACTION_REMOVE:
@@ util/grub-protect.c: protect_tpm2_args_verify (protect_args_t *args)
return GRUB_ERR_BAD_ARGUMENT;
}
@@ util/grub-protect.c: protect_tpm2_args_verify (protect_args_t *args)
+ if (args->tpm2_srk == 0 && args->tpm2_nvindex == 0)
{
- fprintf (stderr, N_("--tpm2-srk is not specified when --action is
'remove'.\n"));
-+ fprintf (stderr, N_("--tpm2-srk and --tpm2-nvindex are not specified
when --action is 'remove'.\n"));
++ fprintf (stderr, N_("missing --tpm2-srk or --tpm2-nvindex for
--action 'remove'.\n"));
return GRUB_ERR_BAD_ARGUMENT;
}
8: ebd51f2ea ! 9: 38de3037c tests/tpm2_key_protector_test: Amend the NV
index mode test
@@ Commit message
replaced with one 'grub-protect' command to simplify the test script.
Two more NV index test cases are also added to test key sealing and
- unsealing with the NV index handle, 0x1000000.
+ unsealing with the NV index handle 0x1000000.
+
+ Also, there is a minor fix to reset 'ret' to 0 when a test case fails
so
+ that the other test cases could continue.
Signed-off-by: Gary Lin <glin@suse.com>
@@ tests/tpm2_key_protector_test.in: srktests+=("ECC transient
fallback_srk")
elif [ "${ret}" -eq 1 ]; then
- echo "TPM2 [${srktests[$i]}]: FAIL"
+ echo "TPM2 [SRK][${srktests[$i]}]: FAIL"
++ ret=0
else
- echo "Unexpected failure [${srktests[$i]}]" >&2
+- echo "Unexpected failure [${srktests[$i]}]" >&2
++ echo "Unexpected failure [SRK][${srktests[$i]}]" >&2
exit ${ret}
fi
done
@@ tests/tpm2_key_protector_test.in: srktests+=("ECC transient
fallback_srk")
+ echo "TPM2 [NV Index][${nvtests[$i]}]: PASS"
+ elif [ "${ret}" -eq 1 ]; then
+ echo "TPM2 [NV Index][${nvtests[$i]}]: FAIL"
++ ret=0
+ else
+ echo "Unexpected failure [NV index][${nvtests[$i]}]" >&2
+ exit ${ret}
9: 66fde0cdb ! 10: d9bdd4bbc docs: Update NV index mode of TPM2 key protector
@@ docs/grub.texi: When/After the shim or GRUB are updated, it only
requires to run
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 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}.
-+There are two types of TPM handles supported by NV index mode: persistent
-+handle and NV index handle.
++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 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}.
++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}
@@ docs/grub.texi: When/After the shim or GRUB are updated, it only
requires to run
-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}.
++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-}
@@ docs/grub.texi: When/After the shim or GRUB are updated, it only
requires to run
+@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.
++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.
+
-+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.
++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}
@@ docs/grub.texi: When/After the shim or GRUB are updated, it only
requires to run
+@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.
++@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|policywrite|ownerwrite" \
++ -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, 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.
++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
-+If the key in the NV index handle becomes unwanted, this
@command{grub-protect}
-+command removes the specified NV index handle @kbd{0x1000000}.
++The following @command{grub-protect} command allows to remove the
specified
++NV index handle @kbd{0x1000000}.
+
+@example
+@group
--
2.43.0
- [PATCH v2 00/10] TPM2 key protector follow-up patches,
Gary Lin <=
- [PATCH v2 01/10] tpm2_key_protector: dump PCRs on policy fail, Gary Lin, 2025/01/08
- [PATCH v2 02/10] tpm2_key_protector: Add 'tpm2_dump_pcr' command, Gary Lin, 2025/01/08
- [PATCH v2 03/10] docs: Document tpm2_dump_pcr, Gary Lin, 2025/01/08
- [PATCH v2 04/10] tss2: Fix the missing authCommand, Gary Lin, 2025/01/08
- [PATCH v2 05/10] tss2: Add TPM 2.0 NV index commands, Gary Lin, 2025/01/08
- [PATCH v2 06/10] tpm2_key_protector: Unseal key from a buffer, Gary Lin, 2025/01/08
- [PATCH v2 07/10] tpm2_key_protector: Support NV index handles, Gary Lin, 2025/01/08
- [PATCH v2 08/10] util/grub-protect: Support NV index mode, Gary Lin, 2025/01/08