#include <tls_session.h>

Public Member Functions
Ciphersuite	ciphersuite () const
u16bit	ciphersuite_code () const
byte	compression_method () const
secure_vector< byte >	DER_encode () const
u16bit	dtls_srtp_profile () const
std::vector< byte >	encrypt (const SymmetricKey &key, RandomNumberGenerator &rng) const
size_t	fragment_size () const
const secure_vector< byte > &	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< byte > &session_id, const secure_vector< byte > &master_secret, Protocol_Version version, u16bit ciphersuite, byte compression_method, Connection_Side side, size_t fragment_size, const std::vector< X509_Certificate > &peer_certs, const std::vector< byte > &session_ticket, const Server_Information &server_info, const std::string &srp_identifier, u16bit srtp_profile)
	Session (const byte ber[], size_t ber_len)
	Session (const std::string &pem)
std::chrono::seconds	session_age () const
const std::vector< byte > &	session_id () const
const std::vector< byte > &	session_ticket () const
Connection_Side	side () const
const std::string &	srp_identifier () const
std::chrono::system_clock::time_point	start_time () const
Protocol_Version	version () const
Static Public Member Functions
static Session	decrypt (const byte ctext[], size_t ctext_size, const SymmetricKey &key)
static Session	decrypt (const std::vector< byte > &ctext, const SymmetricKey &key)

Detailed Description

Class representing a TLS session state

Definition at line 27 of file tls_session.h.

Constructor & Destructor Documentation

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_compression_method(0),
         m_connection_side(static_cast<Connection_Side>(0)),
         m_fragment_size(0)
            {}

Botan::TLS::Session::Session	(	const std::vector< byte > &	session_id,
		const secure_vector< byte > &	master_secret,
		Protocol_Version	version,
		u16bit	ciphersuite,
		byte	compression_method,
		Connection_Side	side,
		size_t	fragment_size,
		const std::vector< X509_Certificate > &	peer_certs,
		const std::vector< byte > &	session_ticket,
		const Server_Information &	server_info,
		const std::string &	srp_identifier,
		u16bit	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_compression_method(compression_method),
   m_connection_side(side),
   m_srtp_profile(srtp_profile),
   m_fragment_size(fragment_size),
   m_peer_certs(certs),
   m_server_info(server_info),
   m_srp_identifier(srp_identifier)
   {
   }

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

Load a session from DER representation (created by DER_encode)

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().

   {
   byte side_code = 0;

   ASN1_String server_hostname;
   ASN1_String server_service;
   size_t server_port;

   ASN1_String srp_identifier_str;

   byte major_version = 0, minor_version = 0;
   std::vector<byte> peer_cert_bits;

   size_t start_time = 0;
   size_t srtp_profile = 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(m_compression_method)
        .decode_integer_type(side_code)
        .decode_integer_type(m_fragment_size)
        .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();

   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 = srtp_profile;

   m_server_info = Server_Information(server_hostname.value(),
                                      server_service.value(),
                                      server_port);

   m_srp_identifier = srp_identifier_str.value();

   if(!peer_cert_bits.empty())
      {
      DataSource_Memory certs(&peer_cert_bits[0], peer_cert_bits.size());

      while(!certs.end_of_data())
         m_peer_certs.push_back(X509_Certificate(certs));
      }
   }

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

Load a session from PEM representation (created by PEM_encode)

Definition at line 49 of file tls_session.cpp.

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

   {
   secure_vector<byte> der = PEM_Code::decode_check_label(pem, "TLS SESSION");

   *this = Session(&der[0], der.size());
   }

Member Function Documentation

Ciphersuite Botan::TLS::Session::ciphersuite ( ) const [inline]

Get the ciphersuite info of the saved session

Definition at line 124 of file tls_session.h.

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

{ return Ciphersuite::by_id(m_ciphersuite); }

u16bit Botan::TLS::Session::ciphersuite_code ( ) const [inline]

Get the ciphersuite code of the saved session

Definition at line 119 of file tls_session.h.

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

{ return m_ciphersuite; }

byte Botan::TLS::Session::compression_method ( ) const [inline]

Get the compression method used in the saved session

Definition at line 129 of file tls_session.h.

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

{ return m_compression_method; }

Session Botan::TLS::Session::decrypt	(	const byte	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 177 of file tls_session.cpp.

References Botan::DECRYPTION, e, Botan::Buffered_Computation::final(), Botan::get_aead(), Session(), Botan::SymmetricAlgorithm::set_key(), and Botan::Buffered_Computation::update().

   {
   try
      {
      std::unique_ptr<AEAD_Mode> aead(get_aead("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
      HMAC hmac(new 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<byte> buf(in + nonce_len, in + in_len);
      aead->finish(buf, 0);

      return Session(&buf[0], buf.size());
      }
   catch(std::exception& e)
      {
      throw Decoding_Error("Failed to decrypt serialized TLS session: " +
                           std::string(e.what()));
      }
   }

static Session Botan::TLS::Session::decrypt	(	const std::vector< byte > &	ctext,
		const SymmetricKey &	key
	)		`[inline, 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 98 of file tls_session.h.

References decrypt.

         {
         return Session::decrypt(&ctext[0], ctext.size(), key);
         }

secure_vector< byte > 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 115 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<byte> 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>(m_compression_method))
         .encode(static_cast<size_t>(m_connection_side))
         .encode(static_cast<size_t>(m_fragment_size))
         .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();
   }

u16bit Botan::TLS::Session::dtls_srtp_profile ( ) const [inline]

Get the negotiated DTLS-SRTP algorithm (RFC 5764)

Definition at line 160 of file tls_session.h.

{ return m_srtp_profile; }

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

Encrypt a session (useful for serialization or session tickets)

Definition at line 156 of file tls_session.cpp.

References DER_encode(), Botan::ENCRYPTION, Botan::Buffered_Computation::final(), Botan::get_aead(), Botan::RandomNumberGenerator::random_vec(), Botan::SymmetricAlgorithm::set_key(), Botan::unlock(), and Botan::Buffered_Computation::update().

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

   {
   std::unique_ptr<AEAD_Mode> aead(get_aead("AES-256/GCM", ENCRYPTION));
   const size_t nonce_len = aead->default_nonce_length();

   const secure_vector<byte> nonce = rng.random_vec(nonce_len);
   const secure_vector<byte> bits = this->DER_encode();

   // Support any length key for input
   HMAC hmac(new SHA_256);
   hmac.set_key(key);
   hmac.update(nonce);
   aead->set_key(hmac.final());

   secure_vector<byte> buf = nonce;
   buf += bits;
   aead->start(&buf[0], nonce_len);
   aead->finish(buf, nonce_len);
   return unlock(buf);
   }

size_t Botan::TLS::Session::fragment_size ( ) const [inline]

Get the negotiated maximum fragment size (or 0 if default)

Definition at line 155 of file tls_session.h.

Referenced by Botan::TLS::Client_Hello::Client_Hello(), and Botan::TLS::Server_Hello::Server_Hello().

{ return m_fragment_size; }

const secure_vector<byte>& Botan::TLS::Session::master_secret ( ) const [inline]

Get the saved master secret

Definition at line 145 of file tls_session.h.

{ return m_master_secret; }

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

Return the certificate chain of the peer (possibly empty)

Definition at line 165 of file tls_session.h.

{ return m_peer_certs; }

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

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

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

const Server_Information& Botan::TLS::Session::server_info ( ) const [inline]

Definition at line 182 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().

{ return m_server_info; }

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

Return how long this session has existed (in seconds)

Definition at line 149 of file tls_session.cpp.

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

const std::vector<byte>& Botan::TLS::Session::session_id ( ) const [inline]

Get the session identifier

Definition at line 150 of file tls_session.h.

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

{ return m_identifier; }

const std::vector<byte>& Botan::TLS::Session::session_ticket ( ) const [inline]

Return the session ticket the server gave us

Definition at line 180 of file tls_session.h.

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

{ return m_session_ticket; }

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

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

{ return m_connection_side; }

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

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

{ return m_srp_identifier; }

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

Get the wall clock time this session began

Definition at line 170 of file tls_session.h.

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

{ return m_start_time; }

Protocol_Version Botan::TLS::Session::version ( ) const [inline]

Get the version of the saved session

Definition at line 114 of file tls_session.h.

{ 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

Member Function Documentation