Review comments

Co-Authored-By: Amos Treiber <[email protected]>
sehlen-bsi · Oct 28, 2024 · 9a8bfec · 9a8bfec
1 parent 98bbd24
commit 9a8bfec
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 23 deletions.
diff --git 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
 <https://github.com/tpm2-software/tpm2-tss>` 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,18 +134,24 @@ 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 an 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:
 
 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 <tpm/session>`. 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
@@ -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           |
    |                        |                                                                         |