Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::Channel_IO Class Referenceabstract

#include <tls_channel_io.h>

Public Types

using ReceiveEvent

Public Member Functions

 Channel_IO (Channel_IO &&)=delete
 Channel_IO (const Channel_IO &)=delete
void notify_closed_for_reading ()
void notify_shutdown ()
Channel_IO & operator= (Channel_IO &&)=delete
Channel_IO & operator= (const Channel_IO &)=delete
void set_cipher_state (std::weak_ptr< Cipher_State > cipher_state)
void set_record_size_limits (uint16_t out, uint16_t in)
void set_selected_certificate_type (Certificate_Type cert_type)
virtual ~Channel_IO ()=default
Ingestion of incoming data
void copy_data (std::span< const uint8_t > data)
ReceiveEvent next_pending_event (std::optional< Transcript_Hash_State > &transcript_hash, bool handshake_complete)
Emission of outgoing data
void send (std::vector< Flight::Message > flight)
 Sends a flight of handshake messages to the peer.
void send (std::span< const uint8_t > payload)
 Sends application data to the peer.
void send (const Alert &alert, bool handle_compat_mode)
 Sends an alert to the peer.
Traffic key updates (RFC 8446 4.6.3)
void handle_key_update (const Key_Update &key_update)
void update_traffic_keys (bool request_peer_update)

Static Public Member Functions

static std::shared_ptr< Channel_IO > create (Connection_Side side, TLS_Flavor flavor, std::shared_ptr< const Policy > policy, std::shared_ptr< Callbacks > callbacks)

Protected Member Functions

Callbacks & callbacks ()
const Callbacks & callbacks () const
 Channel_IO (Connection_Side side, std::shared_ptr< const Policy > policy, std::shared_ptr< Callbacks > callbacks)
std::shared_ptr< Cipher_State > cipher_state ()
std::shared_ptr< const Cipher_State > cipher_state () const
virtual const Handshake_Layer & handshake_layer () const =0
virtual Handshake_Layer & handshake_layer ()=0
std::optional< ReceiveEvent > next_pending_handshake_message (std::optional< Transcript_Hash_State > &transcript_hash, bool handshake_complete)
const Policy & policy () const
virtual void process (const Handshake_Record &record)=0
virtual const Record_Layer & record_layer () const =0
virtual Record_Layer & record_layer ()=0
virtual void send_data (Record_Type record_type, std::span< const uint8_t > payload, Cipher_State *cipher_state)=0
void send_dummy_change_cipher_spec ()
 Sends a dummy ChangeCipherSpec record to the peer.
virtual void send_flight (std::vector< Flight::Message > flight)=0

Detailed Description

Channel_IO owns the record layer and handshake layer of a (D)TLS 1.3 channel and handles all wire-format I/O: incoming bytes are ingested via copy_data() and surfaced as a stream of events via next_pending_event(); outgoing handshake flights, application data and alerts are emitted via the send() overloads.

Definition at line 30 of file tls_channel_io.h.

Member Typedef Documentation

◆ ReceiveEvent

Initial value:
std::variant<BytesNeeded,
size_t BytesNeeded
std::variant< Client_Hello_13, Client_Hello_12_Shim, Server_Hello_13, Server_Hello_12_Shim, Hello_Retry_Request, Encrypted_Extensions, Certificate_13, Certificate_Request_13, Certificate_Verify_13, Finished_13 > Handshake_Message_13
std::variant< New_Session_Ticket_13, Key_Update > Post_Handshake_Message_13

Definition at line 32 of file tls_channel_io.h.

Constructor & Destructor Documentation

◆ Channel_IO() [1/3]

Botan::TLS::Channel_IO::Channel_IO ( Connection_Side side,
std::shared_ptr< const Policy > policy,
std::shared_ptr< Callbacks > callbacks )
inlineprotected

Definition at line 45 of file tls_channel_io.h.

45 :
46 m_policy(std::move(policy)), m_callbacks(std::move(callbacks)), m_side(side) {}
const Callbacks & callbacks() const
const Policy & policy() const

