Merge pull request #4361 from Rohde-Schwarz/feature/tpm2_rng_in_python

TPM2: Basic bindings in FFI & Python

doc/api_ref/ffi.rst

@@ -177,6 +177,10 @@ The following enum values are defined in the FFI header:
  calling :cpp:func:`botan_hash_destroy` on a ``botan_rng_t`` object will cause
  this error.
 
+.. cpp:enumerator:: BOTAN_FFI_TPM_ERROR = -78
+
+ An error occured when performing TPM2 interactions.
+
 .. cpp:enumerator:: BOTAN_FFI_ERROR_UNKNOWN_ERROR = -100
 
  Something bad happened, but we are not sure why or how.
@@ -1337,6 +1341,61 @@ Public Key Encapsulation
 
  Destroy the operation, freeing memory
 
+
+TPM 2.0 Functions
+----------------------------------------
+
+.. versionadded:: 3.6.0
+
+.. cpp:type:: opaque* botan_tpm2_ctx_t
+
+ An opaque data type for a TPM 2.0 context object. Don't mess with it.
+
+.. cpp:type:: opaque* botan_tpm2_session_t
+
+ An opaque data type for a TPM 2.0 session object. Don't mess with it.
+
+
+.. cpp:function:: int botan_tpm2_supports_crypto_backend()
+
+ Returns 1 if the Botan-based TPM 2.0 crypto backend is available, 0 otherwise.
+
+.. cpp:function:: int botan_tpm2_ctx_init(botan_tpm2_ctx_t* ctx_out, const char* tcti_nameconf)
+
+ Initialize a TPM 2.0 context object. The TCTI name and configuration are
+ mangled into a single string separated by a colon. for instance "device:/dev/tpm0".
+
+.. cpp:function:: int botan_tpm2_ctx_init_ex(botan_tpm2_ctx_t* ctx_out, const char* tcti_name, const char* tcti_conf)
+
+ Initialize a TPM 2.0 context object. The TCTI name and configuration are
+ passed as separate strings.
+
+.. 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.
+
+.. cpp:function:: int botan_tpm2_unauthenticated_session_init(botan_tpm2_session_t* session_out, botan_tpm2_ctx_t ctx)
+
+ Initialize an unauthenticated session that can be used to encrypt the
+ communication between your application and the TPM.
+
+.. cpp:function:: int botan_tpm2_rng_init(botan_rng_t* rng_out, \
+ botan_tpm2_ctx_t ctx, \
+ botan_tpm2_session_t s1, \
+ botan_tpm2_session_t s2, \
+ botan_tpm2_session_t s3)
+
+ Initialize a random number generator that uses the TPM as a source of entropy.
+
+.. cpp:function:: int botan_tpm2_ctx_destroy(botan_tpm2_ctx_t ctx)
+
+ Destroy a TPM 2.0 context object.
+
+.. cpp:function:: int botan_tpm2_session_destroy(botan_tpm2_session_t session)
+
+ Destroy a TPM 2.0 session object.
+
 X.509 Certificates
 ----------------------------------------
 

doc/api_ref/python.rst

@@ -46,6 +46,11 @@ Random Number Generators
  no matter how many 'system' rng instances are created. Thus it is
  easy to use the RNG in a one-off way, with `botan.RandomNumberGenerator().get(32)`.
 
+ When Botan is configured with TPM 2.0 support, also 'tpm2' is allowed
+ to instantiate a TPM-backed RNG. Note that this requires passing
+ additional named arguments ``tpm2_context=`` with a ``TPM2Context`` and
+ (optionally) ``tpm2_sessions=`` with one or more ``TPM2Session`` objects.
+
  .. py:method:: get(length)
 
  Return some bytes
@@ -461,6 +466,31 @@ Public Key Operations
 
  Returns a key derived by the KDF.
 
+TPM 2.0 Bindings
+-------------------------------------
+
+.. versionadded:: 3.6.0
+
+.. py:class:: TPM2Context(tcti_nameconf = None, tcti_conf = None)
+
+ Create a TPM 2.0 context optionally with a TCTI name and configuration,
+ separated by a colon, or as separate parameters.
+
+ .. py:method:: supports_botan_crypto_backend()
+
+ Returns True if the TPM adapter can use Botan-based crypto primitives
+ to communicate with the TPM
+
+ .. py:method:: enable_botan_crypto_backend(rng)
+
+ Enables the TPM adapter to use Botan-based crypto primitives. The passed
+ RNG must not depend on the TPM itself.
+
+.. py:class:: TPM2UnauthenticatedSession(ctx)
+
+ Creates a TPM 2.0 session that is not bound to any authentication credential
+ but provides basic parameter encryption between the TPM and the application.
+
 Multiple Precision Integers (MPI)
 -------------------------------------
 .. versionadded:: 2.8.0

src/lib/ffi/ffi.cpp

