#include <tls_session.h>

Inheritance diagram for Botan::TLS::Session:

Public Member Functions
Ciphersuite	ciphersuite () const
uint16_t	ciphersuite_code () const
secure_vector< uint8_t >	DER_encode () const
uint16_t	dtls_srtp_profile () const
std::vector< uint8_t >	encrypt (const SymmetricKey &key, RandomNumberGenerator &rng) const
secure_vector< uint8_t >	extract_master_secret ()
std::chrono::seconds	lifetime_hint () const
const secure_vector< uint8_t > &	master_secret () const
uint32_t	max_early_data_bytes () const
const std::vector< X509_Certificate > &	peer_certs () const
std::shared_ptr< const Public_Key >	peer_raw_public_key () const
std::string	PEM_encode () const
const Server_Information &	server_info () const
	Session (const secure_vector< uint8_t > &master_secret, Protocol_Version version, uint16_t ciphersuite, Connection_Side side, bool supports_extended_master_secret, bool supports_encrypt_then_mac, const std::vector< X509_Certificate > &peer_certs, const Server_Information &server_info, uint16_t srtp_profile, std::chrono::system_clock::time_point current_timestamp, std::chrono::seconds lifetime_hint=std::chrono::seconds::max())
	Session (const secure_vector< uint8_t > &session_psk, const std::optional< uint32_t > &max_early_data_bytes, uint32_t ticket_age_add, std::chrono::seconds lifetime_hint, Protocol_Version version, uint16_t ciphersuite, Connection_Side side, const std::vector< X509_Certificate > &peer_certs, std::shared_ptr< const Public_Key > peer_raw_public_key, const Server_Information &server_info, std::chrono::system_clock::time_point current_timestamp)
BOTAN_FUTURE_EXPLICIT	Session (std::span< const uint8_t > ber_data)
	Session (std::string_view pem)
uint32_t	session_age_add () const
Connection_Side	side () const
std::chrono::system_clock::time_point	start_time () const
bool	supports_early_data () const
bool	supports_encrypt_then_mac () const
bool	supports_extended_master_secret () const
Protocol_Version	version () const

Static Public Member Functions
static Session	decrypt (const uint8_t ctext[], size_t ctext_size, const SymmetricKey &key)
static Session	decrypt (std::span< const uint8_t > ctext, const SymmetricKey &key)

Protected Attributes
uint16_t	m_ciphersuite = 0
Connection_Side	m_connection_side = Connection_Side::Client
bool	m_encrypt_then_mac = false
bool	m_extended_master_secret = false
std::vector< X509_Certificate >	m_peer_certs
std::shared_ptr< const Public_Key >	m_peer_raw_public_key
Server_Information	m_server_info
uint16_t	m_srtp_profile = 0
std::chrono::system_clock::time_point	m_start_time
Protocol_Version	m_version

Detailed Description

Represents a session's negotiated features along with all resumption information to re-establish a TLS connection later on.

Definition at line 238 of file tls_session.h.

Constructor & Destructor Documentation

◆ Session() [1/4]

Botan::TLS::Session::Session	(	const secure_vector< uint8_t > &	master_secret,
		Protocol_Version	version,
		uint16_t	ciphersuite,
		Connection_Side	side,
		bool	supports_extended_master_secret,
		bool	supports_encrypt_then_mac,
		const std::vector< X509_Certificate > &	peer_certs,
		const Server_Information &	server_info,
		uint16_t	srtp_profile,
		std::chrono::system_clock::time_point	current_timestamp,
		std::chrono::seconds	lifetime_hint = std::chrono::seconds::max() )

New TLS 1.2 session (sets session start time)

Definition at line 239 of file tls_session.cpp.

                                                 :
      Session_Base(current_timestamp,
                   version,
                   ciphersuite,
                   side,
                   srtp_profile,
                   extended_master_secret,
                   encrypt_then_mac,
                   certs,
                   nullptr,  // RFC 7250 (raw public keys) is NYI for TLS 1.2
                   server_info),
      m_master_secret(master_secret),
      m_early_data_allowed(false),
      m_max_early_data_bytes(0),
      m_ticket_age_add(0),
      m_lifetime_hint(lifetime_hint) {
   BOTAN_ARG_CHECK(version.is_pre_tls_13(), "Instantiated a TLS 1.2 session object with a TLS version newer than 1.2");
}

