Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::Datagram_Handshake_IO Class Referencefinal

#include <tls_handshake_io.h>

Inheritance diagram for Botan::TLS::Datagram_Handshake_IO:
Botan::TLS::Handshake_IO

Public Types

using steady_clock_fn = std::function<uint64_t()>
using writer_fn = std::function<void(uint16_t, Record_Type, const std::vector<uint8_t>&)>

Public Member Functions

void add_record (const uint8_t record[], size_t record_len, Record_Type type, uint64_t sequence_number) override
void add_retransmitted_record (const uint8_t record[], size_t record_len, Record_Type type, uint64_t sequence_number)
 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)
void finalize_handshake (bool retransmit_terminal_flight)
std::vector< uint8_t > format (const std::vector< uint8_t > &handshake_msg, Handshake_Type handshake_type) const override
std::pair< Handshake_Type, std::vector< uint8_t > > get_next_record (bool expecting_ccs, size_t max_message_size) override
bool have_more_data () const override
Protocol_Version initial_record_version () const override
std::optional< std::chrono::milliseconds > next_retransmission_timeout () const override
size_t pending_reassembly_bytes () const
std::vector< uint8_t > send (const Handshake_Message &msg) override
std::vector< uint8_t > send_under_epoch (const Handshake_Message &msg, uint16_t epoch) override
bool timeout_check () override

Detailed Description

Handshake IO for datagram-based handshakes

Definition at line 129 of file tls_handshake_io.h.

Member Typedef Documentation

◆ steady_clock_fn

using Botan::TLS::Datagram_Handshake_IO::steady_clock_fn = std::function<uint64_t()>

Definition at line 134 of file tls_handshake_io.h.

◆ writer_fn

using Botan::TLS::Datagram_Handshake_IO::writer_fn = std::function<void(uint16_t, Record_Type, const std::vector<uint8_t>&)>

Definition at line 131 of file tls_handshake_io.h.

Constructor & Destructor Documentation

◆ Datagram_Handshake_IO()

Botan::TLS::Datagram_Handshake_IO::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 )

Definition at line 229 of file tls_handshake_io.cpp.

238 :
239 m_seqs(seq),
240 m_flights(1),
241 m_flight_ccs(1),
242 m_initial_timeout(initial_timeout_ms),
243 m_max_timeout(max_timeout_ms),
244 m_max_retransmissions(max_retransmissions),
245 m_initial_epoch(initial_epoch),
246 m_last_delivered_epoch(initial_epoch),
247 m_send_hs(std::move(writer)),
248 m_steady_clock_ms(std::move(steady_clock_ms)),
249 m_mtu(mtu),
250 m_max_handshake_msg_size(max_handshake_msg_size),
251 m_max_pending_reassembly(max_pending_reassembly(m_max_handshake_msg_size)),
252 m_is_server(is_server) {}

Member Function Documentation

◆ add_record()

void Botan::TLS::Datagram_Handshake_IO::add_record ( const uint8_t record[],
size_t record_len,
Record_Type type,
uint64_t sequence_number )
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 427 of file tls_handshake_io.cpp.

430 {
431 add_record(record, record_len, record_type, record_sequence, false);
432}
void add_record(const uint8_t record[], size_t record_len, Record_Type type, uint64_t sequence_number) override

References add_record().

Referenced by add_record(), and add_retransmitted_record().

◆ add_retransmitted_record()

void Botan::TLS::Datagram_Handshake_IO::add_retransmitted_record ( const uint8_t record[],
size_t record_len,
Record_Type type,
uint64_t sequence_number )

Definition at line 434 of file tls_handshake_io.cpp.

437 {
438 add_record(record, record_len, record_type, record_sequence, true);
439}

References add_record().

◆ finalize_handshake()

void Botan::TLS::Datagram_Handshake_IO::finalize_handshake ( bool retransmit_terminal_flight)

Enter FINISHED after channel activation. Intermediate outgoing flights are finalized implicitly when the peer's next handshake message is requested. The terminal-flight sender retains reactive replay behavior.

Definition at line 357 of file tls_handshake_io.cpp.