References callbacks(), and policy().

Referenced by Channel_IO(), Channel_IO(), operator=(), and operator=().

◆ Channel_IO() [2/3]

Botan::TLS::Channel_IO::Channel_IO ( const Channel_IO & )
delete

References Channel_IO().

◆ Channel_IO() [3/3]

Botan::TLS::Channel_IO::Channel_IO ( Channel_IO && )
delete

References Channel_IO().

◆ ~Channel_IO()

virtual Botan::TLS::Channel_IO::~Channel_IO ( )
virtualdefault

Member Function Documentation

◆ callbacks() [1/2]

Callbacks & Botan::TLS::Channel_IO::callbacks ( )
inlineprotected

Definition at line 151 of file tls_channel_io.h.

151{ return *m_callbacks; }

◆ callbacks() [2/2]

const Callbacks & Botan::TLS::Channel_IO::callbacks ( ) const
inlineprotected

Definition at line 149 of file tls_channel_io.h.

149{ return *m_callbacks; }

Referenced by Channel_IO(), create(), handle_key_update(), and update_traffic_keys().

◆ cipher_state() [1/2]

std::shared_ptr< Cipher_State > Botan::TLS::Channel_IO::cipher_state ( )
protected

Definition at line 335 of file tls_channel_io.cpp.

335 {
336 return m_cipher_state.lock();
337}

◆ cipher_state() [2/2]

std::shared_ptr< const Cipher_State > Botan::TLS::Channel_IO::cipher_state ( ) const
protected

Definition at line 331 of file tls_channel_io.cpp.

331 {
332 return m_cipher_state.lock();
333}

Referenced by handle_key_update(), handshake_layer(), next_pending_event(), send(), send(), send_data(), set_cipher_state(), and update_traffic_keys().

◆ copy_data()

void Botan::TLS::Channel_IO::copy_data ( std::span< const uint8_t > data)

Ingests incoming data from the network and processes it into a stream of events.

See also
next_pending_event().

Definition at line 87 of file tls_channel_io.cpp.

87 {
88 // RFC 9846 6.1
89 // Any data received after a closure alert has been received MUST
90 // be ignored.
91 if(m_closed_for_reading) {
92 return;
93 }
94
95 record_layer().copy_data(data);
96}
virtual Record_Layer & record_layer()=0
virtual void copy_data(std::span< const uint8_t > data_from_peer)=0

References Botan::TLS::Record_Layer::copy_data(), and record_layer().

Referenced by ~Channel_IO().

◆ create()

std::shared_ptr< Channel_IO > Botan::TLS::Channel_IO::create ( Connection_Side side,
TLS_Flavor flavor,
std::shared_ptr< const Policy > policy,
std::shared_ptr< Callbacks > callbacks )
static

Definition at line 468 of file tls_channel_io.cpp.

471 {
472 if(flavor == TLS_Flavor::DTLS) {
473 throw Not_Implemented("DTLS 1.3 is not yet supported");
474 } else {
475 return std::make_shared<TLS_Channel_IO>(side, std::move(policy), std::move(callbacks));
476 }
477}

References callbacks(), Botan::TLS::DTLS, and policy().

◆ handle_key_update()

void Botan::TLS::Channel_IO::handle_key_update ( const Key_Update & key_update)

Processes a KeyUpdate message received from the peer: updates the read keys, and schedules a reciprocal KeyUpdate if the peer requested one.

Definition at line 223 of file tls_channel_io.cpp.