References BOTAN_ARG_CHECK, Botan::TLS::Session_Base::ciphersuite(), lifetime_hint(), master_secret(), Botan::TLS::Session_Base::server_info(), Botan::TLS::Session_Base::Session_Base(), Botan::TLS::Session_Base::side(), and Botan::TLS::Session_Base::version().

Referenced by decrypt(), decrypt(), and Session().

◆ Session() [2/4]

Botan::TLS::Session::Session	(	const secure_vector< uint8_t > &	session_psk,
		const std::optional< uint32_t > &	max_early_data_bytes,
		uint32_t	ticket_age_add,
		std::chrono::seconds	lifetime_hint,
		Protocol_Version	version,
		uint16_t	ciphersuite,
		Connection_Side	side,
		const std::vector< X509_Certificate > &	peer_certs,
		std::shared_ptr< const Public_Key >	peer_raw_public_key,
		const Server_Information &	server_info,
		std::chrono::system_clock::time_point	current_timestamp )

New TLS 1.3 session (sets session start time)

Definition at line 270 of file tls_session.cpp.

                                                                    :
      Session_Base(current_timestamp,
                   version,
                   ciphersuite,
                   side,
 
                   // TODO: SRTP might become necessary when DTLS 1.3 is being implemented
                   0,
 
                   // RFC 8446 Appendix D
                   //    Because TLS 1.3 always hashes in the transcript up to the server
                   //    Finished, implementations which support both TLS 1.3 and earlier
                   //    versions SHOULD indicate the use of the Extended Master Secret
                   //    extension in their APIs whenever TLS 1.3 is used.
                   true,
 
                   // TLS 1.3 uses AEADs, so technically encrypt-then-MAC is not applicable.
                   false,
                   peer_certs,
                   std::move(peer_raw_public_key),
                   server_info),
      m_master_secret(session_psk),
      m_early_data_allowed(max_early_data_bytes.has_value()),
      m_max_early_data_bytes(max_early_data_bytes.value_or(0)),
      m_ticket_age_add(ticket_age_add),
      m_lifetime_hint(lifetime_hint) {
   BOTAN_ARG_CHECK(!version.is_pre_tls_13(), "Instantiated a TLS 1.3 session object with a TLS version older than 1.3");
}

References BOTAN_ARG_CHECK, Botan::TLS::Session_Base::ciphersuite(), lifetime_hint(), max_early_data_bytes(), Botan::TLS::Session_Base::peer_certs(), Botan::TLS::Session_Base::peer_raw_public_key(), Botan::TLS::Session_Base::server_info(), Botan::TLS::Session_Base::Session_Base(), Botan::TLS::Session_Base::side(), and Botan::TLS::Session_Base::version().

◆ Session() [3/4]

Botan::TLS::Session::Session ( std::span< const uint8_t > ber_data )

Load a session from DER representation (created by DER_encode)

Parameters

ber_data DER representation buffer

