Botan::TPM2::Session Class Reference

#include <tpm2_session.h>

Public Member Functions
SessionAttributes	attributes () const
detail::SessionHandle	handle ()
	Session (std::shared_ptr< Context > ctx, ESYS_TR session_handle)
void	set_attributes (SessionAttributes attributes)
secure_vector< uint8_t >	tpm_nonce () const

Static Public Member Functions
static std::shared_ptr< Session >	authenticated_session (const std::shared_ptr< Context > &ctx, const TPM2::PrivateKey &tpm_key, std::string_view sym_algo="CFB(AES-256)", std::string_view hash_algo="SHA-256")
static std::shared_ptr< Session >	unauthenticated_session (const std::shared_ptr< Context > &ctx, std::string_view sym_algo="CFB(AES-256)", std::string_view hash_algo="SHA-256")

Friends
class	detail::SessionHandle

Detailed Description

Definition at line 86 of file tpm2_session.h.

Constructor & Destructor Documentation

Session()

Botan::TPM2::Session::Session ( std::shared_ptr< Context > ctx, ESYS_TR session_handle )

inline

Create a session object from a user-provided transient handle.

Use this to wrap an externally created session handle into a Botan::TPM2::Session instance to use it with the Botan::TPM2 library.

Note that this will take ownership of the ESYS_TR handle and will release it when the object is destroyed.

Parameters

ctx	the TPM context to use
session_handle	the transient handle to wrap

Definition at line 139 of file tpm2_session.h.

: m_session(std::move(ctx), session_handle) {}

Referenced by authenticated_session(), and unauthenticated_session().

Member Function Documentation

attributes()

SessionAttributes Botan::TPM2::Session::attributes

(

)

const

Definition at line 107 of file tpm2_session.cpp.

                                            {
   TPMA_SESSION attrs;
   check_rc("Esys_TRSess_GetAttributes",
            Esys_TRSess_GetAttributes(*m_session.context(), m_session.transient_handle(), &attrs));
   return SessionAttributes::read(attrs);
}

References Botan::TPM2::check_rc(), Botan::TPM2::Object::context(), Botan::TPM2::SessionAttributes::read(), and Botan::TPM2::Object::transient_handle().

Referenced by set_attributes().

authenticated_session()

std::shared_ptr< Session > Botan::TPM2::Session::authenticated_session ( const std::shared_ptr< Context > & ctx, const TPM2::PrivateKey & tpm_key, std::string_view sym_algo = "CFB(AES-256)", std::string_view hash_algo = "SHA-256" )

static

Instantiate a session based on a salt encrypted for tpm_key. This allows for the encryption of sensitive parameters passed to and from the TPM. The application's random salt is generated automatically (via the software RNG in the TSS2's crypto backend).

Such a session is protected against man-in-the-middle attacks with access to the data channel between the application and the TPM, under the assumption that the tpm_key is not compromised.

Parameters

ctx	the TPM context
tpm_key	the key to use for session establishment
sym_algo	the symmetric algorithm used for parameter encryption
hash_algo	the hash algorithm in the HMAC used for authentication

Definition at line 72 of file tpm2_session.cpp.

                                                                                  {
   Object session(ctx);
   const auto auth_sym = get_tpm2_sym_cipher_spec(sym_algo);
   const auto auth_hash_algo = get_tpm2_hash_type(hash_algo);
 
   BOTAN_ASSERT_NONNULL(ctx);
 
   check_rc("Esys_StartSession",
            Esys_StartAuthSession(*ctx,
                                  tpm_key.handles().transient_handle(),
                                  tpm_key.handles().transient_handle(),
                                  ESYS_TR_NONE,
                                  ESYS_TR_NONE,
                                  ESYS_TR_NONE,
                                  nullptr /*NonceCaller generated automatically*/,
                                  TPM2_SE_HMAC,
                                  &auth_sym,
                                  auth_hash_algo,
                                  out_transient_handle(session)));
 
   return std::shared_ptr<Session>(new Session(std::move(session),
                                               {
                                                  .continue_session = true,
                                                  .decrypt = true,
                                                  .encrypt = true,
                                               }));
}