223 {
224 const auto cs = cipher_state();
226
227 // A non-requesting KeyUpdate received while our own request is outstanding
228 // is the reciprocation we solicited. It is exempt from rate limiting (and
229 // invisible to it), so that a peer whose own key update crossed ours in
230 // flight is not penalized for the resulting back to back KeyUpdates.
231 const bool solicited_reciprocation = m_key_update_requested && !key_update.expects_reciprocation();
232
233 if(const uint64_t min_interval = policy().minimum_key_update_interval_ms();
234 min_interval > 0 && !solicited_reciprocation) {
235 const uint64_t now = callbacks().tls_current_monotonic_clock_ms();
236
237 if(m_last_peer_key_update_ms != 0 && (now - m_last_peer_key_update_ms) < min_interval) {
238 throw TLS_Exception(Alert::UnexpectedMessage, "Peer is requesting KeyUpdates too frequently");
239 }
240
241 m_last_peer_key_update_ms = now;
242 }
243
244 cs->update_read_keys();
245
246 if(key_update.expects_reciprocation() && cs->can_encrypt_application_traffic()) {
247 // RFC 9846 4.7.3
248 // If the request_update field is set to "update_requested", then the
249 // receiver MUST send a KeyUpdate of its own with request_update set to
250 // "update_not_requested" prior to sending its next Application Data
251 // record.
252 //
253 // This happens opportunistically in send(), and only if we can (still)
254 // encrypt application data. If we half-closed the connection on our side
255 // we cannot reciprocate the key update any longer.
256 m_key_update_reciprocation_pending = true;
257 } else {
258 // Only an actual reciprocation settles our outstanding request. RFC 9846
259 // 4.7.3 would allow requesting again after any KeyUpdate from the peer,
260 // but waiting for the reciprocation keeps the exemption above one-shot.
261 m_key_update_requested = false;
262 }
263}
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
virtual uint64_t tls_current_monotonic_clock_ms()
std::shared_ptr< const Cipher_State > cipher_state() const

References BOTAN_ASSERT_NONNULL, callbacks(), cipher_state(), Botan::TLS::Key_Update::expects_reciprocation(), policy(), and Botan::TLS::Callbacks::tls_current_monotonic_clock_ms().

Referenced by ~Channel_IO().

◆ handshake_layer() [1/2]

virtual const Handshake_Layer & Botan::TLS::Channel_IO::handshake_layer ( ) const
protectedpure virtual

References cipher_state().

◆ handshake_layer() [2/2]

virtual Handshake_Layer & Botan::TLS::Channel_IO::handshake_layer ( )
protectedpure virtual

◆ next_pending_event()

Channel_IO::ReceiveEvent Botan::TLS::Channel_IO::next_pending_event ( std::optional< Transcript_Hash_State > & transcript_hash,
bool handshake_complete )

Retrieves the next pending event from the processed incoming data. If no more events are available, this will return a BytesNeeded event indicating how many more bytes are needed to continue processing.

Definition at line 98 of file tls_channel_io.cpp.

99 {
100 const auto cs = cipher_state();
101
102 while(true) {
103 // First we check if the handshake layer has any complete messages ready
104 // to be consumed by the channel. If yes, we return that message....
105 if(auto event = next_pending_handshake_message(transcript_hash, handshake_complete)) {
106 // Handshake messages can be directly consumed by the channel
107 return std::move(event).value();
108 }
109
110 // ... otherwise we check if the record layer has any complete records
111 // ready to be processed. If yes, we dispatch the record to the
112 // appropriate handler or return it to the channel (e.g. application data,
113 // alerts, etc.). If no complete record is available, we return a
114 // BytesNeeded event which indicates that no more events are available and
115 // the channel needs to wait for the application to provide more data.
116 auto res = std::visit( //
118 [](BytesNeeded bytes) -> std::optional<Channel_IO::ReceiveEvent> { return bytes; },
119 [&](const Handshake_Record& record) -> std::optional<Channel_IO::ReceiveEvent> {
120 process(record);
121 return std::nullopt; // continue looping, the handshake layer may have progressed...
122 },
123 [&](auto anything_else) -> std::optional<Channel_IO::ReceiveEvent> {
124 // RFC 8446 5.1
125 // Handshake messages MUST NOT be interleaved with other record types.
126 if(handshake_layer().has_pending_data()) {
127 throw Unexpected_Message("Expected remainder of a handshake message");
128 }
129 return anything_else;
130 },
131 },
132 record_layer().next_record(cs.get()));
133
134 if(res.has_value()) {
135 return std::move(res).value();
136 }
137 }
138}
virtual void process(const Handshake_Record &record)=0
std::optional< ReceiveEvent > next_pending_handshake_message(std::optional< Transcript_Hash_State > &transcript_hash, bool handshake_complete)
virtual Handshake_Layer & handshake_layer()=0
virtual ReadResult next_record(Cipher_State *cipher_state=nullptr)=0
overloaded(Ts...) -> overloaded< Ts... >