Definition at line 313 of file tls_session.cpp.

                                                  {
   uint8_t side_code = 0;
 
   std::vector<uint8_t> raw_pubkey_or_empty;
 
   ASN1_String server_hostname;
   ASN1_String server_service;
   size_t server_port = 0;
 
   uint8_t major_version = 0;
   uint8_t minor_version = 0;
 
   size_t start_time = 0;
   size_t srtp_profile = 0;
   uint16_t ciphersuite_code = 0;
   uint64_t lifetime_hint = 0;
 
   BER_Decoder(ber_data, BER_Decoder::Limits::DER())
      .start_sequence()
      .decode_and_check(TLS_SESSION_PARAM_STRUCT_VERSION, "Unknown version in serialized TLS session")
      .decode_integer_type(start_time)
      .decode_integer_type(major_version)
      .decode_integer_type(minor_version)
      .decode_integer_type(ciphersuite_code)
      .decode_integer_type(side_code)
      .decode(m_extended_master_secret)
      .decode(m_encrypt_then_mac)
      .decode(m_master_secret, ASN1_Type::OctetString)
      .decode_list<X509_Certificate>(m_peer_certs)
      .decode(raw_pubkey_or_empty, ASN1_Type::OctetString)
      .decode(server_hostname)
      .decode(server_service)
      .decode(server_port)
      .decode(srtp_profile)
      .decode(m_early_data_allowed)
      .decode_integer_type(m_max_early_data_bytes)
      .decode_integer_type(m_ticket_age_add)
      .decode_integer_type(lifetime_hint)
      .end_cons()
      .verify_end();
 
   if(!Ciphersuite::by_id(ciphersuite_code)) {
      throw Decoding_Error(
         "Serialized TLS session contains unknown cipher suite "
         "(" +
         std::to_string(ciphersuite_code) + ")");
   }
 
   m_ciphersuite = ciphersuite_code;
   m_version = Protocol_Version(major_version, minor_version);
   m_start_time = std::chrono::system_clock::from_time_t(start_time);
   if(side_code != static_cast<uint8_t>(Connection_Side::Client) &&
      side_code != static_cast<uint8_t>(Connection_Side::Server)) {
      throw Decoding_Error("Serialized TLS session contains unknown connection side " + std::to_string(side_code));
   }
   m_connection_side = static_cast<Connection_Side>(side_code);
 
   const bool valid_secret_size = m_version.is_pre_tls_13()
                                     ? (m_master_secret.size() == 48)
                                     : (m_master_secret.size() == 32 || m_master_secret.size() == 48);
   if(!valid_secret_size) {
      throw Decoding_Error("Serialized TLS session has master_secret of unexpected length");
   }
   m_srtp_profile = static_cast<uint16_t>(srtp_profile);
 
   m_server_info =
      Server_Information(server_hostname.value(), server_service.value(), static_cast<uint16_t>(server_port));
 
   if(!raw_pubkey_or_empty.empty()) {
      m_peer_raw_public_key = X509::load_key(raw_pubkey_or_empty);
   }
 
   m_lifetime_hint = std::chrono::seconds(lifetime_hint);
}

◆ Session() [4/4]

Botan::TLS::Session::Session ( std::string_view pem )

explicit

Load a session from PEM representation (created by PEM_encode)

Parameters

PEM	PEM representation

Definition at line 311 of file tls_session.cpp.

311: Session(PEM_Code::decode_check_label(pem, "TLS SESSION")) {}

Botan::TLS::Session::Session

Session(const secure_vector< uint8_t > &master_secret, Protocol_Version version, uint16_t ciphersuite, Connection_Side side, bool supports_extended_master_secret, bool supports_encrypt_then_mac, const std::vector< X509_Certificate > &peer_certs, const Server_Information &server_info, uint16_t srtp_profile, std::chrono::system_clock::time_point current_timestamp, std::chrono::seconds lifetime_hint=std::chrono::seconds::max())

Definition tls_session.cpp:239

Botan::PEM_Code::decode_check_label

secure_vector< uint8_t > decode_check_label(DataSource &source, std::string_view label_want)

Definition pem.cpp:49

References Session().

Member Function Documentation

◆ ciphersuite()

Ciphersuite Botan::TLS::Session_Base::ciphersuite ( ) const

inherited

Get the ciphersuite info of the negotiated TLS session

Definition at line 123 of file tls_session.cpp.

                                            {
   auto suite = Ciphersuite::by_id(m_ciphersuite);
   if(!suite.has_value()) {
      throw Decoding_Error("Failed to find cipher suite for ID " + std::to_string(m_ciphersuite));
   }
   return suite.value();
}

References Botan::TLS::Ciphersuite::by_id(), and m_ciphersuite.

Referenced by Botan::TLS::Session_Summary::cipher_algo(), Botan::TLS::Session_Summary::mac_algo(), Botan::TLS::Session_Summary::prf_algo(), Botan::TLS::Session::Session(), Botan::TLS::Session::Session(), and Session_Base().

◆ ciphersuite_code()

uint16_t Botan::TLS::Session_Base::ciphersuite_code ( ) const

inlineinherited

Get the ciphersuite code of the negotiated TLS session

Definition at line 79 of file tls_session.h.

79{ return m_ciphersuite; }

References m_ciphersuite.

Referenced by Botan::TLS::Client_Hello_12::Client_Hello_12(), and Botan::TLS::Session::Session().

◆ decrypt() [1/2]

Session Botan::TLS::Session::decrypt	(	const uint8_t	ctext[],
		size_t	ctext_size,
		const SymmetricKey &	key )

inlinestatic

Decrypt a session created by encrypt

Parameters

ctext	the ciphertext returned by encrypt
ctext_size	the size of ctext in bytes
key	the same key used by the encrypting side

Definition at line 304 of file tls_session.h.

                                                                                                       {
         return Session::decrypt(std::span(ctext, ctext_size), key);
      }

References decrypt(), and Session().

Referenced by decrypt(), Botan::TLS::Session_Manager_SQL::find_some(), Botan::TLS::Session_Manager_SQL::retrieve_one(), and Botan::TLS::Session_Manager_Stateless::retrieve_one().

◆ decrypt() [2/2]

Session Botan::TLS::Session::decrypt	(	std::span< const uint8_t >	ctext,
		const SymmetricKey &	key )

static

Decrypt a session created by encrypt

Parameters

ctext	the ciphertext returned by encrypt
key	the same key used by the encrypting side

Definition at line 494 of file tls_session.cpp.

                                                                           {
   try {
      const size_t min_session_size = 48 + 4;  // serious under-estimate
      if(in.size() < TLS_SESSION_CRYPT_OVERHEAD + min_session_size) {
         throw Decoding_Error("Encrypted session too short to be valid");
      }
 
      BufferSlicer sub(in);
      const auto* const magic = sub.take(TLS_SESSION_CRYPT_MAGIC_LEN).data();
      const auto* const key_name = sub.take(TLS_SESSION_CRYPT_KEY_NAME_LEN).data();
      const auto* const key_seed = sub.take(TLS_SESSION_CRYPT_AEAD_KEY_SEED_LEN).data();
      const auto* const aead_nonce = sub.take(TLS_SESSION_CRYPT_AEAD_NONCE_LEN).data();
      auto ctext = sub.copy_as_secure_vector(sub.remaining());
 
      if(load_be<uint64_t>(magic, 0) != TLS_SESSION_CRYPT_MAGIC) {
         throw Decoding_Error("Missing expected magic numbers");
      }
 
      auto hmac = MessageAuthenticationCode::create_or_throw(TLS_SESSION_CRYPT_HMAC);
      hmac->set_key(key);
 
      // First derive and check the "key name"
      std::vector<uint8_t> cmp_key_name(hmac->output_length());
      hmac->update(TLS_SESSION_CRYPT_KEY_NAME);
      hmac->final(cmp_key_name.data());
 
      if(CT::is_equal(cmp_key_name.data(), key_name, TLS_SESSION_CRYPT_KEY_NAME_LEN).as_bool() == false) {
         throw Decoding_Error("Wrong key name for encrypted session");
      }
 
      hmac->update(key_seed, TLS_SESSION_CRYPT_AEAD_KEY_SEED_LEN);
      const secure_vector<uint8_t> aead_key = hmac->final();
 
      auto aead = AEAD_Mode::create_or_throw(TLS_SESSION_CRYPT_AEAD, Cipher_Dir::Decryption);
      aead->set_key(aead_key);
      aead->set_associated_data(in.data(), TLS_SESSION_CRYPT_HDR_LEN);
      aead->start(aead_nonce, TLS_SESSION_CRYPT_AEAD_NONCE_LEN);
      aead->finish(ctext, 0);
      return Session(ctext);
   } catch(std::exception& e) {
      throw Decoding_Error("Failed to decrypt serialized TLS session: " + std::string(e.what()));
   }
}

References Botan::BufferSlicer::copy_as_secure_vector(), Botan::AEAD_Mode::create_or_throw(), Botan::MessageAuthenticationCode::create_or_throw(), Botan::Decryption, Botan::CT::is_equal(), Botan::load_be(), Botan::BufferSlicer::remaining(), Session(), and Botan::BufferSlicer::take().

◆ DER_encode()

secure_vector< uint8_t > Botan::TLS::Session::DER_encode ( ) const

Encode this session data for storage

Warning: if the master secret is compromised so is the session traffic

Definition at line 388 of file tls_session.cpp.

                                                 {
   const auto raw_pubkey_or_empty =
      m_peer_raw_public_key ? m_peer_raw_public_key->subject_public_key() : std::vector<uint8_t>{};
 
   return DER_Encoder()
      .start_sequence()
      .encode(TLS_SESSION_PARAM_STRUCT_VERSION)
      .encode(static_cast<size_t>(std::chrono::system_clock::to_time_t(m_start_time)))
      .encode(static_cast<size_t>(m_version.major_version()))
      .encode(static_cast<size_t>(m_version.minor_version()))
      .encode(static_cast<size_t>(m_ciphersuite))
      .encode(static_cast<size_t>(m_connection_side))
      .encode(m_extended_master_secret)
      .encode(m_encrypt_then_mac)
      .encode(m_master_secret, ASN1_Type::OctetString)
      .start_sequence()
      .encode_list(m_peer_certs)
      .end_cons()
      .encode(raw_pubkey_or_empty, ASN1_Type::OctetString)
      .encode(ASN1_String(m_server_info.hostname(), ASN1_Type::Utf8String))
      .encode(ASN1_String(m_server_info.service(), ASN1_Type::Utf8String))
      .encode(static_cast<size_t>(m_server_info.port()))
      .encode(static_cast<size_t>(m_srtp_profile))
 
      // the fields below were introduced for TLS 1.3 session tickets
      .encode(m_early_data_allowed)
      .encode(static_cast<size_t>(m_max_early_data_bytes))
      .encode(static_cast<size_t>(m_ticket_age_add))
      .encode(static_cast<size_t>(m_lifetime_hint.count()))
      .end_cons()
      .get_contents();
}

Referenced by encrypt(), and PEM_encode().

◆ dtls_srtp_profile()

uint16_t Botan::TLS::Session_Base::dtls_srtp_profile ( ) const

inlineinherited

Get the negotiated DTLS-SRTP algorithm (RFC 5764)

Definition at line 94 of file tls_session.h.

94{ return m_srtp_profile; }

References m_srtp_profile.

◆ encrypt()

std::vector< uint8_t > Botan::TLS::Session::encrypt	(	const SymmetricKey &	key,
		RandomNumberGenerator &	rng ) const

Encrypt a session (useful for serialization or session tickets)

Definition at line 451 of file tls_session.cpp.

                                                                                             {
   auto hmac = MessageAuthenticationCode::create_or_throw(TLS_SESSION_CRYPT_HMAC);
   hmac->set_key(key);
 
   // First derive the "key name"
   std::vector<uint8_t> key_name(hmac->output_length());
   hmac->update(TLS_SESSION_CRYPT_KEY_NAME);
   hmac->final(key_name.data());
   key_name.resize(TLS_SESSION_CRYPT_KEY_NAME_LEN);
 
   std::vector<uint8_t> aead_nonce;
   std::vector<uint8_t> key_seed;
 
   rng.random_vec(aead_nonce, TLS_SESSION_CRYPT_AEAD_NONCE_LEN);
   rng.random_vec(key_seed, TLS_SESSION_CRYPT_AEAD_KEY_SEED_LEN);
 
   hmac->update(key_seed);
   const secure_vector<uint8_t> aead_key = hmac->final();
 
   secure_vector<uint8_t> bits = this->DER_encode();
 
   // create the header
   std::vector<uint8_t> buf;
   buf.reserve(TLS_SESSION_CRYPT_OVERHEAD + bits.size());
   buf.resize(TLS_SESSION_CRYPT_MAGIC_LEN);
   store_be(TLS_SESSION_CRYPT_MAGIC, &buf[0]);  // NOLINT(*container-data-pointer)
   buf += key_name;
   buf += key_seed;
   buf += aead_nonce;
 
   auto aead = AEAD_Mode::create_or_throw(TLS_SESSION_CRYPT_AEAD, Cipher_Dir::Encryption);
   BOTAN_ASSERT_NOMSG(aead->valid_nonce_length(TLS_SESSION_CRYPT_AEAD_NONCE_LEN));
   BOTAN_ASSERT_NOMSG(aead->tag_size() == TLS_SESSION_CRYPT_AEAD_TAG_SIZE);
   aead->set_key(aead_key);
   aead->set_associated_data(buf);
   aead->start(aead_nonce);
   aead->finish(bits, 0);
 
   // append the ciphertext
   buf += bits;
   return buf;
}