@@ -67,13 +67,15 @@ int ffi_map_error_type(Botan::ErrorType err) {
  case Botan::ErrorType::IoError:
  case Botan::ErrorType::Pkcs11Error:
  case Botan::ErrorType::CommonCryptoError:
- case Botan::ErrorType::TPMError:
  case Botan::ErrorType::ZlibError:
  case Botan::ErrorType::Bzip2Error:
  case Botan::ErrorType::LzmaError:
  case Botan::ErrorType::DatabaseError:
  return BOTAN_FFI_ERROR_SYSTEM_ERROR;
 
+ case Botan::ErrorType::TPMError:
+ return BOTAN_FFI_ERROR_TPM_ERROR;
+
  case Botan::ErrorType::NotImplemented:
  return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
  case Botan::ErrorType::OutOfMemory:

src/lib/ffi/ffi.h

@@ -138,6 +138,7 @@ enum BOTAN_FFI_ERROR {
  BOTAN_FFI_ERROR_TLS_ERROR = -75,
  BOTAN_FFI_ERROR_HTTP_ERROR = -76,
  BOTAN_FFI_ERROR_ROUGHTIME_ERROR = -77,
+ BOTAN_FFI_ERROR_TPM_ERROR = -78,
 
  BOTAN_FFI_ERROR_UNKNOWN_ERROR = -100,
 };
@@ -2201,6 +2202,90 @@ BOTAN_FFI_EXPORT(3, 0)
 int botan_zfec_decode(
  size_t K, size_t N, const size_t* indexes, uint8_t* const* inputs, size_t shareSize, uint8_t** outputs);
 
+/**
+* TPM2 context
+*/
+typedef struct botan_tpm2_ctx_struct* botan_tpm2_ctx_t;
+
+/**
+* TPM2 session
+*/
+typedef struct botan_tpm2_session_struct* botan_tpm2_session_t;
+
+/**
+* Checks if Botan's TSS2 crypto backend can be used in this build
+* @returns 1 if the crypto backend can be enabled
+*/
+BOTAN_FFI_EXPORT(3, 6)
+int botan_tpm2_supports_crypto_backend();
+
+/**
+* Initialize a TPM2 context
+* @param ctx_out output TPM2 context
+* @param tcti_nameconf TCTI config (may be nullptr)
+* @return 0 on success
+*/
+BOTAN_FFI_EXPORT(3, 6) int botan_tpm2_ctx_init(botan_tpm2_ctx_t* ctx_out, const char* tcti_nameconf);
+
+/**
+* Initialize a TPM2 context
+* @param ctx_out output TPM2 context
+* @param tcti_name TCTI name (may be nullptr)
+* @param tcti_conf TCTI config (may be nullptr)
+* @return 0 on success
+*/
+BOTAN_FFI_EXPORT(3, 6)
+int botan_tpm2_ctx_init_ex(botan_tpm2_ctx_t* ctx_out, const char* tcti_name, const char* tcti_conf);
+
+/**
+* Enable Botan's TSS2 crypto backend that replaces the cryptographic functions
+* required for the communication with the TPM with implementations provided
+* by Botan instead of using TSS' defaults OpenSSL or mbedTLS.
+* Note that the provided @p rng should not be dependent on the TPM and the
+* caller must ensure that it remains usable for the lifetime of the @p ctx.
+* @param ctx TPM2 context
+* @param rng random number generator to be used by the crypto backend
+*/
+BOTAN_FFI_EXPORT(3, 6)
+int botan_tpm2_ctx_enable_crypto_backend(botan_tpm2_ctx_t ctx, botan_rng_t rng);
+
+/**
+* Frees all resouces of a TPM2 context
+* @param ctx TPM2 context
+* @return 0 on success
+*/
+BOTAN_FFI_EXPORT(3, 6) int botan_tpm2_ctx_destroy(botan_tpm2_ctx_t ctx);
+
+/**
+* Initialize a random number generator object via TPM2
+* @param rng_out rng object to create
+* @param ctx TPM2 context
+* @param s1 the first session to use (optional, may be nullptr)
+* @param s2 the second session to use (optional, may be nullptr)
+* @param s3 the third session to use (optional, may be nullptr)
+*/
+BOTAN_FFI_EXPORT(3, 6)
+int botan_tpm2_rng_init(botan_rng_t* rng_out,
+ botan_tpm2_ctx_t ctx,
+ botan_tpm2_session_t s1,
+ botan_tpm2_session_t s2,
+ botan_tpm2_session_t s3);
+
+/**
+* Create an unauthenticated session for use with TPM2
+* @param session_out the session object to create
+* @param ctx TPM2 context
+*/
+BOTAN_FFI_EXPORT(3, 6)
+int botan_tpm2_unauthenticated_session_init(botan_tpm2_session_t* session_out, botan_tpm2_ctx_t ctx);
+
+/**
+* Create an unauthenticated session for use with TPM2
+* @param session the session object to destroy
+*/
+BOTAN_FFI_EXPORT(3, 6)
+int botan_tpm2_session_destroy(botan_tpm2_session_t session);
+
 #ifdef __cplusplus
 }
 #endif