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