Botan 3.14.1
Crypto and TLS for C&
tls_channel_impl_12.h
Go to the documentation of this file.
1/*
2* TLS Channel - implementation for TLS 1.2
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_IMPL_12_H_
10#define BOTAN_TLS_CHANNEL_IMPL_12_H_
11
12#include <botan/tls_alert.h>
13#include <botan/tls_session_manager.h>
14#include <botan/internal/tls_channel_impl.h>
15#include <botan/internal/tls_connection_state_12.h>
16#include <map>
17#include <memory>
18#include <string>
19#include <vector>
20
21namespace Botan {
22
24
25namespace TLS {
26
27class Callbacks;
30class Handshake_IO;
31class Handshake_State;
33class Client_Hello_12;
34class Server_Hello_12;
35class Policy;
36
37/**
38* Generic interface for TLSv.12 endpoint
39*/
41 public:
42 /**
43 * Set up a new TLS session
44 *
45 * @param callbacks contains a set of callback function references
46 * required by the TLS endpoint.
47 * @param session_manager manages session state
48 * @param rng a random number generator
49 * @param policy specifies other connection policy information
50 * @param is_server whether this is a server session or not
51 * @param flavor specifies the TLS flavor (TLS or DTLS)
52 * @param io_buf_sz This many bytes of memory will
53 * be preallocated for the read and write buffers. Smaller
54 * values just mean reallocations and copies are more likely.
55 */
56 explicit Channel_Impl_12(const std::shared_ptr<Callbacks>& callbacks,
57 const std::shared_ptr<Session_Manager>& session_manager,
58 const std::shared_ptr<RandomNumberGenerator>& rng,
59 const std::shared_ptr<const Policy>& policy,
60 bool is_server,
62 size_t io_buf_sz = TLS::Channel::IO_BUF_DEFAULT_SIZE);
63
64 Channel_Impl_12(const Channel_Impl_12& other) = delete;
66 Channel_Impl_12& operator=(const Channel_Impl_12& other) = delete;
68
69 ~Channel_Impl_12() override;
70
71 size_t from_peer(std::span<const uint8_t> data) override;
72 void to_peer(std::span<const uint8_t> data) override;
73
74 /**
75 * Send a TLS alert message. If the alert is fatal, the internal
76 * state (keys, etc) will be reset.
77 * @param alert the Alert to send
78 */
79 void send_alert(const Alert& alert) override;
80
81 /**
82 * @return true iff the TLS handshake completed successfully
83 */
84 bool is_handshake_complete() const override;
85
86 /**
87 * @return true iff the connection is active for sending application data
88 */
89 bool is_active() const override;
90
91 std::optional<std::chrono::milliseconds> next_retransmission_timeout() const override;
92
93 /**
94 * @return true iff the connection has been definitely closed
95 */
96 bool is_closed() const override;
97
98 bool is_closed_for_reading() const override { return is_closed(); }
99
100 bool is_closed_for_writing() const override { return is_closed(); }
101
102 /**
103 * @return certificate chain of the peer (may be empty)
104 */
105 std::vector<X509_Certificate> peer_cert_chain() const override;
106
107 /**
108 * Note: Raw public key for authentication (RFC7250) is currently not
109 * implemented for TLS 1.2.
110 *
111 * @return raw public key of the peer (will be nullptr)
112 */
113 std::shared_ptr<const Public_Key> peer_raw_public_key() const override { return nullptr; }
114
115 std::optional<std::string> external_psk_identity() const override;
116
117 /**
118 * Key material export (RFC 5705)
119 * @param label a disambiguating label string
120 * @param context a per-association context value
121 * @param length the length of the desired key in bytes
122 * @return key of length bytes
123 */
124 SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override;
125
126 /**
127 * Attempt to renegotiate the session
128 * @param force_full_renegotiation if true, require a full renegotiation,
129 * otherwise allow session resumption
130 */
131 void renegotiate(bool force_full_renegotiation = false) override;
132
133 /**
134 * Attempt to update the session's traffic key material
135 * Note that this is possible with a TLS 1.3 channel, only.
136 *
137 * @param request_peer_update if true, require a reciprocal key update
138 */
139 void update_traffic_keys(bool request_peer_update = false) override;
140
141 /**
142 * @return true iff the counterparty supports the secure
143 * renegotiation extensions.
144 */
145 bool secure_renegotiation_supported() const override;
146
147 /**
148 * Perform a handshake timeout check. This does nothing unless this is a
149 * DTLS channel with a handshake in progress.
150 */
151 bool timeout_check() override;
152
153 protected:
154 const std::optional<Active_Connection_State_12>& active_state() const { return m_active_state; }
155
156 virtual void process_handshake_msg(Handshake_State& pending_state,
157 Handshake_Type type,
158 const std::vector<uint8_t>& contents,
159 bool epoch0_restart) = 0;
160
162 bool epoch0_restart = false,
163 std::optional<uint64_t> read_sequence_number = std::nullopt,
164 std::optional<uint64_t> write_sequence_number = std::nullopt);
165 virtual std::unique_ptr<Handshake_State> new_handshake_state(std::unique_ptr<Handshake_IO> io) = 0;
166
167 enum class TimerGeneration : bool {
170 };
171
172 /**
173 * Ask the user to asynchronously and transparently invoke the time-based
174 * retransmission mechanism.
175 */
177
179
180 void activate_session();
181
183
185
186 /* secure renegotiation handling */
187
188 // `fresh_handshake_mode` makes the check ignore m_active_state and treat
189 // the new ClientHello as starting a fresh handshake. Used for DTLS
190 // epoch-0 restart, where the peer has lost association state.
191 void secure_renegotiation_check(const Client_Hello_12* client_hello, bool fresh_handshake_mode = false);
192 void secure_renegotiation_check(const Server_Hello_12* server_hello);
193
194 std::vector<uint8_t> secure_renegotiation_data_for_client_hello() const;
195 std::vector<uint8_t> secure_renegotiation_data_for_server_hello() const;
196
197 RandomNumberGenerator& rng() { return *m_rng; }
198
199 Session_Manager& session_manager() { return *m_session_manager; }
200
201 const Policy& policy() const { return *m_policy; }
202
203 Callbacks& callbacks() const { return *m_callbacks; }
204
205 TLS_Flavor flavor() const { return m_flavor; }
206
208
209 /**
210 * Record the resumption handle this connection was established or resumed
211 * under, so that a fatal alert can invalidate it. The ServerHello session
212 * ID does not identify a ticket-backed session.
213 */
214 void note_resumption_handle(std::optional<Session_Handle> handle);
215
216 // Whether epoch-0 restart of an active DTLS association is permitted
217 // (only true for Server_Impl with a valid DTLS cookie secret)
218 virtual bool dtls_epoch0_restart_enabled() const { return false; }
219
220 virtual void initiate_handshake(Handshake_State& state, bool force_full_renegotiation) = 0;
221
222 /**
223 * The application protocol of the handshake currently in progress, which
224 * becomes the protocol of the connection once that handshake activates
225 */
226 virtual std::string negotiated_application_protocol() const = 0;
227
228 private:
229 void send_record(Record_Type record_type, const std::vector<uint8_t>& record);
230
231 void send_record_under_epoch(uint16_t epoch, Record_Type record_type, const std::vector<uint8_t>& record);
232
233 void send_record_array(uint16_t epoch, Record_Type record_type, const uint8_t input[], size_t length);
234
235 void write_record(
236 Connection_Cipher_State* cipher_state, uint16_t epoch, Record_Type type, const uint8_t input[], size_t length);
237
238 void reset_state();
239
240 // Collect the handles this connection's session is cached under, clearing
241 // the tracked one. Separate from the removal so that the caller can
242 // destroy the connection state first; see invalidate_sessions.
243 std::vector<Session_Handle> take_sessions_to_invalidate();
244
245 void invalidate_sessions(const std::vector<Session_Handle>& handles);
246
247 Connection_Sequence_Numbers& sequence_numbers() const;
248
249 std::shared_ptr<Connection_Cipher_State> read_cipher_state_epoch(uint16_t epoch) const;
250
251 std::shared_ptr<Connection_Cipher_State> write_cipher_state_epoch(uint16_t epoch) const;
252
253 const Handshake_State* pending_state() const { return m_pending_state.get(); }
254
255 /* methods to handle incoming traffic through Channel_Impl_12::receive_data. */
256 void process_handshake_ccs(const secure_vector<uint8_t>& record,
257 uint64_t record_sequence,
258 Record_Type record_type,
259 Protocol_Version record_version,
260 bool epoch0_restart);
261
262 void process_application_data(uint64_t req_no, const secure_vector<uint8_t>& record);
263
264 void process_alert(const secure_vector<uint8_t>& record, bool counts_for_useless_records);
265
266 const bool m_is_server;
267 const TLS_Flavor m_flavor;
268
269 /* callbacks */
270 std::shared_ptr<Callbacks> m_callbacks;
271
272 /* external state */
273 std::shared_ptr<Session_Manager> m_session_manager;
274 std::shared_ptr<const Policy> m_policy;
275 std::shared_ptr<RandomNumberGenerator> m_rng;
276
277 /* sequence number state */
278 std::unique_ptr<Connection_Sequence_Numbers> m_sequence_numbers;
279
280 /* pending handshake state (null when no handshake is in progress) */
281 std::unique_ptr<Handshake_State> m_pending_state;
282 size_t m_retransmission_timer_generation = 0;
283
284 /* handle under which this connection's session is cached, if any */
285 std::optional<Session_Handle> m_resumption_handle;
286
287 // Epochs in force when the pending handshake began. The read epoch says
288 // whether application data belongs to the old association or to the new,
289 // still-unauthenticated epoch; whether either epoch has moved decides
290 // whether an abandoned or refused handshake can be discarded or has to
291 // take the association with it.
292 struct Epochs_Before_Latest_Renegotiation final {
293 uint16_t read_epoch;
294 uint16_t write_epoch;
295 };
296
297 void abandon_timed_out_handshake();
298
299 // Whether neither epoch has moved since the pending handshake began, so
300 // dropping it cannot leave the channel describing two handshakes at once.
301 bool pending_handshake_epochs_unmoved() const;
302
303 // Drop the pending handshake and the epoch markers that describe it.
304 void clear_pending_handshake_state();
305
306 /*
307 A read cipher state together with the point at which it stopped being the
308 current epoch, in Callbacks::tls_current_monotonic_clock_ms units, if it has.
309
310 The two are stored together deliberately. Epoch numbers are not unique for
311 the lifetime of the channel: reset_active_association_state() rewinds them,
312 so a DTLS epoch-0 restart produces a second epoch 1. A retirement time held
313 apart from the state it describes therefore outlives it and gets applied to
314 the reused epoch, expiring a brand new cipher state.
315 */
316 struct Retained_Read_Cipher_State final {
317 std::shared_ptr<Connection_Cipher_State> state;
318 std::optional<uint64_t> retired_at;
319 };
320
321 /* cipher states for each epoch */
322 std::map<uint16_t, std::shared_ptr<Connection_Cipher_State>> m_write_cipher_states;
323 std::map<uint16_t, Retained_Read_Cipher_State> m_read_cipher_states;
324
325 /* I/O buffers */
326 secure_vector<uint8_t> m_writebuf;
327 secure_vector<uint8_t> m_readbuf;
328 secure_vector<uint8_t> m_record_buf;
329
330 bool m_has_been_closed;
331
332 // Set when a fatal alert was sent or received, which unlike close_notify
333 // destroys the connection state outright.
334 bool m_had_fatal_alert = false;
335
336 // Set when the peer sent close_notify, as opposed to us closing. Only
337 // then is later data from the peer something to ignore rather than reject.
338 bool m_peer_closed_connection = false;
339
340 // Set while the current pending handshake is a DTLS epoch-zero restart (a
341 // peer that lost its state beginning again at epoch zero, RFC 6347 4.2.8)
342 // that has not yet discarded the association it replaces. Its failure
343 // rolls back to that live association rather than tearing it down, so a
344 // stray epoch-zero record hitting a renegotiation must not be mistaken
345 // for one.
346 bool m_dtls_pending_is_epoch0_restart = false;
347
348 std::optional<Active_Connection_State_12> m_active_state;
349 // TODO(Botan4) remember to remove this when renegotiation support is dropped
350 std::optional<Epochs_Before_Latest_Renegotiation> m_epochs_before_latest_renegotiation;
351};
352
353} // namespace TLS
354
355} // namespace Botan
356
357#endif
RandomNumberGenerator & rng()
void change_cipher_spec_reader(Connection_Side side)
void inspect_handshake_message(const Handshake_Message &msg)
void maybe_arm_dtls_retransmission_timer(TimerGeneration generation_policy=TimerGeneration::Advance)
virtual std::string negotiated_application_protocol() const =0
void update_traffic_keys(bool request_peer_update=false) override
std::vector< uint8_t > secure_renegotiation_data_for_server_hello() const
bool is_handshake_complete() const override
Channel_Impl_12 & operator=(const Channel_Impl_12 &other)=delete
std::shared_ptr< const Public_Key > peer_raw_public_key() const override
virtual bool dtls_epoch0_restart_enabled() const
size_t from_peer(std::span< const uint8_t > data) override
Channel_Impl_12(const std::shared_ptr< Callbacks > &callbacks, const std::shared_ptr< Session_Manager > &session_manager, const std::shared_ptr< RandomNumberGenerator > &rng, const std::shared_ptr< const Policy > &policy, bool is_server, TLS_Flavor flavor, size_t io_buf_sz=TLS::Channel::IO_BUF_DEFAULT_SIZE)
bool is_closed_for_reading() const override
Channel_Impl_12 & operator=(Channel_Impl_12 &&other)=delete
Session_Manager & session_manager()
Handshake_State & create_handshake_state(Protocol_Version version, bool epoch0_restart=false, std::optional< uint64_t > read_sequence_number=std::nullopt, std::optional< uint64_t > write_sequence_number=std::nullopt)
const Policy & policy() const
void send_alert(const Alert &alert) override
virtual void initiate_handshake(Handshake_State &state, bool force_full_renegotiation)=0
std::vector< X509_Certificate > peer_cert_chain() const override
void to_peer(std::span< const uint8_t > data) override
bool is_closed_for_writing() const override
void note_resumption_handle(std::optional< Session_Handle > handle)
void change_cipher_spec_writer(Connection_Side side)
std::vector< uint8_t > secure_renegotiation_data_for_client_hello() const
void secure_renegotiation_check(const Client_Hello_12 *client_hello, bool fresh_handshake_mode=false)
const std::optional< Active_Connection_State_12 > & active_state() const
Channel_Impl_12(const Channel_Impl_12 &other)=delete
SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override
Channel_Impl_12(Channel_Impl_12 &&other)=delete
std::optional< std::string > external_psk_identity() const override
virtual std::unique_ptr< Handshake_State > new_handshake_state(std::unique_ptr< Handshake_IO > io)=0
std::optional< std::chrono::milliseconds > next_retransmission_timeout() const override
virtual void process_handshake_msg(Handshake_State &pending_state, Handshake_Type type, const std::vector< uint8_t > &contents, bool epoch0_restart)=0
bool secure_renegotiation_supported() const override
void renegotiate(bool force_full_renegotiation=false) override
Channel_Impl(const Channel_Impl &other)=delete
static constexpr size_t IO_BUF_DEFAULT_SIZE
Definition tls_channel.h:38
OctetString SymmetricKey
Definition symkey.h:153
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128