357 {
358 // Keep an empty trailing flight to mean "we are waiting for the peer".
359 // Retransmission then replays the previous, completed flight instead of
360 // appending to it.
361 if(!m_flights.rbegin()->empty()) {
362 m_flights.emplace_back();
363 m_flight_ccs.emplace_back();
364 }
365
366 // RFC 6347 4.2.4: "Once the messages have been sent, the implementation
367 // then enters the FINISHED state if this is the last flight in the
368 // handshake." Keep the flight for reactive replay when the peer
369 // retransmits, but do not arm a proactive retransmission timer.
370 m_finished = true;
371 m_retransmit_terminal_flight = retransmit_terminal_flight;
372
373 // Messages of any later handshake are reassembled by a new Handshake_IO
374 discard_pending_messages();
375}

◆ format()

std::vector< uint8_t > Botan::TLS::Datagram_Handshake_IO::format ( const std::vector< uint8_t > & handshake_msg,
Handshake_Type handshake_type ) const
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 1091 of file tls_handshake_io.cpp.

1091 {
1092 // Formats the message just delivered, so the guard is that one exists, not
1093 // that the counter is non-zero. Those differ once m_in_message_seq wraps,
1094 // where the subtraction wraps to 65535 of its own accord, which is the
1095 // right sequence number for that message.
1096 BOTAN_ASSERT_NOMSG(m_first_delivered_epoch.has_value());
1097 return format_w_seq(msg, type, static_cast<uint16_t>(m_in_message_seq - 1));
1098}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82

References BOTAN_ASSERT_NOMSG.

◆ get_next_record()

std::pair< Handshake_Type, std::vector< uint8_t > > Botan::TLS::Datagram_Handshake_IO::get_next_record ( bool expecting_ccs,
size_t max_message_size )
overridevirtual

Returns (HANDSHAKE_NONE, std::vector<>()) if no message currently available

Implements Botan::TLS::Handshake_IO.

Definition at line 879 of file tls_handshake_io.cpp.

880 {
881 // Expecting a message means the last flight is concluded
882 if(!m_flights.rbegin()->empty()) {
883 m_flights.emplace_back();
884 m_flight_ccs.emplace_back();
885 }
886
887 if(expecting_ccs) {
888 // CCS is expected under the epoch the peer's handshake messages have
889 // been arriving on, and always follows at least one delivered message.
890 if(m_first_delivered_epoch.has_value() && m_ccs_epochs.contains(*m_first_delivered_epoch)) {
891 return std::make_pair(Handshake_Type::HandshakeCCS, std::vector<uint8_t>());
892 }
893 return std::make_pair(Handshake_Type::None, std::vector<uint8_t>());
894 }
895
896 auto i = m_messages.find(m_in_message_seq);
897
898 if(i == m_messages.end() || !i->second.complete()) {
899 // Nothing in sequence to make progress with. A complete ClientHello
900 // buffered from an earlier sequence number is delivered only here, since
901 // delivering it ahead of an in-sequence message makes that message look
902 // like trailing data to the caller's have_more_data() check.
903 if(!m_retransmitted_client_hello.has_value() || !m_retransmitted_client_hello->second.complete()) {
904 return std::make_pair(Handshake_Type::None, std::vector<uint8_t>());
905 }
906
907 /*
908 This ClientHello is either a retransmission of the one the pending
909 HelloVerifyRequest answered or the start of another handshake. Nothing a
910 server has sent so far is retained (RFC 6347 3.2.1 keeps the
911 HelloVerifyRequest stateless), so the exchange simply begins again from
912 it: the sequence numbers are seated at this ClientHello, which also
913 recovers from ClientHellos that never validated having advanced them.
914 Only the slot after it can hold anything of the peer's, namely the
915 cookie-bearing ClientHello it may already be sending; everything else
916 buffered is stale.
917 */
918 const uint16_t seq = m_retransmitted_client_hello->first;
919
920 for(auto s = m_messages.begin(); s != m_messages.end();) {
921 if(s->first != static_cast<uint16_t>(seq + 1)) {
922 release_reassembly_bytes(s->second);
923 s = m_messages.erase(s);
924 } else {
925 ++s;
926 }
927 }
928
929 m_in_message_seq = seq;
930 m_recreating_hello_verify_request = true;
931 i = m_messages.insert_or_assign(seq, std::move(m_retransmitted_client_hello->second)).first;
932 m_retransmitted_client_hello.reset();
933 }
934
935 m_in_message_seq += 1;
936 if(m_in_message_seq == 0) {
937 m_in_message_seq_wrapped = true;
938 }
939
940 if(!m_first_delivered_epoch.has_value()) {
941 m_first_delivered_epoch = i->second.epoch();
942 }
943
944 auto result = i->second.message();
945
946 if(result.first == Handshake_Type::ClientHello) {
947 m_awaiting_cookie_client_hello = false;
948
949 // RFC 6347 4.2.4 (as corrected by erratum 5186): "the server MUST use the
950 // message_seq in the ClientHello as the message_seq in the
951 // HelloVerifyRequest" and "the server MUST use the message_seq in the
952 // ClientHello as the message_seq in its initial ServerHello". Until a
953 // flight has been sent, the outgoing counter therefore follows the
954 // ClientHello just delivered.
955 if(server_awaiting_first_flight()) {
956 m_out_message_seq = static_cast<uint16_t>(m_in_message_seq - 1);
957 }
958
959 // The ClientHello we were waiting for arrived, so a buffered duplicate of
960 // an earlier one has nothing left to tell us.
961 if(m_retransmitted_client_hello.has_value()) {
962 release_reassembly_bytes(m_retransmitted_client_hello->second);
963 m_retransmitted_client_hello.reset();
964 }
965 }
966
967 const uint16_t delivered_epoch = i->second.epoch();
968
969 release_reassembly_bytes(i->second);
970 m_messages.erase(i);
971
972 if(delivered_epoch > m_last_delivered_epoch) {
973 m_last_delivered_epoch = delivered_epoch;
974 discard_stale_epoch_messages();
975 }
976
977 return result;
978}