References cipher_state(), handshake_layer(), next_pending_handshake_message(), Botan::TLS::Record_Layer::next_record(), process(), and record_layer().

Referenced by ~Channel_IO().

◆ next_pending_handshake_message()

std::optional< Channel_IO::ReceiveEvent > Botan::TLS::Channel_IO::next_pending_handshake_message ( std::optional< Transcript_Hash_State > & transcript_hash,
bool handshake_complete )
protected

Definition at line 24 of file tls_channel_io.cpp.

25 {
26 auto& hs_layer = handshake_layer();
27 auto& rec_layer = record_layer();
28
29 if(!handshake_complete) {
30 BOTAN_ASSERT_NOMSG(transcript_hash.has_value());
31 auto handshake_msg = hs_layer.next_message(policy(), *transcript_hash);
32 if(!handshake_msg.has_value()) {
33 return std::nullopt;
34 }
35
36 // RFC 9846 5.1
37 // Handshake messages MUST NOT span key changes. Implementations
38 // MUST verify that all messages immediately preceding a key change
39 // align with a record boundary; if not, then they MUST terminate the
40 // connection with an "unexpected_message" alert. Because the
41 // ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate
42 // messages can immediately precede a key change, implementations
43 // MUST send these messages in alignment with a record boundary.
44 //
45 // Note: Hello_Retry_Request was added to the list below although it
46 // cannot immediately precede a key change. However, there cannot be
47 // any further sensible messages in the record after HRR.
48 //
49 // Note: Server_Hello_12 was deliberately not included in the check below
50 // because in TLS 1.2 Server Hello and other handshake messages can
51 // be legally coalesced in a single record.
52 //
53 if(holds_any_of<Client_Hello_12_Shim,
54 Client_Hello_13 /*, EndOfEarlyData,*/,
55 Server_Hello_13,
56 Hello_Retry_Request,
57 Finished_13>(handshake_msg.value()) &&
58 hs_layer.has_pending_data()) {
59 throw Unexpected_Message("Unexpected additional handshake message data found in record");
60 }
61
62 // After the initial handshake message is received, the record
63 // layer must be more restrictive.
64 // See RFC 9846 5.1 regarding "legacy_record_version"
65 if(!m_first_message_delivered) {
66 rec_layer.disable_receiving_compat_mode();
67 m_first_message_delivered = true;
68 }
69
70 return std::move(handshake_msg).value();
71 } else {
72 auto post_handshake_msg = hs_layer.next_post_handshake_message(policy());
73 if(!post_handshake_msg.has_value()) {
74 return std::nullopt;
75 }
76
77 // make sure Key_Update appears only at the end of a record; see RFC
78 // 9846 5.1 description above
79 if(std::holds_alternative<Key_Update>(post_handshake_msg.value()) && hs_layer.has_pending_data()) {
80 throw Unexpected_Message("Unexpected additional post-handshake message data found in record");
81 }
82
83 return std::move(post_handshake_msg).value();
84 }
85}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
constexpr bool holds_any_of(const std::variant< Ts... > &v) noexcept
Definition stl_util.h:66

References BOTAN_ASSERT_NOMSG, handshake_layer(), Botan::holds_any_of(), policy(), and record_layer().

Referenced by next_pending_event().

◆ notify_closed_for_reading()

void Botan::TLS::Channel_IO::notify_closed_for_reading ( )

Notifies that the channel is closed for reading (close_notify received). The IO can discard any read-side state; no further data will be processed.

Definition at line 314 of file tls_channel_io.cpp.

314 {
316 m_closed_for_reading = true;
317}
virtual void clear_read_buffer()=0

