Coverage Report

Created: 2020-03-26 13:53

/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
      * @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,
63
              RandomNumberGenerator& rng,
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
       */
75
      Channel(output_fn out,
76
              data_cb app_data_cb,
77
              alert_cb alert_cb,
78
              handshake_cb hs_cb,
79
              handshake_msg_cb hs_msg_cb,
80
              Session_Manager& session_manager,
81
              RandomNumberGenerator& rng,
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
2.43k
      void send_warning_alert(Alert::Type type) { send_alert(Alert(type, false)); }
140
141
      /**
142
      * Send a fatal alert
143
      */
144
7.77k
      void send_fatal_alert(Alert::Type type) { send_alert(Alert(type, true)); }
145
146
      /**
147
      * Send a close notification alert
148
      */
149
0
      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,
204
                                         Handshake_Type type,
205
                                         const std::vector<uint8_t>& contents,
206
                                         bool epoch0_restart) = 0;
207
208
      virtual void initiate_handshake(Handshake_State& state,
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
214
      virtual Handshake_State* new_handshake_state(class Handshake_IO* io) = 0;
215
216
      Handshake_State& create_handshake_state(Protocol_Version version);
217
218
      void inspect_handshake_message(const Handshake_Message& msg);
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
91.2k
      RandomNumberGenerator& rng() { return m_rng; }
235
236
29.5k
      Session_Manager& session_manager() { return m_session_manager; }
237
238
233k
      const Policy& policy() const { return m_policy; }
239
240
      bool save_session(const Session& session);
241
242
276k
      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
333k
      const Handshake_State* active_state() const { return m_active_state.get(); }
269
270
238k
      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