Coverage Report

Created: 2021-05-04 09:02

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