Botan  2.8.0
Crypto and TLS for C++11
tls_session.h
Go to the documentation of this file.
1 /*
2 * TLS Session
3 * (C) 2011-2012,2015 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7 
8 #ifndef BOTAN_TLS_SESSION_STATE_H_
9 #define BOTAN_TLS_SESSION_STATE_H_
10 
11 #include <botan/x509cert.h>
12 #include <botan/tls_version.h>
13 #include <botan/tls_ciphersuite.h>
14 #include <botan/tls_magic.h>
15 #include <botan/tls_server_info.h>
16 #include <botan/secmem.h>
17 #include <botan/symkey.h>
18 #include <chrono>
19 
20 namespace Botan {
21 
22 namespace TLS {
23 
24 /**
25 * Class representing a TLS session state
26 */
28  {
29  public:
30 
31  /**
32  * Uninitialized session
33  */
34  Session() :
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  {}
43 
44  /**
45  * New session (sets session start time)
46  */
47  Session(const std::vector<uint8_t>& session_id,
48  const secure_vector<uint8_t>& master_secret,
49  Protocol_Version version,
50  uint16_t ciphersuite,
51  Connection_Side side,
52  bool supports_extended_master_secret,
53  bool supports_encrypt_then_mac,
54  const std::vector<X509_Certificate>& peer_certs,
55  const std::vector<uint8_t>& session_ticket,
56  const Server_Information& server_info,
57  const std::string& srp_identifier,
58  uint16_t srtp_profile);
59 
60  /**
61  * Load a session from DER representation (created by DER_encode)
62  * @param ber DER representation buffer
63  * @param ber_len size of buffer in bytes
64  */
65  Session(const uint8_t ber[], size_t ber_len);
66 
67  /**
68  * Load a session from PEM representation (created by PEM_encode)
69  * @param pem PEM representation
70  */
71  explicit Session(const std::string& pem);
72 
73  /**
74  * Encode this session data for storage
75  * @warning if the master secret is compromised so is the
76  * session traffic
77  */
78  secure_vector<uint8_t> DER_encode() const;
79 
80  /**
81  * Encrypt a session (useful for serialization or session tickets)
82  */
83  std::vector<uint8_t> encrypt(const SymmetricKey& key,
84  RandomNumberGenerator& rng) const;
85 
86 
87  /**
88  * Decrypt a session created by encrypt
89  * @param ctext the ciphertext returned by encrypt
90  * @param ctext_size the size of ctext in bytes
91  * @param key the same key used by the encrypting side
92  */
93  static Session decrypt(const uint8_t ctext[],
94  size_t ctext_size,
95  const SymmetricKey& key);
96 
97  /**
98  * Decrypt a session created by encrypt
99  * @param ctext the ciphertext returned by encrypt
100  * @param key the same key used by the encrypting side
101  */
102  static inline Session decrypt(const std::vector<uint8_t>& ctext,
103  const SymmetricKey& key)
104  {
105  return Session::decrypt(ctext.data(), ctext.size(), key);
106  }
107 
108  /**
109  * Encode this session data for storage
110  * @warning if the master secret is compromised so is the
111  * session traffic
112  */
113  std::string PEM_encode() const;
114 
115  /**
116  * Get the version of the saved session
117  */
118  Protocol_Version version() const { return m_version; }
119 
120  /**
121  * Get the ciphersuite code of the saved session
122  */
123  uint16_t ciphersuite_code() const { return m_ciphersuite; }
124 
125  /**
126  * Get the ciphersuite info of the saved session
127  */
128  Ciphersuite ciphersuite() const { return Ciphersuite::by_id(m_ciphersuite); }
129 
130  /**
131  * Get which side of the connection the resumed session we are/were
132  * acting as.
133  */
134  Connection_Side side() const { return m_connection_side; }
135 
136  /**
137  * Get the SRP identity (if sent by the client in the initial handshake)
138  */
139  const std::string& srp_identifier() const { return m_srp_identifier; }
140 
141  /**
142  * Get the saved master secret
143  */
144  const secure_vector<uint8_t>& master_secret() const { return m_master_secret; }
145 
146  /**
147  * Get the session identifier
148  */
149  const std::vector<uint8_t>& session_id() const { return m_identifier; }
150 
151  /**
152  * Get the negotiated DTLS-SRTP algorithm (RFC 5764)
153  */
154  uint16_t dtls_srtp_profile() const { return m_srtp_profile; }
155 
156  bool supports_extended_master_secret() const { return m_extended_master_secret; }
157 
158  bool supports_encrypt_then_mac() const { return m_encrypt_then_mac; }
159 
160  /**
161  * Return the certificate chain of the peer (possibly empty)
162  */
163  const std::vector<X509_Certificate>& peer_certs() const { return m_peer_certs; }
164 
165  /**
166  * Get the wall clock time this session began
167  */
168  std::chrono::system_clock::time_point start_time() const { return m_start_time; }
169 
170  /**
171  * Return how long this session has existed (in seconds)
172  */
173  std::chrono::seconds session_age() const;
174 
175  /**
176  * Return the session ticket the server gave us
177  */
178  const std::vector<uint8_t>& session_ticket() const { return m_session_ticket; }
179 
180  /**
181  * @return information about the TLS server
182  */
183  const Server_Information& server_info() const { return m_server_info; }
184 
185  private:
186  enum { TLS_SESSION_PARAM_STRUCT_VERSION = 20160812 };
187 
188  std::chrono::system_clock::time_point m_start_time;
189 
190  std::vector<uint8_t> m_identifier;
191  std::vector<uint8_t> m_session_ticket; // only used by client side
192  secure_vector<uint8_t> m_master_secret;
193 
194  Protocol_Version m_version;
195  uint16_t m_ciphersuite;
196  Connection_Side m_connection_side;
197  uint16_t m_srtp_profile;
198  bool m_extended_master_secret;
199  bool m_encrypt_then_mac;
200 
201  std::vector<X509_Certificate> m_peer_certs;
202  Server_Information m_server_info; // optional
203  std::string m_srp_identifier; // optional
204  };
205 
206 }
207 
208 }
209 
210 #endif
const std::vector< uint8_t > & session_id() const
Definition: tls_session.h:149
uint16_t ciphersuite_code() const
Definition: tls_session.h:123
static Session decrypt(const uint8_t ctext[], size_t ctext_size, const SymmetricKey &key)
std::chrono::system_clock::time_point start_time() const
Definition: tls_session.h:168
int(* final)(unsigned char *, CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
Definition: bigint.h:891
const Server_Information & server_info() const
Definition: tls_session.h:183
uint16_t dtls_srtp_profile() const
Definition: tls_session.h:154
Connection_Side side() const
Definition: tls_session.h:134
std::string decrypt(const uint8_t input[], size_t input_len, const std::string &passphrase)
Definition: cryptobox.cpp:162
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:148
const std::vector< uint8_t > & session_ticket() const
Definition: tls_session.h:178
bool supports_extended_master_secret() const
Definition: tls_session.h:156
Definition: alg_id.cpp:13
Ciphersuite ciphersuite() const
Definition: tls_session.h:128
bool supports_encrypt_then_mac() const
Definition: tls_session.h:158
const secure_vector< uint8_t > & master_secret() const
Definition: tls_session.h:144
static Ciphersuite by_id(uint16_t suite)
static Session decrypt(const std::vector< uint8_t > &ctext, const SymmetricKey &key)
Definition: tls_session.h:102
const std::vector< X509_Certificate > & peer_certs() const
Definition: tls_session.h:163
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:88
Protocol_Version version() const
Definition: tls_session.h:118
std::string encrypt(const uint8_t input[], size_t input_len, const std::string &passphrase, RandomNumberGenerator &rng)
Definition: cryptobox.cpp:43
const std::string & srp_identifier() const
Definition: tls_session.h:139