From f982118ddaaa48278c2c73f352a6babdee922215 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Mon, 28 Oct 2024 12:52:17 +0100 Subject: [PATCH] Review comments Co-Authored-By: Amos Treiber --- docs/cryptodoc/src/10_tpm.rst | 46 ++++++++++++++++++++++------------- docs/testspec/src/18_tpm.rst | 11 ++++----- 2 files changed, 34 insertions(+), 23 deletions(-) diff --git a/docs/cryptodoc/src/10_tpm.rst b/docs/cryptodoc/src/10_tpm.rst index c78621df..f88fad26 100644 --- a/docs/cryptodoc/src/10_tpm.rst +++ b/docs/cryptodoc/src/10_tpm.rst @@ -5,15 +5,15 @@ Trusted Platform Module Botan provides a helper to use asymmetric key material hosted by a TPM. Once initialized, such keys can be used in the same way as any other key in Botan. -This wrapper relies on `the TPM2-TSS library +There are independent wrappers for TPM 1.2 and TPM 2.0. The TPM 1.2 wrapper is +deprecated and will be removed in a future release. This chapter only covers +the TPM 2.0 wrapper and specifies the calls made to the ESAPI by Botan. + +The TPM 2.0 support in Botan relies on `the TPM2-TSS library ` as specified by the Trusted Computing Group. More specifically, it uses the Enhanced System API (ESAPI) of the TPM2-TSS library. -There are independent wrappers for TPM 1.2 and TPM 2.0. The TPM 1.2 wrapper is -deprecated and will be removed in a future release. This chapter only covers -the TPM 2.0 wrapper. - Currently, this TPM wrapper is limited to basic functionality. Particularly, it does not support: @@ -65,6 +65,7 @@ capabilities and fundamental key management operations. - If no handle was provided, ``handle = next_free_handle()`` (via ``Esys_GetCapability``) - ``Esys_EvictControl(ctx, key.transient_handle(), sessions, out(handle))`` - ``Esys_TR_SetAuth(ctx, key.transient_handle(), auth_value)`` + - ``key.persistent_handle() = Esys_TR_GetTpmHandle(ctx, key.transient_handle())`` - Return ``handle`` .. admonition:: TPM2::Context::evict() @@ -76,7 +77,7 @@ capabilities and fundamental key management operations. **Steps:** - - ``Esys_EvictControl(ctx, handle, sessions)`` + - ``Esys_EvictControl(ctx, key.transient_handle(), sessions)`` .. _tpm/session: @@ -111,6 +112,11 @@ Botan's TPM session wrapper is implemented in :srcref:`[src/lib/prov]/tpm2/tpm2_ 1. ``m_session_handle = Esys_StartAuthSession(ctx, TPM2_SE_HMAC, sym_algo, hash_algo)`` + **Notes:** + + - This does not provide confidentiality against an attacker with access to the + communication channel between the application and the TPM. + .. admonition:: TPM2::Session::authenticated_session() **Input:** @@ -128,6 +134,12 @@ Botan's TPM session wrapper is implemented in :srcref:`[src/lib/prov]/tpm2/tpm2_ - ``m_session_handle = Esys_StartAuthSession(ctx, TPM2_SE_HMAC, key, sym_algo, hash_algo)`` + **Notes:** + + - Assuming the public part of ``key`` is trustworthy due to external or + organizational means, this provides confidentiality against an attacker + with access to the communication channel between the application and the + TPM. .. _tpm/crypto_backend: @@ -135,11 +147,11 @@ Crypto Backend -------------- The communication between the application and the TPM can (and should be) -encrypted. The protocol used for this communication is specified by the Trusted -Computing Group and implemented by the TPM2-TSS library. Starting with version -4.0 the TPM2-TSS library provides ``Esys_SetCryptoCallbacks``, that allows -overriding the cryptographic primitives used for this encryption by the -application at runtime. +encrypted using :ref:`TPM2 Sessions `. The protocol used for this +communication is specified by the Trusted Computing Group and implemented by the +TPM2-TSS library. Starting with version 4.0 the TPM2-TSS library provides +``Esys_SetCryptoCallbacks``, that allows overriding the cryptographic primitives +used for this encryption by the application at runtime. Botan provides such a "crypto backend" to form a self-contained TPM wrapper that does not depend on any other cryptographic library. @@ -197,8 +209,8 @@ overview of the functionality without distinguishing between RSA and ECC keys. **Steps:** - 1. Create a ``TPM2B_SENSITIVE_CREATE`` structure with ``auth_value`` - 2. Create a ``TPMT_PUBLIC`` key template that does not restrict the key for any specific use case + 1. Create a ``TPM2B_SENSITIVE_CREATE`` structure ``sensitive_data`` with ``auth_value`` + 2. Create a ``TPMT_PUBLIC`` key template ``template`` with ``key_spec`` that does not restrict the key for any specific use case 3. ``pub_info, priv_bytes = Esys_CreateLoaded(ctx, parent_key, sessions, sensitive_data, template)`` 4. Return a ``TPM2::PrivateKey`` as a wrapper object @@ -214,7 +226,7 @@ overview of the functionality without distinguishing between RSA and ECC keys. - auth_value: The TPM authorization value for the key - parent_key: The parent key under which the new key shall be created - public_blob: The public part of the key - - private_blob: The private part of the key + - private_blob: The private part of the key (previously encrypted by the TPM) - sessions: The TPM session bundle **Output:** @@ -276,14 +288,14 @@ here. 1. Calculate the digest of ``data``: - 1. If ``key`` is *not marked* as "restricted", use Botan's software implementation of ``hash_name`` + 1. If ``key`` is *not marked* as "restricted", use Botan's software implementation of ``hash_name`` and create a dummy ``validation_ticket`` 2. Otherwise, use the TPM to calculate the digest (see :srcref:`[src/lib/prov/tpm2]/tpm2_hash.cpp`): - 1. ``hash_obj = Esys_HashSequenceStart(ctx, sessions, hash_type)`` + 1. ``hash_obj = Esys_HashSequenceStart(ctx, sessions, hash_name)`` 2. ``Esys_SequenceUpdate(ctx, hash_obj, sessions, data)`` 3. ``(digest, validation_ticket) = Esys_SequenceComplete(ctx, hash_obj, sessions)`` - 2. ``sig = Esys_Sign(ctx, key, sessions, digest, validation_ticket?)`` (see :srcref:`[src/lib/prov/tpm2]/tpm2_pkops.cpp:51|sign`) + 2. ``sig = Esys_Sign(ctx, key, sessions, digest, validation_ticket)`` (see :srcref:`[src/lib/prov/tpm2]/tpm2_pkops.cpp:51|sign`) 3. Marshal the signature into its canonical byte encoding 4. Return the signature diff --git a/docs/testspec/src/18_tpm.rst b/docs/testspec/src/18_tpm.rst index 07b07807..67cb15f1 100644 --- a/docs/testspec/src/18_tpm.rst +++ b/docs/testspec/src/18_tpm.rst @@ -190,7 +190,7 @@ Random Number Generator | | | | | #. Create a ``TPM2::RandomNumberGenerator`` object | | | | - | | #. Create a random buffer of 8 bytes and pass 30 bytes of entropy | + | | #. Create a random buffer of 9 bytes and pass 30 bytes of entropy | | | | | | #. Create a random buffer of 66 bytes and pass 64 bytes of entropy | | | | @@ -258,7 +258,7 @@ RSA | | #. Instantiate the passed persistent RSA key pair using an incorrect | | | authentication value | | | | - | | #. Check that the signature creatino fail with a "TPM2 Error" | + | | #. Check that the signature creation fails with a "TPM2 Error" | +------------------------+-------------------------------------------------------------------------+ .. table:: @@ -281,7 +281,7 @@ RSA +------------------------+-------------------------------------------------------------------------+ | **Steps:** | #. Create a TPM2 context and an unauthenticated session | | | | - | | #. Instantiate the passed persistent RSA key pair using an incorrect | + | | #. Instantiate the passed persistent RSA key pair using the correct | | | authentication value | | | | | | #. Encrypt the plaintext message "feedc0debaadcafe" using RSA-OAEP | @@ -416,7 +416,7 @@ ECDSA | | #. Instantiate the passed persistent ECDSA key pair using an incorrect | | | authentication value | | | | - | | #. Check that the signature creatino fail with a "TPM2 Error" | + | | #. Check that the signature creation fails with a "TPM2 Error" | +------------------------+-------------------------------------------------------------------------+ @@ -440,8 +440,7 @@ ECDSA | **Steps:** | #. Create a TPM2 context and an authenticated session via the Storage | | | Root Key | | | | - | | #. Create a transient unrestricted key with the auth_value "secret" and | - | | the elliptic curve "secp521r1" | + | | #. Create a transient unrestricted key with the auth_value "secret" | | | | | | #. Sign a random message using the new private key on the TPM | | | |