References Botan::TLS::ClientHello, Botan::TLS::HandshakeCCS, and Botan::TLS::None.

◆ have_more_data()

bool Botan::TLS::Datagram_Handshake_IO::have_more_data ( ) const
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 348 of file tls_handshake_io.cpp.

348 {
349 // Future or incomplete fragments remain buffered, but only a complete
350 // next-in-sequence message is trailing handshake data. A buffered duplicate
351 // ClientHello is not: it carries nothing the peer has not already sent, and
352 // get_next_record only reaches for it when there is no in-sequence message.
353 const auto next = m_messages.find(m_in_message_seq);
354 return next != m_messages.end() && next->second.complete();
355}

◆ initial_record_version()

Protocol_Version Botan::TLS::Datagram_Handshake_IO::initial_record_version ( ) const
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 254 of file tls_handshake_io.cpp.

254 {
255 return Protocol_Version::DTLS_V12;
256}

◆ next_retransmission_timeout()

std::optional< std::chrono::milliseconds > Botan::TLS::Datagram_Handshake_IO::next_retransmission_timeout ( ) const
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 402 of file tls_handshake_io.cpp.

402 {
403 if(m_finished) {
404 return std::nullopt;
405 }
406
407 // Without an outgoing flight there is nothing timeout_check() could retransmit.
408 if(!m_last_write.has_value() || !last_completed_flight_index().has_value()) {
409 return std::nullopt;
410 }
411
412 const uint64_t ms_since_write = m_steady_clock_ms() - m_last_write.value();
413 if(ms_since_write >= m_next_timeout) {
414 return std::chrono::milliseconds(0);
415 }
416
417 // BoringSSL reports a sub-15ms remainder as zero (ssl/d1_lib.cc
418 // DTLSTimer::MicrosecondsRemaining) to absorb divergence with caller
419 // scheduling; BoGo's DTLS-Retransmit-Fudge test requires it. The cap keeps
420 // the fudge from swallowing the very short timers some tests configure.
421 const uint64_t fudge_ms = std::min<uint64_t>(15, m_initial_timeout / 2);
422 const uint64_t remaining_ms = m_next_timeout - ms_since_write;
423
424 return std::chrono::milliseconds(remaining_ms <= fudge_ms ? 0 : remaining_ms);
425}

Referenced by timeout_check().

◆ pending_reassembly_bytes()

size_t Botan::TLS::Datagram_Handshake_IO::pending_reassembly_bytes ( ) const
inline
Returns
the number of bytes currently claimed by partially received messages

Definition at line 158 of file tls_handshake_io.h.

158{ return m_pending_reassembly_bytes; }

◆ send()

std::vector< uint8_t > Botan::TLS::Datagram_Handshake_IO::send ( const Handshake_Message & msg)
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 1100 of file tls_handshake_io.cpp.

1100 {
1101 return this->send_under_epoch(msg, m_seqs.current_write_epoch());
1102}
std::vector< uint8_t > send_under_epoch(const Handshake_Message &msg, uint16_t epoch) override

References send_under_epoch().

◆ send_under_epoch()

std::vector< uint8_t > Botan::TLS::Datagram_Handshake_IO::send_under_epoch ( const Handshake_Message & msg,
uint16_t epoch )
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 1104 of file tls_handshake_io.cpp.

1104 {
1105 const std::vector<uint8_t> msg_bits = msg.serialize();
1106 const Handshake_Type msg_type = msg.type();
1107
1108 if(msg_type == Handshake_Type::HandshakeCCS) {
1109 m_flight_ccs.rbegin()->emplace_back(m_flights.rbegin()->size(), epoch);
1110 m_send_hs(epoch, Record_Type::ChangeCipherSpec, msg_bits);
1111 return {}; // not included in handshake hashes
1112 } else if(msg_type == Handshake_Type::HelloVerifyRequest) {
1113 // RFC 6347 3.2.1: "Note that timeout and retransmission do not apply to
1114 // the HelloVerifyRequest, because this would require creating state on
1115 // the server." So it is not retained as a flight, and a repeated
1116 // ClientHello simply produces it again. get_next_record seated the
1117 // outgoing counter at the ClientHello being answered, so this carries
1118 // that ClientHello's message_seq (RFC 6347 4.2.4, erratum 5186).
1119 const uint16_t msg_seq = m_out_message_seq++;
1120
1121 // A ClientHello carrying the cookie cannot have been sent yet, so
1122 // anything received so far is useless and must not stay allocated
1123 if(!m_recreating_hello_verify_request) {
1124 discard_pending_messages();
1125 }
1126 m_awaiting_cookie_client_hello = true;
1127 m_recreating_hello_verify_request = false;
1128 send_message(msg_seq, epoch, msg_type, msg_bits);
1129 return {};
1130 }
1131
1132 m_flights.rbegin()->push_back(m_out_message_seq);
1133 m_flight_data.insert_or_assign(m_out_message_seq, Message_Info(epoch, msg_type, msg_bits));
1134
1135 m_out_message_seq += 1;
1136 m_last_write = m_steady_clock_ms();
1137 m_next_timeout = m_initial_timeout;
1138 // Sending a new flight is forward progress: reset the give-up counter so the
1139 // retransmission budget applies per flight, not across the whole handshake.
1140 m_retransmit_count = 0;
1141 m_peer_replay_count = 0;
1142
1143 return send_message(m_out_message_seq - 1, epoch, msg_type, msg_bits);
1144}

References Botan::TLS::ChangeCipherSpec, Botan::TLS::HandshakeCCS, Botan::TLS::HelloVerifyRequest, Botan::TLS::Handshake_Message::serialize(), and Botan::TLS::Handshake_Message::type().

Referenced by send().

◆ timeout_check()

bool Botan::TLS::Datagram_Handshake_IO::timeout_check ( )
overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 377 of file tls_handshake_io.cpp.

377 {
378 const auto timeout = next_retransmission_timeout();
379 if(!timeout || timeout->count() > 0) {
380 return false;
381 }
382
383 // The retransmit timer has expired. Count this attempt and, once the
384 // configured cap is reached, abandon the handshake rather than retransmit
385 // forever. RFC 6347 4.2.4.1 gives the backoff schedule but states no
386 // condition for giving up, so the cap is local policy, not a requirement.
387 // No alert is sent - the peer is by definition unresponsive.
388 m_retransmit_count += 1;
389 if(m_max_retransmissions.has_value() && m_retransmit_count > m_max_retransmissions.value()) {
390 throw TLS_Exception(Alert::None, "DTLS handshake timed out: maximum retransmissions exceeded");
391 }
392
393 // retransmit_last_flight re-anchors m_last_write. Without that, once
394 // m_next_timeout saturates at m_max_timeout the elapsed time keeps growing
395 // and every subsequent poll fires another retransmission.
396 retransmit_last_flight();
397
398 m_next_timeout = std::min(2 * m_next_timeout, m_max_timeout);
399 return true;
400}
std::optional< std::chrono::milliseconds > next_retransmission_timeout() const override

References next_retransmission_timeout().


The documentation for this class was generated from the following files: