Documentation for supporting externally provided ESYS_CONTEXT

Co-Authored-By: René Meusel <[email protected]>

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
 ----------------------------------------
 

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<Context> 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<const uint8_t> auth_value, std::optional<TPM2_HANDLE> 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
 ~~~~~~~~~~~~~~~