Botan 2.19.2
Crypto and TLS for C&
tls_channel.h
Go to the documentation of this file.
1/*
2* TLS Channel
3* (C) 2011,2012,2014,2015 Jack Lloyd
4* 2016 Matthias Gierlings
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_CHANNEL_H_
10#define BOTAN_TLS_CHANNEL_H_
11
12#include <botan/tls_session.h>
13#include <botan/tls_alert.h>
14#include <botan/tls_session_manager.h>
15#include <botan/tls_callbacks.h>
16#include <botan/x509cert.h>
17#include <functional>
18#include <vector>
19#include <string>
20#include <map>
21
22namespace Botan {
23
24namespace TLS {
25
26class Connection_Cipher_State;
27class Connection_Sequence_Numbers;
28class Handshake_State;
29class Handshake_Message;
30class Client_Hello;
31class Server_Hello;
32class Policy;
33
34/**
35* Generic interface for TLS endpoint
36*/
38 {
39 public:
40 typedef std::function<void (const uint8_t[], size_t)> output_fn;
41 typedef std::function<void (const uint8_t[], size_t)> data_cb;
42 typedef std::function<void (Alert, const uint8_t[], size_t)> alert_cb;
43 typedef std::function<bool (const Session&)> handshake_cb;
44 typedef std::function<void (const Handshake_Message&)> handshake_msg_cb;
45 static size_t IO_BUF_DEFAULT_SIZE;
46
47 /**
48 * Set up a new TLS session
49 *
50 * @param callbacks contains a set of callback function references
51 * required by the TLS endpoint.
52 * @param session_manager manages session state
53 * @param rng a random number generator
54 * @param policy specifies other connection policy information
55 * @param is_server whether this is a server session or not
56 * @param is_datagram whether this is a DTLS session
57 * @param io_buf_sz This many bytes of memory will
58 * be preallocated for the read and write buffers. Smaller
59 * values just mean reallocations and copies are more likely.
60 */
61 Channel(Callbacks& callbacks,
62 Session_Manager& session_manager,
64 const Policy& policy,
65 bool is_server,
66 bool is_datagram,
67 size_t io_buf_sz = IO_BUF_DEFAULT_SIZE);
68
69 /**
70 * DEPRECATED. This constructor is only provided for backward
71 * compatibility and should not be used in new implementations.
72 * (Not marked deprecated since it is only called internally, by
73 * other deprecated constructors)
74 */
76 data_cb app_data_cb,
78 handshake_cb hs_cb,
79 handshake_msg_cb hs_msg_cb,
80 Session_Manager& session_manager,
82 const Policy& policy,
83 bool is_server,
84 bool is_datagram,
85 size_t io_buf_sz = IO_BUF_DEFAULT_SIZE);
86
87 Channel(const Channel&) = delete;
88
89 Channel& operator=(const Channel&) = delete;
90
91 virtual ~Channel();
92
93 /**
94 * Inject TLS traffic received from counterparty
95 * @return a hint as the how many more bytes we need to process the
96 * current record (this may be 0 if on a record boundary)
97 */
98 size_t received_data(const uint8_t buf[], size_t buf_size);
99
100 /**
101 * Inject TLS traffic received from counterparty
102 * @return a hint as the how many more bytes we need to process the
103 * current record (this may be 0 if on a record boundary)
104 */
105 size_t received_data(const std::vector<uint8_t>& buf);
106
107 /**
108 * Inject plaintext intended for counterparty
109 * Throws an exception if is_active() is false
110 */
111 void send(const uint8_t buf[], size_t buf_size);
112
113 /**
114 * Inject plaintext intended for counterparty
115 * Throws an exception if is_active() is false
116 */
117 void send(const std::string& val);
118
119 /**
120 * Inject plaintext intended for counterparty
121 * Throws an exception if is_active() is false
122 */
123 template<typename Alloc>
124 void send(const std::vector<unsigned char, Alloc>& val)
125 {
126 send(val.data(), val.size());
127 }
128
129 /**
130 * Send a TLS alert message. If the alert is fatal, the internal
131 * state (keys, etc) will be reset.
132 * @param alert the Alert to send
133 */
134 void send_alert(const Alert& alert);
135
136 /**
137 * Send a warning alert
138 */
139 void send_warning_alert(Alert::Type type) { send_alert(Alert(type, false)); }
140
141 /**
142 * Send a fatal alert
143 */
144 void send_fatal_alert(Alert::Type type) { send_alert(Alert(type, true)); }
145
146 /**
147 * Send a close notification alert
148 */
149 void close() { send_warning_alert(Alert::CLOSE_NOTIFY); }
150
151 /**
152 * @return true iff the connection is active for sending application data
153 */
154 bool is_active() const;
155
156 /**
157 * @return true iff the connection has been definitely closed
158 */
159 bool is_closed() const;
160
161 /**
162 * @return certificate chain of the peer (may be empty)
163 */
164 std::vector<X509_Certificate> peer_cert_chain() const;
165
166 /**
167 * Key material export (RFC 5705)
168 * @param label a disambiguating label string
169 * @param context a per-association context value
170 * @param length the length of the desired key in bytes
171 * @return key of length bytes
172 */
173 SymmetricKey key_material_export(const std::string& label,
174 const std::string& context,
175 size_t length) const;
176
177 /**
178 * Attempt to renegotiate the session
179 * @param force_full_renegotiation if true, require a full renegotiation,
180 * otherwise allow session resumption
181 */
182 void renegotiate(bool force_full_renegotiation = false);
183
184 /**
185 * @return true iff the counterparty supports the secure
186 * renegotiation extensions.
187 */
188 bool secure_renegotiation_supported() const;
189
190 /**
191 * Perform a handshake timeout check. This does nothing unless
192 * this is a DTLS channel with a pending handshake state, in
193 * which case we check for timeout and potentially retransmit
194 * handshake packets.
195 */
196 bool timeout_check();
197
198 virtual std::string application_protocol() const = 0;
199
200 protected:
201
202 virtual void process_handshake_msg(const Handshake_State* active_state,
203 Handshake_State& pending_state,
205 const std::vector<uint8_t>& contents,
206 bool epoch0_restart) = 0;
207
209 bool force_full_renegotiation) = 0;
210
211 virtual std::vector<X509_Certificate>
212 get_peer_cert_chain(const Handshake_State& state) const = 0;
213
215
216 Handshake_State& create_handshake_state(Protocol_Version version);
217
219
220 void activate_session();
221
222 void change_cipher_spec_reader(Connection_Side side);
223
224 void change_cipher_spec_writer(Connection_Side side);
225
226 /* secure renegotiation handling */
227
228 void secure_renegotiation_check(const Client_Hello* client_hello);
229 void secure_renegotiation_check(const Server_Hello* server_hello);
230
231 std::vector<uint8_t> secure_renegotiation_data_for_client_hello() const;
232 std::vector<uint8_t> secure_renegotiation_data_for_server_hello() const;
233
234 RandomNumberGenerator& rng() { return m_rng; }
235
236 Session_Manager& session_manager() { return m_session_manager; }
237
238 const Policy& policy() const { return m_policy; }
239
240 bool save_session(const Session& session);
241
242 Callbacks& callbacks() const { return m_callbacks; }
243
244 void reset_active_association_state();
245
246 private:
247 void init(size_t io_buf_sze);
248
249 void send_record(uint8_t record_type, const std::vector<uint8_t>& record);
250
251 void send_record_under_epoch(uint16_t epoch, uint8_t record_type,
252 const std::vector<uint8_t>& record);
253
254 void send_record_array(uint16_t epoch, uint8_t record_type,
255 const uint8_t input[], size_t length);
256
257 void write_record(Connection_Cipher_State* cipher_state,
258 uint16_t epoch, uint8_t type, const uint8_t input[], size_t length);
259
260 void reset_state();
261
262 Connection_Sequence_Numbers& sequence_numbers() const;
263
264 std::shared_ptr<Connection_Cipher_State> read_cipher_state_epoch(uint16_t epoch) const;
265
266 std::shared_ptr<Connection_Cipher_State> write_cipher_state_epoch(uint16_t epoch) const;
267
268 const Handshake_State* active_state() const { return m_active_state.get(); }
269
270 const Handshake_State* pending_state() const { return m_pending_state.get(); }
271
272 /* methods to handle incoming traffic through Channel::receive_data. */
273 void process_handshake_ccs(const secure_vector<uint8_t>& record,
274 uint64_t record_sequence,
275 Record_Type record_type,
276 Protocol_Version record_version,
277 bool epoch0_restart);
278
279 void process_application_data(uint64_t req_no, const secure_vector<uint8_t>& record);
280
281 void process_alert(const secure_vector<uint8_t>& record);
282
283 const bool m_is_server;
284 const bool m_is_datagram;
285
286 /* callbacks */
287 std::unique_ptr<Compat_Callbacks> m_compat_callbacks;
288 Callbacks& m_callbacks;
289
290 /* external state */
291 Session_Manager& m_session_manager;
292 const Policy& m_policy;
293 RandomNumberGenerator& m_rng;
294
295 /* sequence number state */
296 std::unique_ptr<Connection_Sequence_Numbers> m_sequence_numbers;
297
298 /* pending and active connection states */
299 std::unique_ptr<Handshake_State> m_active_state;
300 std::unique_ptr<Handshake_State> m_pending_state;
301
302 /* cipher states for each epoch */
303 std::map<uint16_t, std::shared_ptr<Connection_Cipher_State>> m_write_cipher_states;
304 std::map<uint16_t, std::shared_ptr<Connection_Cipher_State>> m_read_cipher_states;
305
306 /* I/O buffers */
307 secure_vector<uint8_t> m_writebuf;
308 secure_vector<uint8_t> m_readbuf;
309 secure_vector<uint8_t> m_record_buf;
310
311 bool m_has_been_closed;
312 };
313
314}
315
316}
317
318#endif
void send(const std::vector< unsigned char, Alloc > &val)
Definition: tls_channel.h:124
virtual Handshake_State * new_handshake_state(class Handshake_IO *io)=0
virtual std::vector< X509_Certificate > get_peer_cert_chain(const Handshake_State &state) const =0
void send_warning_alert(Alert::Type type)
Definition: tls_channel.h:139
Callbacks & callbacks() const
Definition: tls_channel.h:242
virtual void initiate_handshake(Handshake_State &state, bool force_full_renegotiation)=0
virtual std::string application_protocol() const =0
void inspect_handshake_message(const Handshake_Message &msg)
std::function< bool(const Session &)> handshake_cb
Definition: tls_channel.h:43
virtual void process_handshake_msg(const Handshake_State *active_state, Handshake_State &pending_state, Handshake_Type type, const std::vector< uint8_t > &contents, bool epoch0_restart)=0
Channel & operator=(const Channel &)=delete
std::function< void(Alert, const uint8_t[], size_t)> alert_cb
Definition: tls_channel.h:42
Session_Manager & session_manager()
Definition: tls_channel.h:236
std::function< void(const Handshake_Message &)> handshake_msg_cb
Definition: tls_channel.h:44
Channel(const Channel &)=delete
void send_fatal_alert(Alert::Type type)
Definition: tls_channel.h:144
const Policy & policy() const
Definition: tls_channel.h:238
RandomNumberGenerator & rng()
Definition: tls_channel.h:234
std::function< void(const uint8_t[], size_t)> output_fn
Definition: tls_channel.h:40
static size_t IO_BUF_DEFAULT_SIZE
Definition: tls_channel.h:45
std::function< void(const uint8_t[], size_t)> data_cb
Definition: tls_channel.h:41
int(* init)(CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
void write_record(secure_vector< uint8_t > &output, uint8_t record_type, Protocol_Version version, uint64_t record_sequence, const uint8_t *message, size_t message_len, Connection_Cipher_State &cs, RandomNumberGenerator &rng)
Definition: tls_record.cpp:224
Definition: alg_id.cpp:13
MechanismType type