diff --git a/doc/api_ref/ffi.rst b/doc/api_ref/ffi.rst index 2ee2d0511f..b811b12f7d 100644 --- a/doc/api_ref/ffi.rst +++ b/doc/api_ref/ffi.rst @@ -1367,6 +1367,12 @@ TPM 2.0 Functions An opaque data type for a TPM 2.0 session object. Don't mess with it. +.. cpp:type:: opaque* botan_tpm2_crypto_backend_state_t + + An opaque data type to hold the TPM 2.0 crypto backend state when registering + the botan-based crypto backend on a bare ESYS_CONTEXT. When the TPM 2.0 + context is managed via Botan botan_tpm2_ctx_t, this state object is maintained + internally. .. cpp:function:: int botan_tpm2_supports_crypto_backend() @@ -1382,10 +1388,30 @@ TPM 2.0 Functions Initialize a TPM 2.0 context object. The TCTI name and configuration are passed as separate strings. +.. cpp:function:: int botan_tpm2_ctx_from_esys(botan_tpm2_ctx_t* ctx_out, ESYS_CONTEXT* esys_ctx) + + Initialize a TPM 2.0 context object from a pre-existing ``ESYS_CONTEXT`` that + is managed by the application. Destroying this object _will not_ finalize the + ``ESYS_CONTEXT``, this responsibility remains with the application. + .. cpp:function:: int botan_tpm2_ctx_enable_crypto_backend(botan_tpm2_ctx_t ctx, botan_rng_t rng) Enable the Botan-based TPM 2.0 crypto backend. Note that the random number generator passed to this function must not be dependent on the TPM itself. + This should be used when the ``ESYS_CONTEXT`` is managed by the TPM 2.0 + wrapper provided by Botan (i.e. the application did not explicitly instantiate + the ``ESYS_CONTEXT`` itself). + +.. cpp:function:: int botan_tpm2_enable_crypto_backend(botan_tpm2_crypto_backend_state_t* cbs_out, \ + ESYS_CONTEXT* esys_ctx, \ + botan_rng_t rng) + + Enable the Botan-based TPM 2.0 crypto backend on a pre-existing ``ESYS_CONTEXT`` + that is managed by the application. Note that the random number generator + passed to this function must not be dependent on the TPM itself. + The crypto backend has to keep internal state. The application is responsible + to keep this state alive and destroy it after the ``ESYS_CONTEXT`` is no longer + used. .. cpp:function:: int botan_tpm2_unauthenticated_session_init(botan_tpm2_session_t* session_out, botan_tpm2_ctx_t ctx) @@ -1408,6 +1434,14 @@ TPM 2.0 Functions Destroy a TPM 2.0 session object. +.. cpp:function:: int botan_tpm2_crypto_backend_state_destroy(botan_tpm2_crypto_backend_state_t cbs) + + Destroy a TPM 2.0 crypto backend state. This is required when registering the + botan-based crypto backend on an ESYS_CONTEXT managed by the application + using botan_tpm2_enable_crypto_backend. When the ESYS_CONTEXT is managed in + the botan wrapper, and botan_tpm2_ctx_enable_crypto_backend was used, this + state is managed within the library and does not need to be cleaned up. + X.509 Certificates ---------------------------------------- diff --git a/doc/api_ref/tpm.rst b/doc/api_ref/tpm.rst index 113273549c..ca7a9cc50e 100644 --- a/doc/api_ref/tpm.rst +++ b/doc/api_ref/tpm.rst @@ -53,6 +53,14 @@ persisting and evicting keys into the TPM's NVRAM. TCTI. Both values may by empty, in which case the TPM-TSS2 will try to determine them from default values. + .. cpp:function:: std::shared_ptr create(ESYS_CONTEXT* ctx) + + Create a TPM2 context from an already set up TPM2-TSS ESYS_CONTEXT* + to enable usage of Botan's TPM2 functionalities via an outside + ESYS Context. + If the Botan TPM2 Context was created this way, the destructor will + not finalize the underlying ESYS_CONTEXT. + .. cpp:function:: TPM2_HANDLE persist(TPM2::PrivateKey& key, const SessionBundle& sessions, std::span auth_value, std::optional persistent_handle) Persists the given ``key`` in the TPM's NVRAM. The returned handle can be @@ -250,6 +258,14 @@ Once a ``Context`` is created, the Botan-based crypto backend may be enabled for it via the ``Context::use_botan_crypto_backend`` method. This will only succeed if the method ``Context::supports_botan_crypto_backend`` returns true. +Alternatively, if one just wants to utilize the backend in a TPM2-TSS ESAPI +application without using Botan's wrappers, free-standing functions are provided +in ``tpm2_crypto_backend.h``. The ``use_botan_crypto_backend`` works similar to +the ``Context::use_botan_crypto_backend`` method but is given an ``ESYS_CONTEXT*`` +and returns a ``TPM2::CryptoCallbackState`` that needs to stay alive as long +as the crypto backend is used. This will only succeed if the method +``supports_botan_crypto_backend`` returns true. + TPM 2.0 Example ~~~~~~~~~~~~~~~