Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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