Botan 3.14.1
Crypto and TLS for C&
tls_handshake_io.h
Go to the documentation of this file.
1/*
2* TLS Handshake Serialization
3* (C) 2012,2014 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_TLS_HANDSHAKE_IO_H_
9#define BOTAN_TLS_HANDSHAKE_IO_H_
10
11#include <botan/tls_magic.h>
12#include <botan/tls_version.h>
13#include <chrono>
14#include <deque>
15#include <functional>
16#include <map>
17#include <optional>
18#include <set>
19#include <utility>
20#include <vector>
21
22namespace Botan::TLS {
23
25
26/**
27* Handshake IO Interface
28*
29* This interface abstracts over stream and datagram processing of handshake
30* messages. It receives individual records from the channel via `add_record` and provides a
31* sending interface via a callback function provided by the channel.
32*
33* Handshake message headers are parsed and removed in `get_next_record`. The
34* result is provided back to the channel via
35* `Handshake_State::get_next_handshake_msg`.
36*
37* `send` is used by individual handshake message implementations, which send
38* themselves, as well as both client and server to dispatch CCS messaged (and
39* Hello_Verify_Request in the server case). Before calling the `writer_fn`,
40* `format` is called to add the handshake message header (except for CCS).
41*
42* The buffer returned by `send` is used to update the transcript record hash
43* (where desired).
44*/
46 public:
48
49 virtual std::vector<uint8_t> send(const Handshake_Message& msg) = 0;
50
51 virtual std::vector<uint8_t> send_under_epoch(const Handshake_Message& msg, uint16_t epoch) = 0;
52
53#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
54 virtual std::vector<uint8_t> start_with_client_hello_from_downgrade(const Handshake_Message& client_hello) = 0;
55#endif
56
57 virtual bool timeout_check() = 0;
58
59 virtual std::optional<std::chrono::milliseconds> next_retransmission_timeout() const = 0;
60
61 virtual bool have_more_data() const = 0;
62
63 virtual std::vector<uint8_t> format(const std::vector<uint8_t>& handshake_msg,
64 Handshake_Type handshake_type) const = 0;
65
66 virtual void add_record(const uint8_t record[],
67 size_t record_len,
68 Record_Type type,
69 uint64_t sequence_number) = 0;
70
71 /**
72 * Returns (HANDSHAKE_NONE, std::vector<>()) if no message currently available
73 */
74 virtual std::pair<Handshake_Type, std::vector<uint8_t>> get_next_record(bool expecting_ccs,
75 size_t max_message_size) = 0;
76
77 Handshake_IO() = default;
78
79 Handshake_IO(const Handshake_IO&) = delete;
83
84 virtual ~Handshake_IO() = default;
85};
86
87/**
88* Handshake IO for stream-based handshakes
89*/
90class Stream_Handshake_IO final : public Handshake_IO {
91 public:
92 typedef std::function<void(Record_Type, const std::vector<uint8_t>&)> writer_fn;
93
94 explicit Stream_Handshake_IO(writer_fn writer) : m_send_hs(std::move(writer)) {}
95
97
98 bool timeout_check() override { return false; }
99
100 std::optional<std::chrono::milliseconds> next_retransmission_timeout() const override { return std::nullopt; }
101
102 bool have_more_data() const override { return !m_queue.empty() || m_ccs_received; }
103
104 std::vector<uint8_t> send(const Handshake_Message& msg) override;
105
106 std::vector<uint8_t> send_under_epoch(const Handshake_Message& msg, uint16_t epoch) override;
107
108#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
109 std::vector<uint8_t> start_with_client_hello_from_downgrade(const Handshake_Message& client_hello) override;
110#endif
111
112 std::vector<uint8_t> format(const std::vector<uint8_t>& handshake_msg,
113 Handshake_Type handshake_type) const override;
114
115 void add_record(const uint8_t record[], size_t record_len, Record_Type type, uint64_t sequence_number) override;
116
117 std::pair<Handshake_Type, std::vector<uint8_t>> get_next_record(bool expecting_ccs,
118 size_t max_message_size) override;
119
120 private:
121 std::deque<uint8_t> m_queue;
122 bool m_ccs_received = false;
123 writer_fn m_send_hs;
124};
125
126/**
127* Handshake IO for datagram-based handshakes
128*/
130 public:
131 using writer_fn = std::function<void(uint16_t, Record_Type, const std::vector<uint8_t>&)>;
132
133 // Lambda pointing to clock function (normally TLS::Callbacks::tls_current_monotonic_clock_ms)
134 using steady_clock_fn = std::function<uint64_t()>;
135
137 steady_clock_fn clock_ms,
139 uint16_t mtu,
140 uint64_t initial_timeout_ms,
141 uint64_t max_timeout_ms,
142 std::optional<size_t> max_retransmissions,
143 size_t max_handshake_msg_size,
144 bool is_server,
145 uint16_t initial_epoch = 0);
146
148
149 bool timeout_check() override;
150
151 std::optional<std::chrono::milliseconds> next_retransmission_timeout() const override;
152
153 bool have_more_data() const override;
154
155 /**
156 * @return the number of bytes currently claimed by partially received messages
157 */
158 size_t pending_reassembly_bytes() const { return m_pending_reassembly_bytes; }
159
160 std::vector<uint8_t> send(const Handshake_Message& msg) override;
161
162 std::vector<uint8_t> send_under_epoch(const Handshake_Message& msg, uint16_t epoch) override;
163
164#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
165 std::vector<uint8_t> start_with_client_hello_from_downgrade(const Handshake_Message& client_hello) override;
166#endif
167
168 std::vector<uint8_t> format(const std::vector<uint8_t>& handshake_msg,
169 Handshake_Type handshake_type) const override;
170
171 void add_record(const uint8_t record[], size_t record_len, Record_Type type, uint64_t sequence_number) override;
172
173 // Process previous-flight records after this IO object was retained by
174 // an active DTLS association for final-flight recovery.
175 void add_retransmitted_record(const uint8_t record[],
176 size_t record_len,
177 Record_Type type,
178 uint64_t sequence_number);
179
180 std::pair<Handshake_Type, std::vector<uint8_t>> get_next_record(bool expecting_ccs,
181 size_t max_message_size) override;
182
183 /**
184 * Enter FINISHED after channel activation. Intermediate outgoing flights
185 * are finalized implicitly when the peer's next handshake message is
186 * requested. The terminal-flight sender retains reactive replay behavior.
187 */
188 void finalize_handshake(bool retransmit_terminal_flight);
189
190 private:
191 void add_record(const uint8_t record[],
192 size_t record_len,
193 Record_Type record_type,
194 uint64_t record_sequence,
195 bool retransmitted_flight);
196
197 bool reassemble_retransmitted_fragment(const uint8_t fragment[],
198 size_t fragment_length,
199 size_t fragment_offset,
200 uint16_t epoch,
201 Handshake_Type msg_type,
202 size_t msg_length,
203 uint16_t message_seq);
204
205 bool process_previous_handshake_fragment(const uint8_t fragment[],
206 size_t fragment_length,
207 size_t fragment_offset,
208 uint16_t epoch,
209 Handshake_Type msg_type,
210 size_t msg_length,
211 uint16_t message_seq,
212 bool retransmitted_flight);
213
214 // Drop buffered messages left over from an earlier handshake, identified
215 // by an epoch below the most recently delivered one.
216 void discard_stale_epoch_messages();
217
218 /**
219 * Drop all partially received messages, eg once they can no longer
220 * become part of the handshake
221 */
222 void discard_pending_messages();
223
224 void retransmit_flight(size_t flight);
225 void retransmit_last_flight();
226 void replay_last_flight_for_peer();
227
228 // Index of the last completed outgoing flight, or nullopt when no
229 // flight has been sent yet.
230 std::optional<size_t> last_completed_flight_index() const;
231
232 // Whether this is a server that has yet to send a flight. Since a
233 // HelloVerifyRequest is not retained as one, that is exactly the window
234 // before a cookie has validated. Restricted to servers because a client
235 // legitimately receives a HelloRequest into a fresh IO that has not sent
236 // anything either.
237 bool server_awaiting_first_flight() const {
238 return m_is_server && m_flights.size() == 1 && m_flights.front().empty();
239 }
240
241 std::vector<uint8_t> format_fragment(const uint8_t fragment[],
242 size_t fragment_len,
243 uint32_t frag_offset,
244 uint32_t msg_len,
245 Handshake_Type type,
246 uint16_t msg_sequence) const;
247
248 std::vector<uint8_t> format_w_seq(const std::vector<uint8_t>& handshake_msg,
249 Handshake_Type handshake_type,
250 uint16_t msg_sequence) const;
251
252 std::vector<uint8_t> send_message(uint16_t msg_seq,
253 uint16_t epoch,
254 Handshake_Type msg_type,
255 const std::vector<uint8_t>& msg);
256
257 class Handshake_Reassembly final {
258 public:
259 void add_fragment(const uint8_t fragment[],
260 size_t fragment_length,
261 size_t fragment_offset,
262 uint16_t epoch,
263 Handshake_Type msg_type,
264 size_t msg_length);
265
266 // Set by the first fragment, which fixes the header metadata and
267 // (in Datagram_Handshake_IO) charges the reassembly budget.
268 bool initialized() const { return m_msg_type != Handshake_Type::None; }
269
270 bool complete() const;
271
272 // Whether a ClientHello fragment may replace what this slot holds:
273 // unauthenticated epoch-zero data of a message never completed.
274 bool superseded_by_client_hello(uint16_t epoch, Handshake_Type msg_type) const {
275 return msg_type == Handshake_Type::ClientHello && epoch == 0 && m_epoch == 0 && initialized() &&
276 !complete();
277 }
278
279 uint16_t epoch() const { return m_epoch; }
280
281 Handshake_Type msg_type() const { return m_msg_type; }
282
283 // 0 until the first fragment has set the declared msg_length.
284 size_t msg_length() const { return m_msg_length; }
285
286 std::pair<Handshake_Type, std::vector<uint8_t>> message() const;
287
288 private:
289 Handshake_Type m_msg_type = Handshake_Type::None;
290 size_t m_msg_length = 0;
291 size_t m_bytes_received = 0;
292 uint16_t m_epoch = 0;
293
294 // Reassembly buffer (sized to m_msg_length once known) and a parallel
295 // byte-mask marking which positions have already been seen.
296 std::vector<uint8_t> m_received_mask;
297 std::vector<uint8_t> m_message;
298 };
299
300 // Add a fragment to a reassembly slot, charging the slot's declared
301 // length against the pending-reassembly budget at its first fragment.
302 // Returns false, adding nothing, if the budget ceiling would be exceeded.
303 bool charged_add_fragment(Handshake_Reassembly& reassembly,
304 size_t ceiling,
305 const uint8_t fragment[],
306 size_t fragment_length,
307 size_t fragment_offset,
308 uint16_t epoch,
309 Handshake_Type msg_type,
310 size_t msg_length);
311
312 // Uncommit a reassembly buffer's bytes from the pending-reassembly budget.
313 void release_reassembly_bytes(const Handshake_Reassembly& reassembly);
314
315 struct Message_Info final {
316 Message_Info(uint16_t e, Handshake_Type mt, const std::vector<uint8_t>& msg) :
317 epoch(e), msg_type(mt), msg_bits(msg) {}
318
319 uint16_t epoch; // NOLINT(*non-private-member-variable*)
320 Handshake_Type msg_type; // NOLINT(*non-private-member-variable*)
321 std::vector<uint8_t> msg_bits; // NOLINT(*non-private-member-variable*)
322 };
323
324 class Connection_Sequence_Numbers& m_seqs;
325 std::map<uint16_t, Handshake_Reassembly> m_messages;
326 size_t m_pending_reassembly_bytes = 0;
327 std::set<uint16_t> m_ccs_epochs;
328
329 // A retransmitted final flight may deliver CCS and Finished in either
330 // order. Other terminal messages may themselves be fragmented.
331 std::optional<uint16_t> m_retransmitted_ccs_epoch;
332 std::optional<uint16_t> m_retransmitted_finished_epoch;
333 std::map<Handshake_Type, std::pair<uint16_t, Handshake_Reassembly>> m_retransmitted_messages;
334 std::vector<std::vector<uint16_t>> m_flights;
335 // Each entry records where in the corresponding flight a CCS was sent
336 // and the epoch under which it was transmitted.
337 std::vector<std::vector<std::pair<size_t, uint16_t>>> m_flight_ccs;
338 std::map<uint16_t, Message_Info> m_flight_data;
339
340 std::optional<std::pair<uint16_t, Handshake_Reassembly>> m_retransmitted_client_hello;
341 bool m_awaiting_cookie_client_hello = false;
342
343 // Set while answering a buffered duplicate ClientHello, so the reissued
344 // HelloVerifyRequest does not discard what the peer has sent since
345 bool m_recreating_hello_verify_request = false;
346 bool m_finished = false;
347 bool m_retransmit_terminal_flight = false;
348
349 uint64_t m_initial_timeout = 0;
350 uint64_t m_max_timeout = 0;
351
352 // Maximum timer-driven retransmissions of the current flight before the
353 // handshake is abandoned (nullopt unlimited). m_retransmit_count tracks the
354 // number fired for the in-flight wait; it resets to 0 whenever a new
355 // flight is sent (forward progress) and is incremented on each timeout.
356 std::optional<size_t> m_max_retransmissions = 0;
357 size_t m_retransmit_count = 0;
358
359 // Time the current flight was last written, unset until one has been.
360 // A caller's clock may legitimately read zero, so the absence of a write
361 // cannot be spelled as a reserved timestamp.
362 std::optional<uint64_t> m_last_write;
363
364 // Flight replays the peer has cued since the current flight was sent.
365 // Kept apart from the timer's own budget because the cue for it is
366 // unauthenticated. See replay_last_flight_for_peer.
367 size_t m_peer_replay_count = 0;
368
369 uint64_t m_next_timeout = 0;
370
371 uint16_t m_in_message_seq = 0;
372 uint16_t m_out_message_seq = 0;
373
374 // Epoch of the first delivered incoming message; its presence also
375 // guards format(), which is not the same as m_in_message_seq being
376 // non-zero once that counter wraps.
377 std::optional<uint16_t> m_first_delivered_epoch;
378
379 // Set once m_in_message_seq wraps, after which all handshake input is
380 // refused; see process_handshake_fragment.
381 bool m_in_message_seq_wrapped = false;
382
383 // Epoch in force when this handshake began. Records from the previous one
384 // sit at or below it, and a Finished has to sit above it.
385 uint16_t m_initial_epoch;
386
387 // Epoch of the most recently delivered incoming handshake message. Used
388 // to reject records held over from a previous handshake.
389 uint16_t m_last_delivered_epoch = 0;
390
391 writer_fn m_send_hs;
392 steady_clock_fn m_steady_clock_ms;
393 uint16_t m_mtu;
394 size_t m_max_handshake_msg_size;
395 size_t m_max_pending_reassembly;
396 bool m_is_server;
397};
398
399} // namespace Botan::TLS
400
401#endif
#define BOTAN_TEST_API
Definition api.h:41
std::function< uint64_t()> steady_clock_fn
std::function< void(uint16_t, Record_Type, const std::vector< uint8_t > &)> writer_fn
std::optional< std::chrono::milliseconds > next_retransmission_timeout() const override
Protocol_Version initial_record_version() const override
Datagram_Handshake_IO(writer_fn writer, steady_clock_fn clock_ms, class Connection_Sequence_Numbers &seq, uint16_t mtu, uint64_t initial_timeout_ms, uint64_t max_timeout_ms, std::optional< size_t > max_retransmissions, size_t max_handshake_msg_size, bool is_server, uint16_t initial_epoch=0)
Handshake_IO & operator=(Handshake_IO &&)=delete
virtual std::vector< uint8_t > send_under_epoch(const Handshake_Message &msg, uint16_t epoch)=0
Handshake_IO(const Handshake_IO &)=delete
virtual bool timeout_check()=0
virtual std::vector< uint8_t > send(const Handshake_Message &msg)=0
virtual std::optional< std::chrono::milliseconds > next_retransmission_timeout() const =0
virtual std::pair< Handshake_Type, std::vector< uint8_t > > get_next_record(bool expecting_ccs, size_t max_message_size)=0
Handshake_IO & operator=(const Handshake_IO &)=delete
virtual void add_record(const uint8_t record[], size_t record_len, Record_Type type, uint64_t sequence_number)=0
virtual Protocol_Version initial_record_version() const =0
Handshake_IO(Handshake_IO &&)=delete
virtual std::vector< uint8_t > format(const std::vector< uint8_t > &handshake_msg, Handshake_Type handshake_type) const =0
virtual ~Handshake_IO()=default
virtual bool have_more_data() const =0
bool have_more_data() const override
std::vector< uint8_t > send_under_epoch(const Handshake_Message &msg, uint16_t epoch) override
std::optional< std::chrono::milliseconds > next_retransmission_timeout() const override
std::vector< uint8_t > format(const std::vector< uint8_t > &handshake_msg, Handshake_Type handshake_type) const override
Protocol_Version initial_record_version() const override
std::function< void(Record_Type, const std::vector< uint8_t > &)> writer_fn
std::vector< uint8_t > send(const Handshake_Message &msg) override
std::pair< Handshake_Type, std::vector< uint8_t > > get_next_record(bool expecting_ccs, size_t max_message_size) override
void add_record(const uint8_t record[], size_t record_len, Record_Type type, uint64_t sequence_number) override