Botan 2.19.3
Crypto and TLS for C&
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
 
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::string &pem)
 
 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)
 
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 std::vector< uint8_t > &ctext, const SymmetricKey &key)
 
static Session decrypt (const uint8_t ctext[], size_t ctext_size, 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.

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

Referenced by decrypt(), and Session().

◆ 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 22 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_connection_side(side),
41 m_srtp_profile(srtp_profile),
42 m_extended_master_secret(extended_master_secret),
43 m_encrypt_then_mac(encrypt_then_mac),
44 m_peer_certs(certs),
45 m_server_info(server_info),
46 m_srp_identifier(srp_identifier)
47 {
48 }
const Server_Information & server_info() const
Protocol_Version version() const
Connection_Side side() const
const secure_vector< uint8_t > & master_secret() const
const std::string & srp_identifier() const
Ciphersuite ciphersuite() const

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

58 {
59 uint8_t side_code = 0;
60
61 ASN1_String server_hostname;
62 ASN1_String server_service;
63 size_t server_port;
64
65 ASN1_String srp_identifier_str;
66
67 uint8_t major_version = 0, minor_version = 0;
68 std::vector<uint8_t> peer_cert_bits;
69
70 size_t start_time = 0;
71 size_t srtp_profile = 0;
72 size_t fragment_size = 0;
73 size_t compression_method = 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(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 * Compression is not supported and must be zero
102 */
103 if(compression_method != 0)
104 {
105 throw Decoding_Error("Serialized TLS session contains non-null compression method");
106 }
107
108 /*
109 Fragment size is not supported anymore, but the field is still
110 set in the session object.
111 */
112 if(fragment_size != 0)
113 {
114 throw Decoding_Error("Serialized TLS session used maximum fragment length which is "
115 " no longer supported");
116 }
117
118 m_version = Protocol_Version(major_version, minor_version);
119 m_start_time = std::chrono::system_clock::from_time_t(start_time);
120 m_connection_side = static_cast<Connection_Side>(side_code);
121 m_srtp_profile = static_cast<uint16_t>(srtp_profile);
122
123 m_server_info = Server_Information(server_hostname.value(),
124 server_service.value(),
125 static_cast<uint16_t>(server_port));
126
127 m_srp_identifier = srp_identifier_str.value();
128
129 if(!peer_cert_bits.empty())
130 {
131 DataSource_Memory certs(peer_cert_bits.data(), peer_cert_bits.size());
132
133 while(!certs.end_of_data())
134 m_peer_certs.push_back(X509_Certificate(certs));
135 }
136 }
std::chrono::system_clock::time_point start_time() const
@ SEQUENCE
Definition asn1_obj.h:42
@ OCTET_STRING
Definition asn1_obj.h:38

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

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

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

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

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.

128{ 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 123 of file tls_session.h.

123{ return m_ciphersuite; }

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

◆ decrypt() [1/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 102 of file tls_session.h.

104 {
105 return Session::decrypt(ctext.data(), ctext.size(), key);
106 }
static Session decrypt(const uint8_t ctext[], size_t ctext_size, const SymmetricKey &key)

◆ decrypt() [2/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 250 of file tls_session.cpp.

251 {
252 try
253 {
254 const size_t min_session_size = 48 + 4; // serious under-estimate
255 if(in_len < TLS_SESSION_CRYPT_OVERHEAD + min_session_size)
256 throw Decoding_Error("Encrypted session too short to be valid");
257
258 const uint8_t* magic = &in[0];
259 const uint8_t* key_name = magic + TLS_SESSION_CRYPT_MAGIC_LEN;
260 const uint8_t* key_seed = key_name + TLS_SESSION_CRYPT_KEY_NAME_LEN;
261 const uint8_t* aead_nonce = key_seed + TLS_SESSION_CRYPT_AEAD_KEY_SEED_LEN;
262 const uint8_t* ctext = aead_nonce + TLS_SESSION_CRYPT_AEAD_NONCE_LEN;
263 const size_t ctext_len = in_len - TLS_SESSION_CRYPT_HDR_LEN; // includes the tag
264
265 if(load_be<uint64_t>(magic, 0) != TLS_SESSION_CRYPT_MAGIC)
266 throw Decoding_Error("Missing expected magic numbers");
267
268 auto hmac = MessageAuthenticationCode::create_or_throw(TLS_SESSION_CRYPT_HMAC);
269 hmac->set_key(key);
270
271 // First derive and check the "key name"
272 std::vector<uint8_t> cmp_key_name(hmac->output_length());
273 hmac->update(TLS_SESSION_CRYPT_KEY_NAME);
274 hmac->final(cmp_key_name.data());
275
276 if(same_mem(cmp_key_name.data(), key_name, TLS_SESSION_CRYPT_KEY_NAME_LEN) == false)
277 throw Decoding_Error("Wrong key name for encrypted session");
278
279 hmac->update(key_seed, TLS_SESSION_CRYPT_AEAD_KEY_SEED_LEN);
280 const secure_vector<uint8_t> aead_key = hmac->final();
281
282 auto aead = AEAD_Mode::create_or_throw(TLS_SESSION_CRYPT_AEAD, DECRYPTION);
283 aead->set_key(aead_key);
284 aead->set_associated_data(in, TLS_SESSION_CRYPT_HDR_LEN);
285 aead->start(aead_nonce, TLS_SESSION_CRYPT_AEAD_NONCE_LEN);
286 secure_vector<uint8_t> buf(ctext, ctext + ctext_len);
287 aead->finish(buf, 0);
288 return Session(buf.data(), buf.size());
289 }
290 catch(std::exception& e)
291 {
292 throw Decoding_Error("Failed to decrypt serialized TLS session: " +
293 std::string(e.what()));
294 }
295 }
static std::unique_ptr< AEAD_Mode > create_or_throw(const std::string &algo, Cipher_Dir direction, const std::string &provider="")
Definition aead.cpp:50
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(const std::string &algo_spec, const std::string &provider="")
Definition mac.cpp:139
@ DECRYPTION
Definition cipher_mode.h:23
uint64_t load_be< uint64_t >(const uint8_t in[], size_t off)
Definition loadstor.h:217
bool same_mem(const T *p1, const T *p2, size_t n)
Definition mem_ops.h:217

References Botan::AEAD_Mode::create_or_throw(), Botan::MessageAuthenticationCode::create_or_throw(), Botan::DECRYPTION, Botan::load_be< uint64_t >(), Botan::same_mem(), and Session().

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

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

139 {
140 std::vector<uint8_t> peer_cert_bits;
141 for(size_t i = 0; i != m_peer_certs.size(); ++i)
142 peer_cert_bits += m_peer_certs[i].BER_encode();
143
144 return DER_Encoder()
145 .start_cons(SEQUENCE)
146 .encode(static_cast<size_t>(TLS_SESSION_PARAM_STRUCT_VERSION))
147 .encode(static_cast<size_t>(std::chrono::system_clock::to_time_t(m_start_time)))
148 .encode(static_cast<size_t>(m_version.major_version()))
149 .encode(static_cast<size_t>(m_version.minor_version()))
150 .encode(m_identifier, OCTET_STRING)
151 .encode(m_session_ticket, OCTET_STRING)
152 .encode(static_cast<size_t>(m_ciphersuite))
153 .encode(static_cast<size_t>(/*old compression method*/0))
154 .encode(static_cast<size_t>(m_connection_side))
155 .encode(static_cast<size_t>(/*old fragment size*/0))
156 .encode(m_extended_master_secret)
157 .encode(m_encrypt_then_mac)
158 .encode(m_master_secret, OCTET_STRING)
159 .encode(peer_cert_bits, OCTET_STRING)
160 .encode(ASN1_String(m_server_info.hostname(), UTF8_STRING))
161 .encode(ASN1_String(m_server_info.service(), UTF8_STRING))
162 .encode(static_cast<size_t>(m_server_info.port()))
163 .encode(ASN1_String(m_srp_identifier, UTF8_STRING))
164 .encode(static_cast<size_t>(m_srtp_profile))
165 .end_cons()
166 .get_contents();
167 }
uint8_t major_version() const
Definition tls_version.h:79
uint8_t minor_version() const
Definition tls_version.h:84
secure_vector< uint8_t > BER_encode(const Private_Key &key)
Definition pkcs8.cpp:139
@ UTF8_STRING
Definition asn1_obj.h:45

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

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

207 {
208 auto hmac = MessageAuthenticationCode::create_or_throw(TLS_SESSION_CRYPT_HMAC);
209 hmac->set_key(key);
210
211 // First derive the "key name"
212 std::vector<uint8_t> key_name(hmac->output_length());
213 hmac->update(TLS_SESSION_CRYPT_KEY_NAME);
214 hmac->final(key_name.data());
215 key_name.resize(TLS_SESSION_CRYPT_KEY_NAME_LEN);
216
217 std::vector<uint8_t> aead_nonce;
218 std::vector<uint8_t> key_seed;
219
220 rng.random_vec(aead_nonce, TLS_SESSION_CRYPT_AEAD_NONCE_LEN);
221 rng.random_vec(key_seed, TLS_SESSION_CRYPT_AEAD_KEY_SEED_LEN);
222
223 hmac->update(key_seed);
224 const secure_vector<uint8_t> aead_key = hmac->final();
225
226 secure_vector<uint8_t> bits = this->DER_encode();
227
228 // create the header
229 std::vector<uint8_t> buf;
230 buf.reserve(TLS_SESSION_CRYPT_OVERHEAD + bits.size());
231 buf.resize(TLS_SESSION_CRYPT_MAGIC_LEN);
232 store_be(TLS_SESSION_CRYPT_MAGIC, &buf[0]);
233 buf += key_name;
234 buf += key_seed;
235 buf += aead_nonce;
236
237 std::unique_ptr<AEAD_Mode> aead = AEAD_Mode::create_or_throw(TLS_SESSION_CRYPT_AEAD, ENCRYPTION);
238 BOTAN_ASSERT_NOMSG(aead->valid_nonce_length(TLS_SESSION_CRYPT_AEAD_NONCE_LEN));
239 BOTAN_ASSERT_NOMSG(aead->tag_size() == TLS_SESSION_CRYPT_AEAD_TAG_SIZE);
240 aead->set_key(aead_key);
241 aead->set_associated_data_vec(buf);
242 aead->start(aead_nonce);
243 aead->finish(bits, 0);
244
245 // append the ciphertext
246 buf += bits;
247 return buf;
248 }
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:68
secure_vector< uint8_t > DER_encode() const
void store_be(uint16_t in, uint8_t out[2])
Definition loadstor.h:438
@ ENCRYPTION
Definition cipher_mode.h:23

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_SQL::save(), and Botan::TLS::Session_Manager_In_Memory::save().

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

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

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

◆ 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.

183{ return m_server_info; }

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

◆ session_age()

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

Return how long this session has existed (in seconds)

Definition at line 174 of file tls_session.cpp.

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

◆ 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.

149{ return m_identifier; }

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

◆ 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.

178{ return m_session_ticket; }

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

◆ 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.

134{ return m_connection_side; }

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

◆ 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.

139{ return m_srp_identifier; }

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

◆ 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.

168{ return m_start_time; }

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

◆ supports_encrypt_then_mac()

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

Definition at line 158 of file tls_session.h.

158{ return m_encrypt_then_mac; }

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

◆ 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: