Botan 3.14.1
Crypto and TLS for C&
tls_channel_io.h
Go to the documentation of this file.
1/*
2* TLS Channel IO
3* (C) 2026 Jack Lloyd
4* 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_CHANNEL_IO_BASE_H_
10#define BOTAN_TLS_CHANNEL_IO_BASE_H_
11
12#include <botan/internal/tls_flight_13.h>
13#include <botan/internal/tls_record_13.h>
14#include <optional>
15
16namespace Botan::TLS {
17
18class Alert;
19class Record_Layer;
20class Handshake_Layer;
21class Cipher_State;
22
23/**
24 * Channel_IO owns the record layer and handshake layer of a (D)TLS 1.3
25 * channel and handles all wire-format I/O: incoming bytes are ingested via
26 * copy_data() and surfaced as a stream of events via next_pending_event();
27 * outgoing handshake flights, application data and alerts are emitted via the
28 * send() overloads.
29 */
31 public:
32 using ReceiveEvent = std::variant<BytesNeeded,
38
39 static std::shared_ptr<Channel_IO> create(Connection_Side side,
40 TLS_Flavor flavor,
41 std::shared_ptr<const Policy> policy,
42 std::shared_ptr<Callbacks> callbacks);
43
44 protected:
45 Channel_IO(Connection_Side side, std::shared_ptr<const Policy> policy, std::shared_ptr<Callbacks> callbacks) :
46 m_policy(std::move(policy)), m_callbacks(std::move(callbacks)), m_side(side) {}
47
48 public:
49 Channel_IO(const Channel_IO&) = delete;
50 Channel_IO& operator=(const Channel_IO&) = delete;
53
54 virtual ~Channel_IO() = default;
55
56 /// @name Ingestion of incoming data
57 /// @{
58
59 /**
60 * Ingests incoming data from the network and processes it into a stream
61 * of events. @sa next_pending_event().
62 */
63 void copy_data(std::span<const uint8_t> data);
64
65 /**
66 * Retrieves the next pending event from the processed incoming data. If
67 * no more events are available, this will return a BytesNeeded event
68 * indicating how many more bytes are needed to continue processing.
69 */
70 ReceiveEvent next_pending_event(std::optional<Transcript_Hash_State>& transcript_hash, bool handshake_complete);
71
72 /// @}
73
74 /// @name Emission of outgoing data
75 /// @{
76
77 /// Sends a flight of handshake messages to the peer.
78 void send(std::vector<Flight::Message> flight);
79
80 /// Sends application data to the peer.
81 void send(std::span<const uint8_t> payload);
82
83 /// Sends an alert to the peer.
84 void send(const Alert& alert, bool handle_compat_mode);
85
86 /// @}
87
88 /// @name Traffic key updates (RFC 8446 4.6.3)
89 /// @{
90
91 /**
92 * Processes a KeyUpdate message received from the peer: updates the read
93 * keys, and schedules a reciprocal KeyUpdate if the peer requested one.
94 */
95 void handle_key_update(const Key_Update& key_update);
96
97 /**
98 * Sends a KeyUpdate message to the peer and updates the write keys.
99 *
100 * @param request_peer_update whether to request a reciprocal KeyUpdate
101 */
102 void update_traffic_keys(bool request_peer_update);
103
104 /// @}
105
106 /**
107 * Notifies that the channel is closed for reading (close_notify received).
108 * The IO can discard any read-side state; no further data will be processed.
109 */
111
112 /**
113 * Notifies that the channel was shut down in both directions. The IO
114 * discards any read-side state; no further data will be processed.
115 */
116 void notify_shutdown();
117
118 void set_cipher_state(std::weak_ptr<Cipher_State> cipher_state) { m_cipher_state = std::move(cipher_state); }
119
120 void set_record_size_limits(uint16_t out, uint16_t in);
121 void set_selected_certificate_type(Certificate_Type cert_type);
122
123 protected:
124 std::optional<ReceiveEvent> next_pending_handshake_message(std::optional<Transcript_Hash_State>& transcript_hash,
125 bool handshake_complete);
126
127 /// Sends a dummy ChangeCipherSpec record to the peer.
128 void send_dummy_change_cipher_spec();
129
130 virtual void process(const Handshake_Record& record) = 0;
131
132 virtual void send_data(Record_Type record_type, std::span<const uint8_t> payload, Cipher_State* cipher_state) = 0;
133
134 virtual void send_flight(std::vector<Flight::Message> flight) = 0;
135
137
139
140 virtual const Record_Layer& record_layer() const = 0;
141
142 virtual const Handshake_Layer& handshake_layer() const = 0;
143
144 std::shared_ptr<const Cipher_State> cipher_state() const;
145 std::shared_ptr<Cipher_State> cipher_state();
146
147 const Policy& policy() const { return *m_policy; }
148
149 const Callbacks& callbacks() const { return *m_callbacks; }
150
151 Callbacks& callbacks() { return *m_callbacks; }
152
153 private:
154 bool needs_traffic_based_key_update() const;
155
156 private:
157 bool m_first_message_delivered = false;
158
159 /**
160 * True once the peer sent close_notify and notify_closed_for_reading()
161 * was called. From then on, any further incoming data is ignored.
162 * See RFC 9846 6.1.
163 */
164 bool m_closed_for_reading = false;
165
166 /**
167 * True if a dummy CCS record has been sent to the peer already.
168 * See RFC 9846 E.4 for details.
169 */
170 bool m_dummy_ccs_emitted = false;
171
172 /**
173 * True if the peer requested a KeyUpdate that we have yet to reciprocate
174 * before sending our next application data record.
175 */
176 bool m_key_update_reciprocation_pending = false;
177
178 /**
179 * True while a KeyUpdate with "update_requested" is outstanding, i.e.
180 * the peer has not yet replied with a KeyUpdate of its own.
181 */
182 bool m_key_update_requested = false;
183
184 uint64_t m_last_peer_key_update_ms = 0;
185
186 std::weak_ptr<Cipher_State> m_cipher_state;
187 std::shared_ptr<const Policy> m_policy;
188 std::shared_ptr<Callbacks> m_callbacks;
189 Connection_Side m_side;
190};
191
192} // namespace Botan::TLS
193
194#endif
#define BOTAN_TEST_API
Definition api.h:41
void copy_data(std::span< const uint8_t > data)
std::shared_ptr< const Cipher_State > cipher_state() const
virtual void process(const Handshake_Record &record)=0
virtual const Handshake_Layer & handshake_layer() const =0
const Callbacks & callbacks() const
virtual const Record_Layer & record_layer() const =0
void send(std::vector< Flight::Message > flight)
Sends a flight of handshake messages to the peer.
std::variant< BytesNeeded, Handshake_Message_13, Post_Handshake_Message_13, ChangeCipherSpec_Record, Alert_Record, ApplicationData_Record > ReceiveEvent
Channel_IO(const Channel_IO &)=delete
Channel_IO & operator=(Channel_IO &&)=delete
void handle_key_update(const Key_Update &key_update)
const Policy & policy() const
virtual void send_data(Record_Type record_type, std::span< const uint8_t > payload, Cipher_State *cipher_state)=0
ReceiveEvent next_pending_event(std::optional< Transcript_Hash_State > &transcript_hash, bool handshake_complete)
Channel_IO(Connection_Side side, std::shared_ptr< const Policy > policy, std::shared_ptr< Callbacks > callbacks)
Channel_IO(Channel_IO &&)=delete
virtual void send_flight(std::vector< Flight::Message > flight)=0
virtual ~Channel_IO()=default
void update_traffic_keys(bool request_peer_update)
static std::shared_ptr< Channel_IO > create(Connection_Side side, TLS_Flavor flavor, std::shared_ptr< const Policy > policy, std::shared_ptr< Callbacks > callbacks)
virtual Record_Layer & record_layer()=0
Channel_IO & operator=(const Channel_IO &)=delete
virtual Handshake_Layer & handshake_layer()=0
void set_cipher_state(std::weak_ptr< Cipher_State > cipher_state)
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