Botan 3.14.1
Crypto and TLS for C&
tls_channel_impl.h
Go to the documentation of this file.
1/*
2* TLS Channel
3* (C) 2011,2012,2014,2015 Jack Lloyd
4* 2016 Matthias Gierlings
5* 2021 Elektrobit Automotive GmbH
6* 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
7*
8* Botan is released under the Simplified BSD License (see license.txt)
9*/
10
11#ifndef BOTAN_TLS_CHANNEL_IMPL_H_
12#define BOTAN_TLS_CHANNEL_IMPL_H_
13
14#include <botan/assert.h>
15#include <botan/tls_channel.h>
16#include <botan/tls_magic.h>
17#include <botan/tls_session.h> // TODO remove this dep
18#include <botan/tls_session_manager.h>
19#include <botan/tls_version.h>
20#include <memory>
21#include <utility>
22#include <vector>
23
24#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
25 #include <botan/tls_messages_13.h>
26 #include <botan/internal/tls_types_13.h>
27#endif
28
29namespace Botan {
30
33
34namespace TLS {
35
36class Client;
37class Server;
38
39class Channel_Impl : public std::enable_shared_from_this<Channel_Impl> {
40 protected:
41 /**
42 * Sentinel object to make constructors of derived classes un-callable by
43 * other classes.
44 */
45 struct Private {
46 explicit Private() = default;
47 };
48
49 public:
50 virtual ~Channel_Impl() = default;
51
52 Channel_Impl(const Channel_Impl& other) = delete;
53 Channel_Impl(Channel_Impl&& other) = default;
54 Channel_Impl& operator=(const Channel_Impl& other) = delete;
56
57 /**
58 * Inject TLS traffic received from counterparty
59 * @return a hint as the how many more bytes we need to q the
60 * current record (this may be 0 if on a record boundary)
61 */
62 virtual size_t from_peer(std::span<const uint8_t> data) = 0;
63
64 /**
65 * Inject plaintext intended for counterparty
66 * Throws an exception if is_active() is false
67 */
68 virtual void to_peer(std::span<const uint8_t> data) = 0;
69
70 /**
71 * Send a TLS alert message. If the alert is fatal, the internal
72 * state (keys, etc) will be reset.
73 * @param alert the Alert to send
74 */
75 virtual void send_alert(const Alert& alert) = 0;
76
77 /**
78 * Send a warning alert
79 */
80 void send_warning_alert(Alert::Type type) { send_alert(Alert(type, false)); }
81
82 /**
83 * Send a fatal alert
84 */
85 void send_fatal_alert(Alert::Type type) { send_alert(Alert(type, true)); }
86
87 /**
88 * Send a close notification alert
89 */
90 void close() { send_warning_alert(Alert::CloseNotify); }
91
92 /**
93 * @return true iff the TLS handshake has finished successfully
94 */
95 virtual bool is_handshake_complete() const = 0;
96
97 /**
98 * @return true iff the connection is active for sending application data
99 */
100 virtual bool is_active() const = 0;
101
102 virtual std::optional<std::chrono::milliseconds> next_retransmission_timeout() const { return std::nullopt; }
103
104 /**
105 * @return true iff the connection has been definitely closed
106 */
107 virtual bool is_closed() const = 0;
108
109 /**
110 * @return true iff the connection is active for sending application data
111 */
112 virtual bool is_closed_for_reading() const = 0;
113
114 /**
115 * @return true iff the connection has been definitely closed
116 */
117 virtual bool is_closed_for_writing() const = 0;
118
119 /**
120 * @return certificate chain of the peer (may be empty)
121 */
122 virtual std::vector<X509_Certificate> peer_cert_chain() const = 0;
123
124 /**
125 * @return raw public key of the peer (may be nullptr)
126 */
127 virtual std::shared_ptr<const Public_Key> peer_raw_public_key() const = 0;
128
129 /**
130 * @return identity of the PSK used for this connection
131 * or std::nullopt if no PSK was used.
132 */
133 virtual std::optional<std::string> external_psk_identity() const = 0;
134
135 /**
136 * Key material export (RFC 5705)
137 * @param label a disambiguating label string
138 * @param context a per-association context value
139 * @param length the length of the desired key in bytes
140 * @return key of length bytes
141 */
142 virtual SymmetricKey key_material_export(std::string_view label,
143 std::string_view context,
144 size_t length) const = 0;
145
146 /**
147 * Attempt to renegotiate the session
148 * @param force_full_renegotiation if true, require a full renegotiation,
149 * otherwise allow session resumption
150 */
151 virtual void renegotiate(bool force_full_renegotiation = false) = 0;
152
153 /**
154 * @return true if this channel can issue TLS 1.3 style session tickets.
155 */
156 virtual bool new_session_ticket_supported() const { return false; }
157
158 /**
159 * Send @p tickets new session tickets to the peer. This is only supported
160 * on TLS 1.3 servers.
161 *
162 * If the server's Session_Manager does not accept the generated Session
163 * objects, the server implementation won't be able to send new tickets.
164 * Additionally, anything but TLS 1.3 servers will return 0 (because they
165 * don't support sending such session tickets).
166 *
167 * @returns the number of session tickets successfully sent to the client
168 */
169 virtual size_t send_new_session_tickets(const size_t /* tickets */) { return 0; }
170
171 /**
172 * Attempt to update the session's traffic key material
173 * Note that this is possible with a TLS 1.3 channel, only.
174 *
175 * @param request_peer_update if true, require a reciprocal key update
176 */
177 virtual void update_traffic_keys(bool request_peer_update = false) = 0;
178
179 /**
180 * @return true iff the counterparty supports the secure
181 * renegotiation extensions.
182 */
183 virtual bool secure_renegotiation_supported() const = 0;
184
185 /**
186 * Perform a handshake timeout check. This does nothing unless this is a
187 * DTLS channel with a handshake in progress.
188 */
189 virtual bool timeout_check() = 0;
190
191 /**
192 * Return the protocol notification set for this connection, if any (ALPN).
193 * This value is not tied to the session and a later renegotiation of the
194 * same session can choose a new protocol.
195 */
196 virtual std::string application_protocol() const = 0;
197
198 protected:
199 Channel_Impl() = default;
200
201 /**
202 * Called for each received record that was dropped without having any
203 * effect, eg an empty record or a warning alert.
204 * Throws if too many of these arrive without any useful record between.
205 */
206 void note_useless_record(const Policy& policy);
207
208 /**
209 * Called for each received record that made progress
210 */
211 void reset_useless_records() { m_useless_records = 0; }
212
213#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
214
215 /**
216 * This struct collect all information required to perform a downgrade from TLS 1.3 to TLS 1.2.
217 *
218 * The downgrade process is (currently) triggered when a TLS 1.3 client receives a downgrade request
219 * in the server hello message (@sa `Client_Impl_13::handle(Server_Hello_12)`). As a result,
220 * `Client::received_data` should detect this condition and replace its `Channel_Impl_13` member by a
221 * `Channel_Impl_12`.
222 *
223 * Note that the downgrade process for the server implementation will likely differ.
224 */
225 struct Downgrade_Information {
226 /// The client hello message including the handshake header bytes as transferred to the peer.
227 std::optional<Client_Hello_13> client_hello;
228
229 /// The full data transcript received from the peer. This will contain the server hello message that forced us to downgrade.
230 std::vector<uint8_t> peer_transcript;
231
232 /// The TLS 1.2 session information found by a TLS 1.3 client that
233 /// caused it to initiate a downgrade before even sending a client hello.
234 std::optional<Session_with_Handle> tls12_session;
235
236 Server_Information server_info;
237 std::vector<std::string> next_protocols;
238 size_t io_buffer_size;
239 std::optional<Epoch0_SequenceNumbers> epoch0_sequence_numbers; // only relevant in DTLS
240
241 std::shared_ptr<Callbacks> callbacks;
242 std::shared_ptr<Session_Manager> session_manager;
243 std::shared_ptr<Credentials_Manager> creds;
244 std::shared_ptr<RandomNumberGenerator> rng;
245 std::shared_ptr<const Policy> policy;
246 TLS_Flavor flavor;
247
248 bool received_tls_13_error_alert;
249 bool will_downgrade;
250 };
251
252 std::unique_ptr<Downgrade_Information> m_downgrade_info; // NOLINT(*non-private-member-variable*)
253
254 void preserve_peer_transcript(std::span<const uint8_t> input) {
255 BOTAN_STATE_CHECK(m_downgrade_info);
256 m_downgrade_info->peer_transcript.insert(m_downgrade_info->peer_transcript.end(), input.begin(), input.end());
257 }
258
259 void preserve_client_hello(Client_Hello_13 client_hello) {
260 BOTAN_STATE_CHECK(m_downgrade_info);
261 m_downgrade_info->client_hello.emplace(std::move(client_hello));
262 }
263
264 friend class Client;
265 friend class Server;
266
267 void set_io_buffer_size(size_t io_buf_sz) {
268 BOTAN_STATE_CHECK(m_downgrade_info);
269 m_downgrade_info->io_buffer_size = io_buf_sz;
270 }
271
272 /**
273 * Implementations use this to signal that the peer indicated a protocol
274 * version downgrade. After calling `request_downgrade()` no further
275 * state changes must be performed by the implementation. Particularly, no
276 * further handshake messages must be emitted. Instead, they must yield
277 * control flow back to the underlying Channel implementation to perform
278 * the protocol version downgrade.
279 */
280 void request_downgrade() {
281 BOTAN_STATE_CHECK(m_downgrade_info && !m_downgrade_info->will_downgrade);
282 m_downgrade_info->will_downgrade = true;
283 }
284
285 void request_downgrade_for_resumption(Session_with_Handle session) {
286 BOTAN_STATE_CHECK(m_downgrade_info && !m_downgrade_info->client_hello.has_value() &&
287 m_downgrade_info->peer_transcript.empty() && !m_downgrade_info->tls12_session.has_value());
288 BOTAN_ASSERT_NOMSG(session.session.version().is_pre_tls_13());
289 m_downgrade_info->tls12_session = std::move(session);
290 request_downgrade();
291 }
292
293 public:
294 /**
295 * @sa Downgrade_Information
296 */
297 std::unique_ptr<Downgrade_Information> extract_downgrade_info() { return std::exchange(m_downgrade_info, {}); }
298
299#endif
300
301 /**
302 * Indicates whether a downgrade to TLS 1.2 or lower is in progress
303 *
304 * @sa Downgrade_Information
305 */
306 bool is_downgrading() const {
307#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
308 return m_downgrade_info && m_downgrade_info->will_downgrade;
309#else
310 return false;
311#endif
312 }
313
314 bool expects_downgrade() const {
315#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
316 return m_downgrade_info != nullptr;
317#else
318 return false;
319#endif
320 }
321
322 private:
323 size_t m_useless_records = 0;
324};
325
326} // namespace TLS
327
328} // namespace Botan
329
330#endif
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
AlertType Type
Definition tls_alert.h:73
virtual std::optional< std::string > external_psk_identity() const =0
virtual SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const =0
virtual bool is_active() const =0
virtual std::string application_protocol() const =0
Channel_Impl(Channel_Impl &&other)=default
virtual bool new_session_ticket_supported() const
virtual ~Channel_Impl()=default
virtual size_t from_peer(std::span< const uint8_t > data)=0
Channel_Impl & operator=(Channel_Impl &&other)=delete
virtual bool timeout_check()=0
virtual std::optional< std::chrono::milliseconds > next_retransmission_timeout() const
virtual bool is_closed_for_reading() const =0
virtual void update_traffic_keys(bool request_peer_update=false)=0
virtual void send_alert(const Alert &alert)=0
virtual void to_peer(std::span< const uint8_t > data)=0
virtual bool is_closed() const =0
void send_warning_alert(Alert::Type type)
virtual bool secure_renegotiation_supported() const =0
virtual bool is_closed_for_writing() const =0
virtual std::shared_ptr< const Public_Key > peer_raw_public_key() const =0
void send_fatal_alert(Alert::Type type)
void note_useless_record(const Policy &policy)
virtual void renegotiate(bool force_full_renegotiation=false)=0
virtual std::vector< X509_Certificate > peer_cert_chain() const =0
Channel_Impl(const Channel_Impl &other)=delete
virtual bool is_handshake_complete() const =0
virtual size_t send_new_session_tickets(const size_t)
Channel_Impl & operator=(const Channel_Impl &other)=delete
OctetString SymmetricKey
Definition symkey.h:153