Botan  2.18.1
Crypto and TLS for C++11
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 
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 */
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  */
75  Channel(output_fn out,
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 
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  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
std::function< void(Alert, const uint8_t[], size_t)> alert_cb
Definition: tls_channel.h:42
void send(const std::vector< unsigned char, Alloc > &val)
Definition: tls_channel.h:124
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
void send_warning_alert(Alert::Type type)
Definition: tls_channel.h:139
std::function< void(const uint8_t[], size_t)> output_fn
Definition: tls_channel.h:40
RandomNumberGenerator & rng()
Definition: tls_channel.h:234
MechanismType type
std::function< bool(const Session &)> handshake_cb
Definition: tls_channel.h:43
static size_t IO_BUF_DEFAULT_SIZE
Definition: tls_channel.h:45
Definition: alg_id.cpp:13
void send_fatal_alert(Alert::Type type)
Definition: tls_channel.h:144
std::function< void(const uint8_t[], size_t)> data_cb
Definition: tls_channel.h:41
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
int(* init)(CTX *)
Callbacks & callbacks() const
Definition: tls_channel.h:242
const Policy & policy() const
Definition: tls_channel.h:238
Session_Manager & session_manager()
Definition: tls_channel.h:236
std::function< void(const Handshake_Message &)> handshake_msg_cb
Definition: tls_channel.h:44