Botan::TLS::Datagram_Handshake_IO Class Reference

#include <tls_handshake_io.h>

Inheritance diagram for Botan::TLS::Datagram_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, 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
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 128 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 133 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 130 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,
		uint16_t	initial_epoch = 0 )

Definition at line 193 of file tls_handshake_io.cpp.

                                                                     :
      m_seqs(seq),
      m_flights(1),
      m_flight_ccs(1),
      m_initial_timeout(initial_timeout_ms),
      m_max_timeout(max_timeout_ms),
      m_max_retransmissions(max_retransmissions),
      m_initial_epoch(initial_epoch),
      m_last_delivered_epoch(initial_epoch),
      m_send_hs(std::move(writer)),
      m_steady_clock_ms(std::move(steady_clock_ms)),
      m_mtu(mtu),
      m_max_handshake_msg_size(max_handshake_msg_size),
      m_max_pending_reassembly(max_pending_reassembly(m_max_handshake_msg_size)) {}

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 374 of file tls_handshake_io.cpp.

                                                                 {
   add_record(record, record_len, record_type, record_sequence, false);
}

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 381 of file tls_handshake_io.cpp.

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

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 306 of file tls_handshake_io.cpp.

                                                                              {
   // Keep an empty trailing flight to mean "we are waiting for the peer".
   // Retransmission then replays the previous, completed flight instead of
   // appending to it.
   if(!m_flights.rbegin()->empty()) {
      m_flights.emplace_back();
      m_flight_ccs.emplace_back();
   }
 
   // RFC 6347 4.2.4: "Once the messages have been sent, the implementation
   // then enters the FINISHED state if this is the last flight in the
   // handshake." Keep the flight for reactive replay when the peer
   // retransmits, but do not arm a proactive retransmission timer.
   m_finished = true;
   m_retransmit_terminal_flight = retransmit_terminal_flight;
}

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 887 of file tls_handshake_io.cpp.

                                                                                                         {
   // Formats the message just delivered, so the guard is that one exists, not
   // that the counter is non-zero. Those differ once m_in_message_seq wraps,
   // where the subtraction wraps to 65535 of its own accord, which is the
   // right sequence number for that message.
   BOTAN_ASSERT_NOMSG(m_first_delivered_epoch.has_value());
   return format_w_seq(msg, type, static_cast<uint16_t>(m_in_message_seq - 1));
}

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 734 of file tls_handshake_io.cpp.

                                                                                                 {
   // Expecting a message means the last flight is concluded
   if(!m_flights.rbegin()->empty()) {
      m_flights.emplace_back();
      m_flight_ccs.emplace_back();
   }
 
   if(expecting_ccs) {
      // CCS is expected under the epoch the peer's handshake messages have
      // been arriving on, and always follows at least one delivered message.
      if(m_first_delivered_epoch.has_value() && m_ccs_epochs.contains(*m_first_delivered_epoch)) {
         return std::make_pair(Handshake_Type::HandshakeCCS, std::vector<uint8_t>());
      }
      return std::make_pair(Handshake_Type::None, std::vector<uint8_t>());
   }
 
   if(m_retransmitted_client_hello.has_value() && m_retransmitted_client_hello->second.complete()) {
      auto result = m_retransmitted_client_hello->second.message();
      release_reassembly_bytes(m_retransmitted_client_hello->second);
      m_retransmitted_client_hello.reset();
      m_recreating_hello_verify_request = true;
      return result;
   }
 
   auto i = m_messages.find(m_in_message_seq);
 
   if(i == m_messages.end() || !i->second.complete()) {
      return std::make_pair(Handshake_Type::None, std::vector<uint8_t>());
   }
 
   m_in_message_seq += 1;
   if(m_in_message_seq == 0) {
      m_in_message_seq_wrapped = true;
   }
 
   if(!m_first_delivered_epoch.has_value()) {
      m_first_delivered_epoch = i->second.epoch();
   }
 
   auto result = i->second.message();
 
   if(result.first == Handshake_Type::ClientHello) {
      m_awaiting_cookie_client_hello = false;
   }
 
   const uint16_t delivered_epoch = i->second.epoch();
 
   release_reassembly_bytes(i->second);
   m_messages.erase(i);
 
   if(delivered_epoch > m_last_delivered_epoch) {
      m_last_delivered_epoch = delivered_epoch;
      discard_stale_epoch_messages();
   }
 
   return result;
}

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 299 of file tls_handshake_io.cpp.

                                                 {
   // Future or incomplete fragments remain buffered, but only a complete
   // next-in-sequence message is trailing handshake data.
   const auto next = m_messages.find(m_in_message_seq);
   return next != m_messages.end() && next->second.complete();
}