References BOTAN_ASSERT_NONNULL, Botan::TPM2::check_rc(), Botan::TPM2::get_tpm2_hash_type(), Botan::TPM2::get_tpm2_sym_cipher_spec(), Botan::TPM2::PrivateKey::handles(), Botan::TPM2::out_transient_handle(), Session(), and Botan::TPM2::Object::transient_handle().

handle()

detail::SessionHandle Botan::TPM2::Session::handle ( )

inlinenodiscard

Definition at line 141 of file tpm2_session.h.

{ return *this; }

set_attributes()

void Botan::TPM2::Session::set_attributes

(

SessionAttributes

attributes

)

Definition at line 114 of file tpm2_session.cpp.

                                                         {
   check_rc("Esys_TRSess_SetAttributes",
            Esys_TRSess_SetAttributes(
               *m_session.context(), m_session.transient_handle(), SessionAttributes::render(attributes), 0xFF));
}

References attributes(), Botan::TPM2::check_rc(), Botan::TPM2::Object::context(), Botan::TPM2::SessionAttributes::render(), and Botan::TPM2::Object::transient_handle().

tpm_nonce()

secure_vector< uint8_t > Botan::TPM2::Session::tpm_nonce

(

)

const

Definition at line 120 of file tpm2_session.cpp.

                                                {
   unique_esys_ptr<TPM2B_NONCE> nonce;
   check_rc("Esys_TRSess_GetNonceTPM",
            Esys_TRSess_GetNonceTPM(*m_session.context(), m_session.transient_handle(), out_ptr(nonce)));
   return copy_into<secure_vector<uint8_t>>(*nonce);
}

References Botan::TPM2::check_rc(), Botan::TPM2::Object::context(), Botan::TPM2::copy_into(), Botan::out_ptr(), and Botan::TPM2::Object::transient_handle().

unauthenticated_session()

std::shared_ptr< Session > Botan::TPM2::Session::unauthenticated_session ( const std::shared_ptr< Context > & ctx, std::string_view sym_algo = "CFB(AES-256)", std::string_view hash_algo = "SHA-256" )

static

Instantiate an unauthenticated session that allows for the encryption of sensitive parameters passed to and from the TPM. The application's random salt is generated automatically (via the software RNG in the TSS2's crypto backend).

Note that such a session is not protected against man-in-the-middle attacks with access to the data channel between the application and the TPM.

Parameters

ctx	the TPM context
sym_algo	the symmetric algorithm used for parameter encryption
hash_algo	the hash algorithm in the HMAC used for authentication

Definition at line 42 of file tpm2_session.cpp.

                                                                                    {
   Object session(ctx);
   const auto auth_sym = get_tpm2_sym_cipher_spec(sym_algo);
   const auto auth_hash_algo = get_tpm2_hash_type(hash_algo);
 
   BOTAN_ASSERT_NONNULL(ctx);
 
   check_rc("Esys_StartSession",
            Esys_StartAuthSession(*ctx,
                                  ESYS_TR_NONE,
                                  ESYS_TR_NONE,
                                  ESYS_TR_NONE,
                                  ESYS_TR_NONE,
                                  ESYS_TR_NONE,
                                  nullptr /*NonceCaller generated automatically*/,
                                  TPM2_SE_HMAC,
                                  &auth_sym,
                                  auth_hash_algo,
                                  out_transient_handle(session)));
 
   return std::shared_ptr<Session>(new Session(std::move(session),
                                               {
                                                  .continue_session = true,
                                                  .decrypt = true,
                                                  .encrypt = true,
                                               }));
}

References BOTAN_ASSERT_NONNULL, Botan::TPM2::check_rc(), Botan::TPM2::get_tpm2_hash_type(), Botan::TPM2::get_tpm2_sym_cipher_spec(), Botan::TPM2::out_transient_handle(), and Session().

Referenced by botan_tpm2_unauthenticated_session_init().

Friends And Related Symbol Documentation

detail::SessionHandle

friend class detail::SessionHandle

friend

Definition at line 149 of file tpm2_session.h.

---

The documentation for this class was generated from the following files:

• src/lib/prov/tpm2/tpm2_session.h
• src/lib/prov/tpm2/tpm2_session.cpp