Botan  1.11.15
Public Member Functions | Static Public Member Functions
Botan::TLS::Session Class Reference

#include <tls_session.h>

List of all members.

Public Member Functions

Ciphersuite ciphersuite () const
u16bit ciphersuite_code () const
byte compression_method () const
secure_vector< byteDER_encode () const
u16bit dtls_srtp_profile () const
std::vector< byteencrypt (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_Informationserver_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

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

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); }

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; }

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:
ctextthe ciphertext returned by encrypt
ctext_sizethe size of ctext in bytes
keythe 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:
ctextthe ciphertext returned by encrypt
keythe 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();
   }

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");
   }
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; }

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; }

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: