[PATCH v3 00/10] TPM2 key protector follow-up patches

[Gary Lin]

git: https://github.com/lcp/grub2/tree/tpm2-follow-up-v3

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.

v3:
- Amending the function names to make them more comprehensive
- Fixing a few more typos and the indentations 
- Improving the document

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                                | 202 ++++++++--
 .../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, 1113 insertions(+), 232 deletions(-)

Range-diff against v2:
 -:  --------- >  1:  cf2be1c66 tpm2_key_protector: dump PCRs on policy fail
 -:  --------- >  2:  052089a84 tpm2_key_protector: Add 'tpm2_dump_pcr' command
 -:  --------- >  3:  01f27df8a docs: Document tpm2_dump_pcr
 -:  --------- >  4:  242483c87 tss2: Fix the missing authCommand
 -:  --------- >  5:  3f0aca8af tss2: Add TPM 2.0 NV index commands
 1:  0e7b6fe17 !  6:  733b8c507 tpm2_key_protector: Unseal key from a buffer
    @@ grub-core/commands/tpm2_key_protector/module.c: tpm2_protector_dump_pcr 
(const T
      static grub_err_t
     -tpm2_protector_srk_recover (const tpm2_protector_context_t *ctx,
     -                      grub_uint8_t **key, grub_size_t *key_size)
    -+tpm2_protector_unseal_buffer (const tpm2_protector_context_t *ctx,
    -+                        void *buffer, grub_size_t buf_size,
    -+                        grub_uint8_t **key, grub_size_t *key_size)
    ++tpm2_protector_key_from_buffer (const tpm2_protector_context_t *ctx,
    ++                          void *buffer, grub_size_t buf_size,
    ++                          grub_uint8_t **key, grub_size_t *key_size)
      {
        tpm2_sealed_key_t sealed_key = {0};
     -  void *file_bytes = NULL;
    @@ grub-core/commands/tpm2_key_protector/module.c: 
tpm2_protector_srk_recover (cons
     +  if (err != GRUB_ERR_NONE)
     +    return err;
     +
    -+  err = tpm2_protector_unseal_buffer (ctx, file_bytes, file_size, key, 
key_size);
    ++  err = tpm2_protector_key_from_buffer (ctx, file_bytes, file_size, key, 
key_size);
     +
        grub_free (file_bytes);
        return err;
 2:  1afe60a7e !  7:  b92cfb4b0 tpm2_key_protector: Support NV index handles
    @@ grub-core/commands/tpm2_key_protector/module.c: 
tpm2_protector_srk_recover (cons
      static grub_err_t
     -tpm2_protector_nv_recover (const tpm2_protector_context_t *ctx,
     -                     grub_uint8_t **key, grub_size_t *key_size)
    -+tpm2_protector_unseal_persistent (const tpm2_protector_context_t *ctx, 
TPM_HANDLE_t sealed_handle,
    -+                            grub_uint8_t **key, grub_size_t *key_size)
    ++tpm2_protector_load_persistent (const tpm2_protector_context_t *ctx, 
TPM_HANDLE_t sealed_handle,
    ++                          grub_uint8_t **key, grub_size_t *key_size)
      {
     -  TPM_HANDLE_t sealed_handle = ctx->nv;
        tpm2key_policy_t policy_seq = NULL;
    @@ grub-core/commands/tpm2_key_protector/module.c: 
tpm2_protector_nv_recover (const
      }
      
     +static grub_err_t
    -+tpm2_protector_unseal_nvindex (const tpm2_protector_context_t *ctx, 
TPM_HANDLE_t nvindex,
    -+                         grub_uint8_t **key, grub_size_t *key_size)
    ++tpm2_protector_key_from_nvindex (const tpm2_protector_context_t *ctx, 
TPM_HANDLE_t nvindex,
    ++                           grub_uint8_t **key, grub_size_t *key_size)
     +{
     +  TPMS_AUTH_COMMAND_t authCmd = {0};
     +  TPM2B_NV_PUBLIC_t nv_public;
    @@ grub-core/commands/tpm2_key_protector/module.c: 
tpm2_protector_nv_recover (const
     +  if (rc != TPM_RC_SUCCESS)
     +    return grub_error (GRUB_ERR_BAD_ARGUMENT, "failed to read data from 
0x%x (TPM2_NV_Read: 0x%x)", nvindex, rc);
     +
    -+  return tpm2_protector_unseal_buffer (ctx, data.buffer, data_size, key, 
key_size);
    ++  return tpm2_protector_key_from_buffer (ctx, data.buffer, data_size, 
key, key_size);
     +}
     +
     +static grub_err_t
    @@ grub-core/commands/tpm2_key_protector/module.c: 
tpm2_protector_nv_recover (const
     +  grub_err_t err;
     +
     +  if (TPM_HT_IS_PERSISTENT (ctx->nv) == true)
    -+    err = tpm2_protector_unseal_persistent (ctx, ctx->nv, key, key_size);
    ++    err = tpm2_protector_load_persistent (ctx, ctx->nv, key, key_size);
     +  else if (TPM_HT_IS_NVINDEX (ctx->nv) == true)
    -+    err = tpm2_protector_unseal_nvindex (ctx, ctx->nv, key, key_size);
    ++    err = tpm2_protector_key_from_nvindex (ctx, ctx->nv, key, key_size);
     +  else
     +    err = GRUB_ERR_BAD_ARGUMENT;
     +
 3:  e6e7982d5 !  8:  be4d93cb2 util/grub-protect: Support NV index mode
    @@ Commit message
               --tpm2-nvindex=0x1000000
     
         Signed-off-by: Gary Lin <glin@suse.com>
    +    Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
     
      ## util/grub-protect.c ##
     @@ util/grub-protect.c: typedef enum protect_opt
    @@ util/grub-protect.c: protect_tpm2_add (protect_args_t *args)
     +  if (rc != TPM_RC_SUCCESS)
     +    {
     +      fprintf (stderr, "Handle 0x%x not found.\n", handle);
    -+      return GRUB_ERR_BAD_ARGUMENT;;
    ++      return GRUB_ERR_BAD_ARGUMENT;
     +    }
     +
     +  /* Undefine the nvindex handle */
 4:  38de3037c !  9:  15bce58ed tests/tpm2_key_protector_test: Amend the NV 
index mode test
    @@ Commit message
         that the other test cases could continue.
     
         Signed-off-by: Gary Lin <glin@suse.com>
    +    Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
     
      ## tests/tpm2_key_protector_test.in ##
     @@ tests/tpm2_key_protector_test.in: EOF
    @@ tests/tpm2_key_protector_test.in: srktests+=("ECC transient 
fallback_srk")
          tpm2_seal_unseal ${srktests[$i]} || ret=$?
          if [ "${ret}" -eq 0 ]; then
     -        echo "TPM2 [${srktests[$i]}]: PASS"
    -+        echo "TPM2 [SRK][${srktests[$i]}]: PASS"
    ++  echo "TPM2 [SRK][${srktests[$i]}]: PASS"
          elif [ "${ret}" -eq 1 ]; then
     -        echo "TPM2 [${srktests[$i]}]: FAIL"
    -+        echo "TPM2 [SRK][${srktests[$i]}]: FAIL"
    ++  echo "TPM2 [SRK][${srktests[$i]}]: FAIL"
     +  ret=0
          else
     -  echo "Unexpected failure [${srktests[$i]}]" >&2
 5:  d9bdd4bbc ! 10:  b782d0bdb 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
     -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
    ++@command{grub-protect} command removes the specified persistent handle
     +@kbd{0x81000000}.
      
      @example
    @@ docs/grub.texi: When/After the shim or GRUB are updated, it only 
requires to run
     +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}
    ++The following @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.
      
    @@ 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 using the following
    ++@file{sealed.tpm}, into a specific NV index handle using the following
     +tpm2-tools (@url{https://github.com/tpm2-software/tpm2-tools}) commands.
     +
     +@example
    @@ docs/grub.texi: grub> @kbd{tpm2_key_protector_init -T 
(hd0,gpt1)/efi/grub/sealed
      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}.
    ++Besides writing the PCR-sealed key into a file, @command{grub-protect} can
    ++write the sealed key into TPM non-volatile memory. Here is the
    ++@command{grub-protect} command to write the sealed key into the NV index
    ++handle @samp{0x1000000}.
     +
     +@example
     +@group
    @@ docs/grub.texi: grub> @kbd{tpm2_key_protector_init -T 
(hd0,gpt1)/efi/grub/sealed
     +@end group
     +@end example
     +
    -+Later, GRUB can fetch and unseal the key from @samp{0x1000000}.
    ++Later, GRUB can fetch the key from @samp{0x1000000}.
     +
     +@example
     +grub> @kbd{tpm2_key_protector_init --mode=nv --nvindex=0x1000000}
    @@ docs/grub.texi: grub> @kbd{tpm2_key_protector_init -T 
(hd0,gpt1)/efi/grub/sealed
     +handles and NV index handles, and @command{tpm2_getcap} can be used to
     +check the existing handles.
     +
    -+To get the existing persistent handles:
    ++To display the list of existing persistent handles:
     +
     +@example
     +@group
    @@ docs/grub.texi: grub> @kbd{tpm2_key_protector_init -T 
(hd0,gpt1)/efi/grub/sealed
     +@end group
     +@end example
     +
    -+Similarly, to get the existing nv-index handles:
    ++Similarly, to display the list of existing NV index handles:
     +
     +@example
     +@group
    @@ docs/grub.texi: grub> @kbd{tpm2_key_protector_init -T 
(hd0,gpt1)/efi/grub/sealed
     +@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}
    ++If the sealed key at an NV index 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 NV index @samp{0x1000000}:
     +
     +@example
     +@group
-- 
2.43.0