Botan  2.1.0
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_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,
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,
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,
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 
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
Callbacks & callbacks() const
Definition: tls_channel.h:241
std::function< void(Alert, const uint8_t[], size_t)> alert_cb
Definition: tls_channel.h:41
bool save_session(const Session &session) const
Definition: tls_channel.h:239
void send(const std::vector< unsigned char, Alloc > &val)
Definition: tls_channel.h:125
void send_warning_alert(Alert::Type type)
Definition: tls_channel.h:140
std::function< void(const uint8_t[], size_t)> output_fn
Definition: tls_channel.h:39
RandomNumberGenerator & rng()
Definition: tls_channel.h:233
MechanismType type
std::function< bool(const Session &)> handshake_cb
Definition: tls_channel.h:42
static size_t IO_BUF_DEFAULT_SIZE
Definition: tls_channel.h:44
Definition: alg_id.cpp:13
void send_fatal_alert(Alert::Type type)
Definition: tls_channel.h:145
RandomNumberGenerator & m_rng
Definition: ecdh.cpp:52
std::function< void(const uint8_t[], size_t)> data_cb
Definition: tls_channel.h:40
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
const Policy & policy() const
Definition: tls_channel.h:237
Session_Manager & session_manager()
Definition: tls_channel.h:235
std::function< void(const Handshake_Message &)> handshake_msg_cb
Definition: tls_channel.h:43