initial_record_version()

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

overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 216 of file tls_handshake_io.cpp.

                                                                     {
   return Protocol_Version::DTLS_V12;
}

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 348 of file tls_handshake_io.cpp.

                                                                                            {
   if(m_finished) {
      return std::nullopt;
   }
 
   // Without an outgoing flight, or while constructing one, there is nothing
   // complete that timeout_check() could retransmit.
   if(!m_last_write.has_value() || (m_flights.size() > 1 && !m_flights.rbegin()->empty())) {
      return std::nullopt;
   }
 
   const uint64_t ms_since_write = m_steady_clock_ms() - m_last_write.value();
   if(ms_since_write >= m_next_timeout) {
      return std::chrono::milliseconds(0);
   }
 
   // BoringSSL reports a sub-15ms remainder as zero (ssl/d1_lib.cc
   // DTLSTimer::MicrosecondsRemaining) to absorb divergence with caller
   // scheduling; BoGo's DTLS-Retransmit-Fudge test requires it. The cap keeps
   // the fudge from swallowing the very short timers some tests configure.
   const uint64_t fudge_ms = std::min<uint64_t>(15, m_initial_timeout / 2);
   const uint64_t remaining_ms = m_next_timeout - ms_since_write;
 
   return std::chrono::milliseconds(remaining_ms <= fudge_ms ? 0 : remaining_ms);
}

Referenced by timeout_check().

send()

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

overridevirtual

Implements Botan::TLS::Handshake_IO.

Definition at line 896 of file tls_handshake_io.cpp.

                                                                           {
   return this->send_under_epoch(msg, m_seqs.current_write_epoch());
}

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 900 of file tls_handshake_io.cpp.

                                                                                                       {
   const std::vector<uint8_t> msg_bits = msg.serialize();
   const Handshake_Type msg_type = msg.type();
 
   if(msg_type == Handshake_Type::HandshakeCCS) {
      m_flight_ccs.rbegin()->emplace_back(m_flights.rbegin()->size(), epoch);
      m_send_hs(epoch, Record_Type::ChangeCipherSpec, msg_bits);
      return {};  // not included in handshake hashes
   } else if(msg_type == Handshake_Type::HelloVerifyRequest) {
      // RFC 6347 3.2.1 explicitly excludes HelloVerifyRequest from timeout
      // retransmission. A repeated ClientHello recreates the response using
      // the original message sequence number without retaining a flight.
      const uint16_t msg_seq = m_recreating_hello_verify_request ? m_out_message_seq - 1 : m_out_message_seq++;
      m_awaiting_cookie_client_hello = true;
      m_recreating_hello_verify_request = false;
      send_message(msg_seq, epoch, msg_type, msg_bits);
      return {};
   }
 
   m_flights.rbegin()->push_back(m_out_message_seq);
   m_flight_data.insert_or_assign(m_out_message_seq, Message_Info(epoch, msg_type, msg_bits));
 
   m_out_message_seq += 1;
   m_last_write = m_steady_clock_ms();
   m_next_timeout = m_initial_timeout;
   // Sending a new flight is forward progress: reset the give-up counter so the
   // retransmission budget applies per flight, not across the whole handshake.
   m_retransmit_count = 0;
   m_peer_replay_count = 0;
 
   return send_message(m_out_message_seq - 1, epoch, msg_type, msg_bits);
}

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 323 of file tls_handshake_io.cpp.

                                          {
   const auto timeout = next_retransmission_timeout();
   if(!timeout || timeout->count() > 0) {
      return false;
   }
 
   // The retransmit timer has expired. Count this attempt and, once the
   // configured cap is reached, abandon the handshake rather than retransmit
   // forever. RFC 6347 4.2.4.1 gives the backoff schedule but states no
   // condition for giving up, so the cap is local policy, not a requirement.
   // No alert is sent - the peer is by definition unresponsive.
   m_retransmit_count += 1;
   if(m_max_retransmissions.has_value() && m_retransmit_count > m_max_retransmissions.value()) {
      throw TLS_Exception(Alert::None, "DTLS handshake timed out: maximum retransmissions exceeded");
   }
 
   // retransmit_last_flight re-anchors m_last_write. Without that, once
   // m_next_timeout saturates at m_max_timeout the elapsed time keeps growing
   // and every subsequent poll fires another retransmission.
   retransmit_last_flight();
 
   m_next_timeout = std::min(2 * m_next_timeout, m_max_timeout);
   return true;
}

References next_retransmission_timeout().

---

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

• src/lib/tls/tls12/tls_handshake_io.h
• src/lib/tls/tls12/tls_handshake_io.cpp