References Botan::TLS::Record_Layer::clear_read_buffer(), and record_layer().

Referenced by notify_shutdown(), and ~Channel_IO().

◆ notify_shutdown()

void Botan::TLS::Channel_IO::notify_shutdown ( )

Notifies that the channel was shut down in both directions. The IO discards any read-side state; no further data will be processed.

Definition at line 319 of file tls_channel_io.cpp.

319 {
321}

References notify_closed_for_reading().

Referenced by ~Channel_IO().

◆ operator=() [1/2]

Channel_IO & Botan::TLS::Channel_IO::operator= ( Channel_IO && )
delete

References Channel_IO().

◆ operator=() [2/2]

Channel_IO & Botan::TLS::Channel_IO::operator= ( const Channel_IO & )
delete

References Channel_IO().

◆ policy()

const Policy & Botan::TLS::Channel_IO::policy ( ) const
inlineprotected

Definition at line 147 of file tls_channel_io.h.

147{ return *m_policy; }

Referenced by Channel_IO(), create(), handle_key_update(), and next_pending_handshake_message().

◆ process()

virtual void Botan::TLS::Channel_IO::process ( const Handshake_Record & record)
protectedpure virtual

Referenced by next_pending_event().

◆ record_layer() [1/2]

virtual const Record_Layer & Botan::TLS::Channel_IO::record_layer ( ) const
protectedpure virtual

◆ record_layer() [2/2]

virtual Record_Layer & Botan::TLS::Channel_IO::record_layer ( )
protectedpure virtual

◆ send() [1/3]

void Botan::TLS::Channel_IO::send ( const Alert & alert,
bool handle_compat_mode )

Sends an alert to the peer.

Definition at line 279 of file tls_channel_io.cpp.

279 {
280 const auto cs = cipher_state();
281
282 // RFC 9846 E.4
283 // [...] the client sends a dummy change_cipher_spec record [...]
284 // immediately before its second flight. [...]
285 // The server sends a dummy change_cipher_spec record immediately after
286 // its first handshake message.
287 //
288 // For the client, the "second flight" might be an alert that aborts the
289 // handshake (e.g., from a failing certificate verification or a throwing
290 // callback). The server isn't expected to emit an alert immediately after
291 // its first handshake message, hence it is not handled here.
292 //
293 // Also, the dummy CCS is only sent if the handshake actually produced a
294 // cipher state: i.e., only if we would actually encrypt now.
295 if(handle_compat_mode && !m_dummy_ccs_emitted && m_side == Connection_Side::Client && cs != nullptr) {
297 }
298
299 send_data(Record_Type::Alert, alert.serialize(), cs.get());
300}
void send_dummy_change_cipher_spec()
Sends a dummy ChangeCipherSpec record to the peer.
virtual void send_data(Record_Type record_type, std::span< const uint8_t > payload, Cipher_State *cipher_state)=0

References Botan::TLS::Alert, cipher_state(), Botan::TLS::Client, send_data(), send_dummy_change_cipher_spec(), and Botan::TLS::Alert::serialize().

◆ send() [2/3]

void Botan::TLS::Channel_IO::send ( std::span< const uint8_t > payload)

Sends application data to the peer.

Definition at line 144 of file tls_channel_io.cpp.

144 {
145 // RFC 9846 4.7.3
146 // If the request_update field [of a received KeyUpdate] is set to
147 // "update_requested", then the receiver MUST send a KeyUpdate of its own
148 // with request_update set to "update_not_requested" prior to sending its
149 // next Application Data record. This mechanism allows either side to
150 // force an update to the entire connection, but causes an implementation
151 // which receives multiple KeyUpdates while it is silent to respond with
152 // a single update.
153 if(m_key_update_reciprocation_pending) {
154 update_traffic_keys(false /* update_requested */);
155 m_key_update_reciprocation_pending = false;
156 } else if(needs_traffic_based_key_update()) {
157 // If approaching traffic limits request the peer update their own keys
158 // as well, unless an earlier request is still unanswered:
159 //
160 // RFC 9846 4.7.3
161 // Until receiving a subsequent KeyUpdate from the peer, the sender
162 // MUST NOT send another KeyUpdate with request_update set to
163 // "update_requested".
164 update_traffic_keys(!m_key_update_requested);
165 }
166
167 const auto cs = cipher_state();
169 send_data(Record_Type::ApplicationData, payload, cs.get());
170}
void update_traffic_keys(bool request_peer_update)

