Botan  2.4.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 */
27 class BOTAN_PUBLIC_API(2,0) Session final
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_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  {}
44 
45  /**
46  * New session (sets session start time)
47  */
48  Session(const std::vector<uint8_t>& session_id,
49  const secure_vector<uint8_t>& master_secret,
50  Protocol_Version version,
51  uint16_t ciphersuite,
52  uint8_t compression_method,
53  Connection_Side side,
54  bool supports_extended_master_secret,
55  bool supports_encrypt_then_mac,
56  const std::vector<X509_Certificate>& peer_certs,
57  const std::vector<uint8_t>& session_ticket,
58  const Server_Information& server_info,
59  const std::string& srp_identifier,
60  uint16_t srtp_profile);
61 
62  /**
63  * Load a session from DER representation (created by DER_encode)
64  * @param ber DER representation buffer
65  * @param ber_len size of buffer in bytes
66  */
67  Session(const uint8_t ber[], size_t ber_len);
68 
69  /**
70  * Load a session from PEM representation (created by PEM_encode)
71  * @param pem PEM representation
72  */
73  explicit Session(const std::string& pem);
74 
75  /**
76  * Encode this session data for storage
77  * @warning if the master secret is compromised so is the
78  * session traffic
79  */
80  secure_vector<uint8_t> DER_encode() const;
81 
82  /**
83  * Encrypt a session (useful for serialization or session tickets)
84  */
85  std::vector<uint8_t> encrypt(const SymmetricKey& key,
86  RandomNumberGenerator& rng) const;
87 
88 
89  /**
90  * Decrypt a session created by encrypt
91  * @param ctext the ciphertext returned by encrypt
92  * @param ctext_size the size of ctext in bytes
93  * @param key the same key used by the encrypting side
94  */
95  static Session decrypt(const uint8_t ctext[],
96  size_t ctext_size,
97  const SymmetricKey& key);
98 
99  /**
100  * Decrypt a session created by encrypt
101  * @param ctext the ciphertext returned by encrypt
102  * @param key the same key used by the encrypting side
103  */
104  static inline Session decrypt(const std::vector<uint8_t>& ctext,
105  const SymmetricKey& key)
106  {
107  return Session::decrypt(ctext.data(), ctext.size(), key);
108  }
109 
110  /**
111  * Encode this session data for storage
112  * @warning if the master secret is compromised so is the
113  * session traffic
114  */
115  std::string PEM_encode() const;
116 
117  /**
118  * Get the version of the saved session
119  */
120  Protocol_Version version() const { return m_version; }
121 
122  /**
123  * Get the ciphersuite code of the saved session
124  */
125  uint16_t ciphersuite_code() const { return m_ciphersuite; }
126 
127  /**
128  * Get the ciphersuite info of the saved session
129  */
130  Ciphersuite ciphersuite() const { return Ciphersuite::by_id(m_ciphersuite); }
131 
132  /**
133  * Get the compression method used in the saved session
134  */
135  uint8_t compression_method() const { return m_compression_method; }
136 
137  /**
138  * Get which side of the connection the resumed session we are/were
139  * acting as.
140  */
141  Connection_Side side() const { return m_connection_side; }
142 
143  /**
144  * Get the SRP identity (if sent by the client in the initial handshake)
145  */
146  const std::string& srp_identifier() const { return m_srp_identifier; }
147 
148  /**
149  * Get the saved master secret
150  */
151  const secure_vector<uint8_t>& master_secret() const { return m_master_secret; }
152 
153  /**
154  * Get the session identifier
155  */
156  const std::vector<uint8_t>& session_id() const { return m_identifier; }
157 
158  /**
159  * Get the negotiated DTLS-SRTP algorithm (RFC 5764)
160  */
161  uint16_t dtls_srtp_profile() const { return m_srtp_profile; }
162 
163  bool supports_extended_master_secret() const { return m_extended_master_secret; }
164 
165  bool supports_encrypt_then_mac() const { return m_encrypt_then_mac; }
166 
167  /**
168  * Return the certificate chain of the peer (possibly empty)
169  */
170  const std::vector<X509_Certificate>& peer_certs() const { return m_peer_certs; }
171 
172  /**
173  * Get the wall clock time this session began
174  */
175  std::chrono::system_clock::time_point start_time() const { return m_start_time; }
176 
177  /**
178  * Return how long this session has existed (in seconds)
179  */
180  std::chrono::seconds session_age() const;
181 
182  /**
183  * Return the session ticket the server gave us
184  */
185  const std::vector<uint8_t>& session_ticket() const { return m_session_ticket; }
186 
187  /**
188  * @return information about the TLS server
189  */
190  const Server_Information& server_info() const { return m_server_info; }
191 
192  private:
193  enum { TLS_SESSION_PARAM_STRUCT_VERSION = 20160812};
194 
195  std::chrono::system_clock::time_point m_start_time;
196 
197  std::vector<uint8_t> m_identifier;
198  std::vector<uint8_t> m_session_ticket; // only used by client side
199  secure_vector<uint8_t> m_master_secret;
200 
201  Protocol_Version m_version;
202  uint16_t m_ciphersuite;
203  uint8_t m_compression_method;
204  Connection_Side m_connection_side;
205  uint16_t m_srtp_profile;
206  bool m_extended_master_secret;
207  bool m_encrypt_then_mac;
208 
209  std::vector<X509_Certificate> m_peer_certs;
210  Server_Information m_server_info; // optional
211  std::string m_srp_identifier; // optional
212  };
213 
214 }
215 
216 }
217 
218 #endif
const std::vector< uint8_t > & session_id() const
Definition: tls_session.h:156
uint16_t ciphersuite_code() const
Definition: tls_session.h:125
static Session decrypt(const uint8_t ctext[], size_t ctext_size, const SymmetricKey &key)
uint8_t compression_method() const
Definition: tls_session.h:135
std::chrono::system_clock::time_point start_time() const
Definition: tls_session.h:175
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
Definition: bigint.h:635
const Server_Information & server_info() const
Definition: tls_session.h:190
uint16_t dtls_srtp_profile() const
Definition: tls_session.h:161
Connection_Side side() const
Definition: tls_session.h:141
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:140
const std::vector< uint8_t > & session_ticket() const
Definition: tls_session.h:185
bool supports_extended_master_secret() const
Definition: tls_session.h:163
Definition: alg_id.cpp:13
Ciphersuite ciphersuite() const
Definition: tls_session.h:130
bool supports_encrypt_then_mac() const
Definition: tls_session.h:165
const secure_vector< uint8_t > & master_secret() const
Definition: tls_session.h:151
static Ciphersuite by_id(uint16_t suite)
static Session decrypt(const std::vector< uint8_t > &ctext, const SymmetricKey &key)
Definition: tls_session.h:104
const std::vector< X509_Certificate > & peer_certs() const
Definition: tls_session.h:170
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:88
Protocol_Version version() const
Definition: tls_session.h:120
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:146