Botan  2.4.0
Crypto and TLS for C++11
Public Member Functions | Static Public Member Functions | List of all members
Botan::TLS::Session Class Referencefinal

#include <tls_session.h>

Public Member Functions

Ciphersuite ciphersuite () const
 
uint16_t ciphersuite_code () const
 
uint8_t compression_method () 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_Informationserver_info () const
 
 Session ()
 
 Session (const std::vector< uint8_t > &session_id, const secure_vector< uint8_t > &master_secret, Protocol_Version version, uint16_t ciphersuite, uint8_t compression_method, 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.

References Botan::CryptoBox::decrypt(), and Botan::CryptoBox::encrypt().

Referenced by decrypt(), and Session().

34  :
35  m_start_time(std::chrono::system_clock::time_point::min()),
36  m_version(),
37  m_ciphersuite(0),
38  m_compression_method(0),
39  m_connection_side(static_cast<Connection_Side>(0)),
40  m_srtp_profile(0),
41  m_extended_master_secret(false),
42  m_encrypt_then_mac(false)
43  {}

◆ 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,
uint8_t  compression_method,
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.

33  :
34  m_start_time(std::chrono::system_clock::now()),
35  m_identifier(session_identifier),
36  m_session_ticket(ticket),
37  m_master_secret(master_secret),
38  m_version(version),
39  m_ciphersuite(ciphersuite),
40  m_compression_method(compression_method),
41  m_connection_side(side),
42  m_srtp_profile(srtp_profile),
43  m_extended_master_secret(extended_master_secret),
44  m_encrypt_then_mac(encrypt_then_mac),
45  m_peer_certs(certs),
46  m_server_info(server_info),
47  m_srp_identifier(srp_identifier)
48  {
49  }
uint8_t compression_method() const
Definition: tls_session.h:135
const Server_Information & server_info() const
Definition: tls_session.h:190
Connection_Side side() const
Definition: tls_session.h:141
Ciphersuite ciphersuite() const
Definition: tls_session.h:130
const secure_vector< uint8_t > & master_secret() const
Definition: tls_session.h:151
Protocol_Version version() const
Definition: tls_session.h:120
const std::string & srp_identifier() const
Definition: tls_session.h:146

◆ 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
berDER representation buffer
ber_lensize of buffer in bytes

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

59  {
60  uint8_t side_code = 0;
61 
62  ASN1_String server_hostname;
63  ASN1_String server_service;
64  size_t server_port;
65 
66  ASN1_String srp_identifier_str;
67 
68  uint8_t major_version = 0, minor_version = 0;
69  std::vector<uint8_t> peer_cert_bits;
70 
71  size_t start_time = 0;
72  size_t srtp_profile = 0;
73  size_t fragment_size = 0;
74 
75  BER_Decoder(ber, ber_len)
76  .start_cons(SEQUENCE)
77  .decode_and_check(static_cast<size_t>(TLS_SESSION_PARAM_STRUCT_VERSION),
78  "Unknown version in serialized TLS session")
79  .decode_integer_type(start_time)
80  .decode_integer_type(major_version)
81  .decode_integer_type(minor_version)
82  .decode(m_identifier, OCTET_STRING)
83  .decode(m_session_ticket, OCTET_STRING)
84  .decode_integer_type(m_ciphersuite)
85  .decode_integer_type(m_compression_method)
86  .decode_integer_type(side_code)
87  .decode_integer_type(fragment_size)
88  .decode(m_extended_master_secret)
89  .decode(m_encrypt_then_mac)
90  .decode(m_master_secret, OCTET_STRING)
91  .decode(peer_cert_bits, OCTET_STRING)
92  .decode(server_hostname)
93  .decode(server_service)
94  .decode(server_port)
95  .decode(srp_identifier_str)
96  .decode(srtp_profile)
97  .end_cons()
98  .verify_end();
99 
100  /*
101  Fragment size is not supported anymore, but the field is still
102  set in the session object.
103  */
104  if(fragment_size != 0)
105  {
106  throw Decoding_Error("Serialized TLS session used maximum fragment length which is "
107  " no longer supported");
108  }
109 
110  m_version = Protocol_Version(major_version, minor_version);
111  m_start_time = std::chrono::system_clock::from_time_t(start_time);
112  m_connection_side = static_cast<Connection_Side>(side_code);
113  m_srtp_profile = static_cast<uint16_t>(srtp_profile);
114 
115  m_server_info = Server_Information(server_hostname.value(),
116  server_service.value(),
117  static_cast<uint16_t>(server_port));
118 
119  m_srp_identifier = srp_identifier_str.value();
120 
121  if(!peer_cert_bits.empty())
122  {
123  DataSource_Memory certs(peer_cert_bits.data(), peer_cert_bits.size());
124 
125  while(!certs.end_of_data())
126  m_peer_certs.push_back(X509_Certificate(certs));
127  }
128  }
std::chrono::system_clock::time_point start_time() const
Definition: tls_session.h:175

◆ Session() [4/4]

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

Load a session from PEM representation (created by PEM_encode)

Parameters
pemPEM representation

Definition at line 51 of file tls_session.cpp.

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

52  {
53  secure_vector<uint8_t> der = PEM_Code::decode_check_label(pem, "TLS SESSION");
54 
55  *this = Session(der.data(), der.size());
56  }
secure_vector< uint8_t > decode_check_label(DataSource &source, const std::string &label_want)
Definition: pem.cpp:54

Member Function Documentation

◆ ciphersuite()

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

Get the ciphersuite info of the saved session

Definition at line 130 of file tls_session.h.

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

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

130 { return Ciphersuite::by_id(m_ciphersuite); }
static Ciphersuite by_id(uint16_t suite)

◆ ciphersuite_code()

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

Get the ciphersuite code of the saved session

Definition at line 125 of file tls_session.h.

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

125 { return m_ciphersuite; }

◆ compression_method()

uint8_t Botan::TLS::Session::compression_method ( ) const
inline

Get the compression method used in the saved session

Definition at line 135 of file tls_session.h.

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

135 { return m_compression_method; }

◆ 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
ctextthe ciphertext returned by encrypt
ctext_sizethe size of ctext in bytes
keythe same key used by the encrypting side

Definition at line 194 of file tls_session.cpp.

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

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

195  {
196  try
197  {
198  std::unique_ptr<AEAD_Mode> aead(get_aead("AES-256/GCM", DECRYPTION));
199  const size_t nonce_len = aead->default_nonce_length();
200 
201  if(in_len < nonce_len + aead->tag_size())
202  throw Decoding_Error("Encrypted session too short to be valid");
203 
204  // Support any length key for input
205  std::unique_ptr<MessageAuthenticationCode> hmac(MessageAuthenticationCode::create("HMAC(SHA-256)"));
206  hmac->set_key(key);
207  hmac->update(in, nonce_len); // nonce bytes
208  aead->set_key(hmac->final());
209 
210  aead->start(in, nonce_len);
211  secure_vector<uint8_t> buf(in + nonce_len, in + in_len);
212  aead->finish(buf, 0);
213 
214  return Session(buf.data(), buf.size());
215  }
216  catch(std::exception& e)
217  {
218  throw Decoding_Error("Failed to decrypt serialized TLS session: " +
219  std::string(e.what()));
220  }
221  }
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:45
AEAD_Mode * get_aead(const std::string &algo, Cipher_Dir dir)
Definition: aead.cpp:42

◆ 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
ctextthe ciphertext returned by encrypt
keythe same key used by the encrypting side

Definition at line 104 of file tls_session.h.

References decrypt(), and Botan::PKCS8::PEM_encode().

106  {
107  return Session::decrypt(ctext.data(), ctext.size(), key);
108  }
static Session decrypt(const uint8_t ctext[], size_t ctext_size, const SymmetricKey &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 130 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().

131  {
132  std::vector<uint8_t> peer_cert_bits;
133  for(size_t i = 0; i != m_peer_certs.size(); ++i)
134  peer_cert_bits += m_peer_certs[i].BER_encode();
135 
136  return DER_Encoder()
137  .start_cons(SEQUENCE)
138  .encode(static_cast<size_t>(TLS_SESSION_PARAM_STRUCT_VERSION))
139  .encode(static_cast<size_t>(std::chrono::system_clock::to_time_t(m_start_time)))
140  .encode(static_cast<size_t>(m_version.major_version()))
141  .encode(static_cast<size_t>(m_version.minor_version()))
142  .encode(m_identifier, OCTET_STRING)
143  .encode(m_session_ticket, OCTET_STRING)
144  .encode(static_cast<size_t>(m_ciphersuite))
145  .encode(static_cast<size_t>(m_compression_method))
146  .encode(static_cast<size_t>(m_connection_side))
147  .encode(static_cast<size_t>(/*old fragment size*/0))
148  .encode(m_extended_master_secret)
149  .encode(m_encrypt_then_mac)
150  .encode(m_master_secret, OCTET_STRING)
151  .encode(peer_cert_bits, OCTET_STRING)
152  .encode(ASN1_String(m_server_info.hostname(), UTF8_STRING))
153  .encode(ASN1_String(m_server_info.service(), UTF8_STRING))
154  .encode(static_cast<size_t>(m_server_info.port()))
155  .encode(ASN1_String(m_srp_identifier, UTF8_STRING))
156  .encode(static_cast<size_t>(m_srtp_profile))
157  .end_cons()
158  .get_contents();
159  }
uint8_t minor_version() const
Definition: tls_version.h:82
std::string hostname() const
secure_vector< uint8_t > BER_encode(const Private_Key &key)
Definition: pkcs8.cpp:131
uint8_t major_version() const
Definition: tls_version.h:77

◆ dtls_srtp_profile()

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

Get the negotiated DTLS-SRTP algorithm (RFC 5764)

Definition at line 161 of file tls_session.h.

161 { 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 173 of file tls_session.cpp.

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

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

174  {
175  std::unique_ptr<AEAD_Mode> aead(get_aead("AES-256/GCM", ENCRYPTION));
176  const size_t nonce_len = aead->default_nonce_length();
177 
178  const secure_vector<uint8_t> nonce = rng.random_vec(nonce_len);
179  const secure_vector<uint8_t> bits = this->DER_encode();
180 
181  // Support any length key for input
182  std::unique_ptr<MessageAuthenticationCode> hmac(MessageAuthenticationCode::create("HMAC(SHA-256)"));
183  hmac->set_key(key);
184  hmac->update(nonce);
185  aead->set_key(hmac->final());
186 
187  secure_vector<uint8_t> buf = nonce;
188  buf += bits;
189  aead->start(buf.data(), nonce_len);
190  aead->finish(buf, nonce_len);
191  return unlock(buf);
192  }
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:45
secure_vector< uint8_t > DER_encode() const
std::vector< T > unlock(const secure_vector< T > &in)
Definition: secmem.h:95
AEAD_Mode * get_aead(const std::string &algo, Cipher_Dir dir)
Definition: aead.cpp:42

◆ master_secret()

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

Get the saved master secret

Definition at line 151 of file tls_session.h.

Referenced by Botan::TLS::Client::Client(), and Botan::TLS::Server::Server().

151 { 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 170 of file tls_session.h.

Referenced by Botan::TLS::Client::Client(), and Botan::TLS::Server::Server().

170 { 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 161 of file tls_session.cpp.

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

162  {
163  return PEM_Code::encode(this->DER_encode(), "TLS SESSION");
164  }
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43
secure_vector< uint8_t > DER_encode() const

◆ server_info()

const Server_Information& Botan::TLS::Session::server_info ( ) const
inline
Returns
information about the TLS server

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

190 { 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 166 of file tls_session.cpp.

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

◆ session_id()

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

Get the session identifier

Definition at line 156 of file tls_session.h.

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

156 { 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 185 of file tls_session.h.

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

185 { 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 141 of file tls_session.h.

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

141 { 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 146 of file tls_session.h.

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

146 { 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 175 of file tls_session.h.

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

175 { return m_start_time; }

◆ supports_encrypt_then_mac()

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

Definition at line 165 of file tls_session.h.

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

165 { return m_encrypt_then_mac; }

◆ supports_extended_master_secret()

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

Definition at line 163 of file tls_session.h.

163 { return m_extended_master_secret; }

◆ version()

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

Get the version of the saved session

Definition at line 120 of file tls_session.h.

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

120 { return m_version; }

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