References Botan::TLS::ApplicationData, BOTAN_ASSERT_NONNULL, cipher_state(), send_data(), and update_traffic_keys().

◆ send() [3/3]

void Botan::TLS::Channel_IO::send ( std::vector< Flight::Message > flight)

Sends a flight of handshake messages to the peer.

Definition at line 140 of file tls_channel_io.cpp.

140 {
141 send_flight(std::move(flight));
142}
virtual void send_flight(std::vector< Flight::Message > flight)=0

References send_flight().

Referenced by ~Channel_IO().

◆ send_data()

virtual void Botan::TLS::Channel_IO::send_data ( Record_Type record_type,
std::span< const uint8_t > payload,
Cipher_State * cipher_state )
protectedpure virtual

References cipher_state().

Referenced by send(), send(), and send_dummy_change_cipher_spec().

◆ send_dummy_change_cipher_spec()

void Botan::TLS::Channel_IO::send_dummy_change_cipher_spec ( )
protected

Sends a dummy ChangeCipherSpec record to the peer.

Definition at line 302 of file tls_channel_io.cpp.

302 {
303 // RFC 9846 5.
304 // An implementation which [...] receives a protected change_cipher_spec
305 // record MUST abort the handshake [...].
306 //
307 // I.e. Change Cipher Spec records must always be sent unprotected, even if
308 // the cipher state is already set up for handshake message encryption.
309 constexpr auto ccs = std::array<uint8_t, 1>{0x01};
311 m_dummy_ccs_emitted = true;
312}

References Botan::TLS::ChangeCipherSpec, and send_data().

Referenced by send().

◆ send_flight()

virtual void Botan::TLS::Channel_IO::send_flight ( std::vector< Flight::Message > flight)
protectedpure virtual

Referenced by send(), and update_traffic_keys().

◆ set_cipher_state()

void Botan::TLS::Channel_IO::set_cipher_state ( std::weak_ptr< Cipher_State > cipher_state)
inline

Definition at line 118 of file tls_channel_io.h.

118{ m_cipher_state = std::move(cipher_state); }

References cipher_state().

◆ set_record_size_limits()

void Botan::TLS::Channel_IO::set_record_size_limits ( uint16_t out,
uint16_t in )

Definition at line 323 of file tls_channel_io.cpp.

323 {
325}
void set_record_size_limits(uint16_t outgoing_limit, uint16_t incoming_limit)

References record_layer(), and Botan::TLS::Record_Layer::set_record_size_limits().

◆ set_selected_certificate_type()

void Botan::TLS::Channel_IO::set_selected_certificate_type ( Certificate_Type cert_type)

Definition at line 327 of file tls_channel_io.cpp.

327 {
329}
void set_selected_certificate_type(Certificate_Type cert_type)

References handshake_layer(), and Botan::TLS::Handshake_Layer::set_selected_certificate_type().

◆ update_traffic_keys()

void Botan::TLS::Channel_IO::update_traffic_keys ( bool request_peer_update)

Sends a KeyUpdate message to the peer and updates the write keys.

Parameters
request_peer_updatewhether to request a reciprocal KeyUpdate

Definition at line 265 of file tls_channel_io.cpp.

265 {
266 const auto cs = cipher_state();
268
269 send_flight(PostHandshakeFlight(callbacks()) //
270 .add(Key_Update(request_peer_update))
271 .commit());
272
273 if(request_peer_update) {
274 m_key_update_requested = true;
275 }
276 cs->update_write_keys();
277}

References BOTAN_ASSERT_NONNULL, callbacks(), cipher_state(), and send_flight().

Referenced by send(), and ~Channel_IO().


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