Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | List of all members
Botan::TLS::Session Class Reference

`#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_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, 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

Botan::TLS::Session::Session | ( |  | ) |
| inline

Uninitialized session

Definition at line 34 of file tls_session.h.

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 {}
Botan::CT::min
T min(T a, T b)
Definition: ct_utils.h:180

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

32 :
33 m_start_time(std::chrono::system_clock::now()),
34 m_identifier(session_identifier),
35 m_session_ticket(ticket),
36 m_master_secret(master_secret),
37 m_version(version),
38 m_ciphersuite(ciphersuite),
39 m_compression_method(compression_method),
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 }
Botan::TLS::Session::compression_method
uint8_t compression_method() const
Definition: tls_session.h:135
Botan::TLS::Session::ciphersuite
Ciphersuite ciphersuite() const
Definition: tls_session.h:130
Botan::TLS::Session::master_secret
const secure_vector< uint8_t > & master_secret() const
Definition: tls_session.h:151
Botan::TLS::Session::side
Connection_Side side() const
Definition: tls_session.h:141
Botan::TLS::Session::server_info
const Server_Information & server_info() const
Definition: tls_session.h:190
Botan::TLS::Session::version
Protocol_Version version() const
Definition: tls_session.h:120
Botan::TLS::Session::srp_identifier
const std::string & srp_identifier() const
Definition: tls_session.h:146

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

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

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

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

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

## Member Function Documentation

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); }
Botan::TLS::Ciphersuite::by_id
static Ciphersuite by_id(uint16_t suite)
Definition: tls_ciphersuite.cpp:43

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

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

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

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

static Session Botan::TLS::Session::decrypt | ( | const std::vector< uint8_t > & | 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 104 of file tls_session.h.

References decrypt().

106 {
107 return Session::decrypt(ctext.data(), ctext.size(), key);
108 }
Botan::TLS::Session::decrypt
static Session decrypt(const uint8_t ctext[], size_t ctext_size, const SymmetricKey &key)
Definition: tls_session.cpp:193

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

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

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

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

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

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.

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

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

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

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

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

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

Return how long this session has existed (in seconds)

Definition at line 165 of file tls_session.cpp.

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

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

156 { return m_identifier; }

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

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

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_Hello::Client_Hello().

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

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

175 { return m_start_time; }

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

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

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

Get the version of the saved session

Definition at line 120 of file tls_session.h.

120 { 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