#include <tls_session.h>

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

const secure_vector< uint8_t > &	master_secret () const

const std::vector< X509_Certificate > &	peer_certs () const

std::string	PEM_encode () const

const Server_Information &	server_info () const

	Session ()

	Session (const std::vector< uint8_t > &session_id, 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 std::vector< uint8_t > &session_ticket, const Server_Information &server_info, const std::string &srp_identifier, uint16_t srtp_profile)

	Session (const uint8_t ber[], size_t ber_len)

	Session (const std::string &pem)

std::chrono::seconds	session_age () const

const std::vector< uint8_t > &	session_id () const

const std::vector< uint8_t > &	session_ticket () const

Connection_Side	side () const

const std::string &	srp_identifier () const

std::chrono::system_clock::time_point	start_time () 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 (const std::vector< uint8_t > &ctext, const SymmetricKey &key)

Detailed Description

Class representing a TLS session state

Definition at line 27 of file tls_session.h.

Constructor & Destructor Documentation

◆ Session() [1/4]

Botan::TLS::Session::Session ( )

inline

Uninitialized session

Definition at line 34 of file tls_session.h.

Referenced by decrypt(), and Session().

                 :
          m_start_time(std::chrono::system_clock::time_point::min()),
          m_version(),
          m_ciphersuite(0),
          m_connection_side(static_cast<Connection_Side>(0)),
          m_srtp_profile(0),
          m_extended_master_secret(false),
          m_encrypt_then_mac(false)
             {}

◆ Session() [2/4]

Botan::TLS::Session::Session	(	const std::vector< uint8_t > &	session_id,
		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 std::vector< uint8_t > &	session_ticket,
		const Server_Information &	server_info,
		const std::string &	srp_identifier,
		uint16_t	srtp_profile
	)

New session (sets session start time)

Definition at line 21 of file tls_session.cpp.

                                         :
    m_start_time(std::chrono::system_clock::now()),
    m_identifier(session_identifier),
    m_session_ticket(ticket),
    m_master_secret(master_secret),
    m_version(version),
    m_ciphersuite(ciphersuite),
    m_connection_side(side),
    m_srtp_profile(srtp_profile),
    m_extended_master_secret(extended_master_secret),
    m_encrypt_then_mac(encrypt_then_mac),
    m_peer_certs(certs),
    m_server_info(server_info),
    m_srp_identifier(srp_identifier)
    {
    }

◆ Session() [3/4]

Botan::TLS::Session::Session	(	const uint8_t	ber[],
		size_t	ber_len
	)

Load a session from DER representation (created by DER_encode)

Parameters

ber	DER representation buffer
ber_len	size of buffer in bytes

Definition at line 56 of file tls_session.cpp.

References Botan::BER_Decoder::decode(), Botan::BER_Decoder::decode_and_check(), Botan::BER_Decoder::decode_integer_type(), Botan::BER_Decoder::end_cons(), Botan::OCTET_STRING, Botan::SEQUENCE, Botan::BER_Decoder::start_cons(), start_time(), Botan::ASN1_String::value(), and Botan::BER_Decoder::verify_end().

    {
    uint8_t side_code = 0;
 
    ASN1_String server_hostname;
    ASN1_String server_service;
    size_t server_port;
 
    ASN1_String srp_identifier_str;
 
    uint8_t major_version = 0, minor_version = 0;
    std::vector<uint8_t> peer_cert_bits;
 
    size_t start_time = 0;
    size_t srtp_profile = 0;
    size_t fragment_size = 0;
    size_t compression_method = 0;
 
    BER_Decoder(ber, ber_len)
       .start_cons(SEQUENCE)
         .decode_and_check(static_cast<size_t>(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(m_identifier, OCTET_STRING)
         .decode(m_session_ticket, OCTET_STRING)
         .decode_integer_type(m_ciphersuite)
         .decode_integer_type(compression_method)
         .decode_integer_type(side_code)
         .decode_integer_type(fragment_size)
         .decode(m_extended_master_secret)
         .decode(m_encrypt_then_mac)
         .decode(m_master_secret, OCTET_STRING)
         .decode(peer_cert_bits, OCTET_STRING)
         .decode(server_hostname)
         .decode(server_service)
         .decode(server_port)
         .decode(srp_identifier_str)
         .decode(srtp_profile)
       .end_cons()
       .verify_end();
 
    /*
    * Compression is not supported and must be zero
    */
    if(compression_method != 0)
       {
       throw Decoding_Error("Serialized TLS session contains non-null compression method");
       }
 
    /*
    Fragment size is not supported anymore, but the field is still
    set in the session object.
    */
    if(fragment_size != 0)
       {
       throw Decoding_Error("Serialized TLS session used maximum fragment length which is "
                            " no longer supported");
       }
 
    m_version = Protocol_Version(major_version, minor_version);
    m_start_time = std::chrono::system_clock::from_time_t(start_time);
    m_connection_side = static_cast<Connection_Side>(side_code);
    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));
 
    m_srp_identifier = srp_identifier_str.value();
 
    if(!peer_cert_bits.empty())
       {
       DataSource_Memory certs(peer_cert_bits.data(), peer_cert_bits.size());
 
       while(!certs.end_of_data())
          m_peer_certs.push_back(X509_Certificate(certs));
       }
    }

◆ Session() [4/4]

Botan::TLS::Session::Session ( const std::string & pem )

explicit

Load a session from PEM representation (created by PEM_encode)

Parameters

pem	PEM representation

Definition at line 49 of file tls_session.cpp.

References Botan::PEM_Code::decode_check_label(), and Session().

    {
    secure_vector<uint8_t> der = PEM_Code::decode_check_label(pem, "TLS SESSION");
 
    *this = Session(der.data(), der.size());
    }

Member Function Documentation

◆ ciphersuite()

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

inline

Get the ciphersuite info of the saved session

Definition at line 128 of file tls_session.h.

References Botan::TLS::Ciphersuite::by_id().

Referenced by Botan::TLS::Server_Hello::Server_Hello().

128 { return Ciphersuite::by_id(m_ciphersuite); }

Botan::TLS::Ciphersuite::by_id

static Ciphersuite by_id(uint16_t suite)

Definition: tls_ciphersuite.cpp:70

◆ ciphersuite_code()

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

inline

Get the ciphersuite code of the saved session

Definition at line 123 of file tls_session.h.

Referenced by Botan::TLS::Client_Hello::Client_Hello().

123 { return m_ciphersuite; }

◆ decrypt() [1/2]

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

static

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 201 of file tls_session.cpp.

References Botan::MessageAuthenticationCode::create(), Botan::AEAD_Mode::create_or_throw(), Botan::DECRYPTION, and Session().

Referenced by decrypt(), Botan::TLS::Session_Manager_SQL::load_from_server_info(), and Botan::TLS::Session_Manager_SQL::load_from_session_id().

    {
    try
       {
       std::unique_ptr<AEAD_Mode> aead = AEAD_Mode::create_or_throw("AES-256/GCM", DECRYPTION);
       const size_t nonce_len = aead->default_nonce_length();
 
       if(in_len < nonce_len + aead->tag_size())
          throw Decoding_Error("Encrypted session too short to be valid");
 
       // Support any length key for input
       std::unique_ptr<MessageAuthenticationCode> hmac(MessageAuthenticationCode::create("HMAC(SHA-256)"));
       hmac->set_key(key);
       hmac->update(in, nonce_len); // nonce bytes
       aead->set_key(hmac->final());
 
       aead->start(in, nonce_len);
       secure_vector<uint8_t> buf(in + nonce_len, in + in_len);
       aead->finish(buf, 0);
 
       return Session(buf.data(), buf.size());
       }
    catch(std::exception& e)
       {
       throw Decoding_Error("Failed to decrypt serialized TLS session: " +
                            std::string(e.what()));
       }
    }

◆ decrypt() [2/2]

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

inlinestatic

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 102 of file tls_session.h.

References decrypt().

          {
          return Session::decrypt(ctext.data(), ctext.size(), key);
          }

◆ 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 137 of file tls_session.cpp.

References Botan::PKCS8::BER_encode(), Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::get_contents(), Botan::TLS::Server_Information::hostname(), Botan::TLS::Protocol_Version::major_version(), Botan::TLS::Protocol_Version::minor_version(), Botan::OCTET_STRING, Botan::TLS::Server_Information::port(), Botan::SEQUENCE, Botan::TLS::Server_Information::service(), Botan::DER_Encoder::start_cons(), and Botan::UTF8_STRING.

Referenced by encrypt(), and PEM_encode().

    {
    std::vector<uint8_t> peer_cert_bits;
    for(size_t i = 0; i != m_peer_certs.size(); ++i)
       peer_cert_bits += m_peer_certs[i].BER_encode();
 
    return DER_Encoder()
       .start_cons(SEQUENCE)
          .encode(static_cast<size_t>(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(m_identifier, OCTET_STRING)
          .encode(m_session_ticket, OCTET_STRING)
          .encode(static_cast<size_t>(m_ciphersuite))
          .encode(static_cast<size_t>(/*old compression method*/0))
          .encode(static_cast<size_t>(m_connection_side))
          .encode(static_cast<size_t>(/*old fragment size*/0))
          .encode(m_extended_master_secret)
          .encode(m_encrypt_then_mac)
          .encode(m_master_secret, OCTET_STRING)
          .encode(peer_cert_bits, OCTET_STRING)
          .encode(ASN1_String(m_server_info.hostname(), UTF8_STRING))
          .encode(ASN1_String(m_server_info.service(), UTF8_STRING))
          .encode(static_cast<size_t>(m_server_info.port()))
          .encode(ASN1_String(m_srp_identifier, UTF8_STRING))
          .encode(static_cast<size_t>(m_srtp_profile))
       .end_cons()
    .get_contents();
    }

◆ dtls_srtp_profile()

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

inline

Get the negotiated DTLS-SRTP algorithm (RFC 5764)

Definition at line 154 of file tls_session.h.

154 { return 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 180 of file tls_session.cpp.

References Botan::MessageAuthenticationCode::create(), Botan::AEAD_Mode::create_or_throw(), DER_encode(), Botan::ENCRYPTION, Botan::RandomNumberGenerator::random_vec(), and Botan::unlock().

Referenced by Botan::TLS::Session_Manager_SQL::save(), and Botan::TLS::Session_Manager_In_Memory::save().

    {
    std::unique_ptr<AEAD_Mode> aead = AEAD_Mode::create_or_throw("AES-256/GCM", ENCRYPTION);
    const size_t nonce_len = aead->default_nonce_length();
 
    const secure_vector<uint8_t> nonce = rng.random_vec(nonce_len);
    const secure_vector<uint8_t> bits = this->DER_encode();
 
    // Support any length key for input
    std::unique_ptr<MessageAuthenticationCode> hmac(MessageAuthenticationCode::create("HMAC(SHA-256)"));
    hmac->set_key(key);
    hmac->update(nonce);
    aead->set_key(hmac->final());
 
    secure_vector<uint8_t> buf = nonce;
    buf += bits;
    aead->start(buf.data(), nonce_len);
    aead->finish(buf, nonce_len);
    return unlock(buf);
    }

◆ master_secret()

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

inline

Get the saved master secret

Definition at line 144 of file tls_session.h.

144 { return m_master_secret; }

◆ peer_certs()

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

inline

Return the certificate chain of the peer (possibly empty)

Definition at line 163 of file tls_session.h.

163 { return m_peer_certs; }

◆ 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 168 of file tls_session.cpp.

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

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

◆ server_info()

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

inline

Returns: information about the TLS server

Definition at line 183 of file tls_session.h.

Referenced by Botan::TLS::Client_Hello::Client_Hello(), Botan::TLS::Session_Manager_SQL::save(), and Botan::TLS::Session_Manager_In_Memory::save().

183 { return m_server_info; }

◆ session_age()

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

Return how long this session has existed (in seconds)

Definition at line 173 of file tls_session.cpp.

    {
    return std::chrono::duration_cast<std::chrono::seconds>(
       std::chrono::system_clock::now() - m_start_time);
    }

◆ session_id()

const std::vector<uint8_t>& Botan::TLS::Session::session_id ( ) const

inline

Get the session identifier

Definition at line 149 of file tls_session.h.

Referenced by Botan::TLS::Session_Manager_SQL::save(), and Botan::TLS::Session_Manager_In_Memory::save().

149 { return m_identifier; }

◆ session_ticket()

const std::vector<uint8_t>& Botan::TLS::Session::session_ticket ( ) const

inline

Return the session ticket the server gave us

Definition at line 178 of file tls_session.h.

Referenced by Botan::TLS::Client_Hello::Client_Hello().

178 { return m_session_ticket; }

◆ side()

Connection_Side Botan::TLS::Session::side ( ) const

inline

Get which side of the connection the resumed session we are/were acting as.

Definition at line 134 of file tls_session.h.

Referenced by Botan::TLS::Session_Manager_In_Memory::save().

134 { return m_connection_side; }

◆ srp_identifier()

const std::string& Botan::TLS::Session::srp_identifier ( ) const

inline

Get the SRP identity (if sent by the client in the initial handshake)

Definition at line 139 of file tls_session.h.

Referenced by Botan::TLS::Client_Hello::Client_Hello().

139 { return m_srp_identifier; }

◆ start_time()

std::chrono::system_clock::time_point Botan::TLS::Session::start_time ( ) const

inline

Get the wall clock time this session began

Definition at line 168 of file tls_session.h.

Referenced by Botan::TLS::Session_Manager_SQL::save(), and Session().

168 { return m_start_time; }

◆ supports_encrypt_then_mac()

bool Botan::TLS::Session::supports_encrypt_then_mac ( ) const

inline

Definition at line 158 of file tls_session.h.

Referenced by Botan::TLS::Client_Hello::Client_Hello().

158 { return m_encrypt_then_mac; }

◆ supports_extended_master_secret()

bool Botan::TLS::Session::supports_extended_master_secret ( ) const

inline

Definition at line 156 of file tls_session.h.

156 { return m_extended_master_secret; }

◆ version()

Protocol_Version Botan::TLS::Session::version ( ) const

inline

Get the version of the saved session

Definition at line 118 of file tls_session.h.

118 { return m_version; }

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

src/lib/tls/tls_session.h
src/lib/tls/tls_session.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Session() [1/4]

◆ Session() [2/4]

◆ Session() [3/4]

◆ Session() [4/4]

Member Function Documentation

◆ ciphersuite()

◆ ciphersuite_code()

◆ decrypt() [1/2]

◆ decrypt() [2/2]

◆ DER_encode()

◆ dtls_srtp_profile()

◆ encrypt()

◆ master_secret()

◆ peer_certs()

◆ PEM_encode()

◆ server_info()

◆ session_age()

◆ session_id()

◆ session_ticket()

◆ side()

◆ srp_identifier()

◆ start_time()

◆ supports_encrypt_then_mac()

◆ supports_extended_master_secret()

◆ version()