References BOTAN_ASSERT_NOMSG, Botan::AEAD_Mode::create_or_throw(), Botan::MessageAuthenticationCode::create_or_throw(), DER_encode(), Botan::Encryption, Botan::RandomNumberGenerator::random_vec(), and Botan::store_be().

Referenced by Botan::TLS::Session_Manager_Stateless::establish(), and Botan::TLS::Session_Manager_SQL::store().

◆ extract_master_secret()

secure_vector< uint8_t > Botan::TLS::Session::extract_master_secret ( )

Get the contained master secret as a moved-out object

Definition at line 425 of file tls_session.cpp.

                                                      {
   BOTAN_STATE_CHECK(!m_master_secret.empty());
   return std::exchange(m_master_secret, {});
}

References BOTAN_STATE_CHECK.

◆ lifetime_hint()

std::chrono::seconds Botan::TLS::Session::lifetime_hint ( ) const

inline

Returns: the lifetime of the ticket as defined by the TLS server

Definition at line 350 of file tls_session.h.

350{ return m_lifetime_hint; }

Referenced by Session(), Session(), Session(), and Botan::TLS::Callbacks::tls_should_persist_resumption_information().

◆ master_secret()

const secure_vector< uint8_t > & Botan::TLS::Session::master_secret ( ) const

inline

Get a reference to the contained master secret

Definition at line 325 of file tls_session.h.

325{ return m_master_secret; }

Referenced by Session().

◆ max_early_data_bytes()

uint32_t Botan::TLS::Session::max_early_data_bytes ( ) const

inline

Return the number of bytes allowed for 0-RTT early data

Definition at line 345 of file tls_session.h.

345{ return m_max_early_data_bytes; }

Referenced by Session().

◆ peer_certs()

const std::vector< X509_Certificate > & Botan::TLS::Session_Base::peer_certs ( ) const

inlineinherited

Return the certificate chain of the peer (possibly empty)

Definition at line 111 of file tls_session.h.

111{ return m_peer_certs; }

References m_peer_certs.

Referenced by Botan::TLS::Session_Summary::Client_Impl_13, Botan::TLS::Session::Session(), and Session_Base().

◆ peer_raw_public_key()

std::shared_ptr< const Public_Key > Botan::TLS::Session_Base::peer_raw_public_key ( ) const

inlineinherited

Return the raw public key of the peer (possibly empty)

Definition at line 116 of file tls_session.h.

116{ return m_peer_raw_public_key; }

References m_peer_raw_public_key.

Referenced by Botan::TLS::Session_Summary::Client_Impl_13, Botan::TLS::Session::Session(), and Session_Base().

◆ PEM_encode()

std::string Botan::TLS::Session::PEM_encode ( ) const

Encode this session data for storage

Warning: if the master secret is compromised so is the session traffic

Definition at line 421 of file tls_session.cpp.

                                    {
   return PEM_Code::encode(this->DER_encode(), "TLS SESSION");
}

References DER_encode(), and Botan::PEM_Code::encode().

◆ server_info()

const Server_Information & Botan::TLS::Session_Base::server_info ( ) const

inlineinherited

Get information about the TLS server

Returns information that identifies the server side of the connection. This is useful for the client in that it identifies what was originally passed to the constructor. For the server, it includes the name the client specified in the server name indicator extension.

Definition at line 126 of file tls_session.h.

126{ return m_server_info; }

References m_server_info.

Referenced by Botan::TLS::Client_Hello_12::Client_Hello_12(), Botan::TLS::Session_Summary::Client_Impl_13, Botan::TLS::Session::Session(), Botan::TLS::Session::Session(), Session_Base(), and Botan::TLS::Session_Manager_SQL::store().