Botan 3.14.1
Crypto and TLS for C&
tls_channel_impl_13.h
Go to the documentation of this file.
1/*
2* TLS Channel - implementation for TLS 1.3
3* (C) 2022 Jack Lloyd
4* 2021 Elektrobit Automotive GmbH
5* 2022 Hannes Rantzsch, René Meusel - neXenio GmbH
6* 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH
7*
8* Botan is released under the Simplified BSD License (see license.txt)
9*/
10
11#ifndef BOTAN_TLS_CHANNEL_IMPL_13_H_
12#define BOTAN_TLS_CHANNEL_IMPL_13_H_
13
14#include <botan/internal/tls_channel_impl.h>
15#include <botan/internal/tls_connection_state_13.h>
16#include <botan/internal/tls_flight_13.h>
17#include <botan/internal/tls_record_13.h>
18#include <botan/internal/tls_transcript_hash_13.h>
19
20namespace Botan::TLS {
21
22class Cipher_State;
23class Channel_IO;
24
25/**
26* Generic interface for TLS 1.3 endpoint
27*/
29 public:
30 /**
31 * Set up a new TLS 1.3 session
32 *
33 * @param callbacks contains a set of callback function references
34 * required by the TLS endpoint.
35 * @param session_manager manages session state
36 * @param credentials_manager manages application/user credentials
37 * @param rng a random number generator
38 * @param policy specifies other connection policy information
39 * @param is_server whether this is a server session or not
40 */
41 explicit Channel_Impl_13(const std::shared_ptr<Callbacks>& callbacks,
42 const std::shared_ptr<Session_Manager>& session_manager,
43 const std::shared_ptr<Credentials_Manager>& credentials_manager,
44 const std::shared_ptr<RandomNumberGenerator>& rng,
45 const std::shared_ptr<const Policy>& policy,
46 bool is_server);
47
48 Channel_Impl_13(const Channel_Impl_13& other) = delete;
50 Channel_Impl_13& operator=(const Channel_Impl_13& other) = delete;
52
53 ~Channel_Impl_13() override;
54
55 size_t from_peer(std::span<const uint8_t> data) override;
56 void to_peer(std::span<const uint8_t> data) override;
57
58 /**
59 * Send a TLS alert message. If the alert is fatal, the internal
60 * state (keys, etc) will be reset.
61 * @param alert the Alert to send
62 */
63 void send_alert(const Alert& alert) override;
64
65 /**
66 * @return true iff the connection is active for sending application data
67 *
68 * Note that the connection is active until the application has called
69 * `close()`, even if a CloseNotify has been received from the peer.
70 */
71 bool is_active() const override;
72
73 /**
74 * @return true iff the connection has been closed, i.e. CloseNotify
75 * has been received from the peer.
76 */
77 bool is_closed() const override { return is_closed_for_reading() && is_closed_for_writing(); }
78
79 bool is_closed_for_reading() const override { return !m_can_read; }
80
81 bool is_closed_for_writing() const override { return !m_can_write; }
82
83 /**
84 * Key material export (RFC 5705)
85 * @param label a disambiguating label string
86 * @param context a per-association context value
87 * @param length the length of the desired key in bytes
88 * @return key of length bytes
89 */
90 SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override;
91
92 /**
93 * Attempt to renegotiate the session
94 */
95 void renegotiate(bool /* unused */) override {
96 throw Invalid_Argument("renegotiation is not allowed in TLS 1.3");
97 }
98
99 /**
100 * Attempt to update the session's traffic key material
101 * Note that this is possible with a TLS 1.3 channel, only.
102 *
103 * @param request_peer_update if true, require a reciprocal key update
104 */
105 void update_traffic_keys(bool request_peer_update = false) override;
106
107 /**
108 * @return true iff the counterparty supports the secure
109 * renegotiation extensions.
110 */
111 bool secure_renegotiation_supported() const override {
112 // Secure renegotiation is not supported in TLS 1.3, though BoGo
113 // tests expect us to claim that it is available.
114 return true;
115 }
116
117 /**
118 * Perform a handshake timeout check. This does nothing unless
119 * this is a DTLS channel with a pending handshake state, in
120 * which case we check for timeout and potentially retransmit
121 * handshake packets.
122 *
123 * In the TLS 1.3 implementation, this always returns false.
124 */
125 bool timeout_check() override { return false; }
126
127 protected:
128 /**
129 * Hands ownership of the channel's cipher state to this channel and its
130 * associated Channel_IO. Typically called once the handshake's key
131 * schedule produced the first traffic secrets.
132 *
133 * @return a reference to the handed-off cipher state for convenience
134 */
135 Cipher_State& setup_cipher_state(std::unique_ptr<Cipher_State> cipher_state);
136
140
141 virtual bool compat_mode_ccs_requested() const = 0;
142 virtual void maybe_log_secret(std::string_view label, std::span<const uint8_t> secret) const = 0;
143
144 void handle(const Key_Update& key_update);
145
146 Callbacks& callbacks() const { return *m_callbacks; }
147
148 Session_Manager& session_manager() { return *m_session_manager; }
149
150 Credentials_Manager& credentials_manager() { return *m_credentials_manager; }
151
152 RandomNumberGenerator& rng() { return *m_rng; }
153
154 const Policy& policy() const { return *m_policy; }
155
157
158 void send_flight(std::vector<Flight::Message> flight);
159
160 private:
161 std::optional<BytesNeeded> process(Handshake_Message_13 handshake_msg);
162 void process(Post_Handshake_Message_13 post_handshake_msg);
163 void process(const Alert_Record& alert_record);
164 void process(const ChangeCipherSpec_Record& ccs_record);
165 void process(const ApplicationData_Record& app_data_record);
166
167 /**
168 * Terminate the connection (on sending or receiving an error alert) and
169 * clear secrets
170 */
171 void shutdown();
172
173 protected:
174 const Connection_Side m_side; // NOLINT(*non-private-member-variable*)
175 std::optional<Transcript_Hash_State> m_transcript_hash; // NOLINT(*non-private-member-variable*)
176 std::shared_ptr<Cipher_State> m_cipher_state; // NOLINT(*non-private-member-variable*)
177 std::optional<Active_Connection_State_13> m_active_state; // NOLINT(*non-private-member-variable*)
178
179 /* I/O handling */
180 std::shared_ptr<Channel_IO> m_channel_io; // NOLINT(*non-private-member-variable*)
181
182#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
183 /**
184 * Indicate that we have to expect a downgrade to TLS 1.2. In which case the current
185 * implementation (i.e. Client_Impl_13 or Server_Impl_13) will need to be replaced
186 * by their respective counter parts.
187 *
188 * This will prepare an internal structure where any information required to downgrade
189 * can be preserved.
190 * @sa `Channel_Impl::Downgrade_Information`
191 */
192 void expect_downgrade(const Server_Information& server_info, const std::vector<std::string>& next_protocols);
193#endif
194
195 /**
196 * Set the record size limits as negotiated by the "record_size_limit"
197 * extension (RFC 8449).
198 *
199 * @param outgoing_limit the maximal number of plaintext bytes to be
200 * sent in a protected record
201 * @param incoming_limit the maximal number of plaintext bytes to be
202 * accepted in a received protected record
203 */
204 void set_record_size_limits(uint16_t outgoing_limit, uint16_t incoming_limit);
205
206 /**
207 * Set the expected certificate type needed to parse Certificate
208 * messages in the handshake layer. See RFC 7250 and 8446 4.4.2 for
209 * further details.
210 */
212
213 private:
214 /* callbacks */
215 std::shared_ptr<Callbacks> m_callbacks;
216
217 /* external state */
218 std::shared_ptr<Session_Manager> m_session_manager;
219 std::shared_ptr<Credentials_Manager> m_credentials_manager;
220 std::shared_ptr<RandomNumberGenerator> m_rng;
221 std::shared_ptr<const Policy> m_policy;
222
223 bool m_can_read;
224 bool m_can_write;
225};
226} // namespace Botan::TLS
227
228#endif
std::shared_ptr< Cipher_State > m_cipher_state
Cipher_State & setup_cipher_state(std::unique_ptr< Cipher_State > cipher_state)
const Policy & policy() const
SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override
void send_flight(std::vector< Flight::Message > flight)
Channel_Impl_13 & operator=(Channel_Impl_13 &&other)=delete
void handle(const Key_Update &key_update)
Credentials_Manager & credentials_manager()
RandomNumberGenerator & rng()
Channel_Impl_13 & operator=(const Channel_Impl_13 &other)=delete
bool is_closed_for_reading() const override
std::optional< Transcript_Hash_State > m_transcript_hash
bool secure_renegotiation_supported() const override
void to_peer(std::span< const uint8_t > data) override
virtual bool compat_mode_ccs_requested() const =0
virtual void process_post_handshake_msg(Post_Handshake_Message_13 msg)=0
std::optional< Active_Connection_State_13 > m_active_state
virtual void process_handshake_msg(Handshake_Message_13 msg)=0
Channel_Impl_13(const std::shared_ptr< Callbacks > &callbacks, const std::shared_ptr< Session_Manager > &session_manager, const std::shared_ptr< Credentials_Manager > &credentials_manager, const std::shared_ptr< RandomNumberGenerator > &rng, const std::shared_ptr< const Policy > &policy, bool is_server)
SecretLoggerFn secret_logger() const
std::shared_ptr< Channel_IO > m_channel_io
void send_alert(const Alert &alert) override
size_t from_peer(std::span< const uint8_t > data) override
virtual void maybe_log_secret(std::string_view label, std::span< const uint8_t > secret) const =0
void update_traffic_keys(bool request_peer_update=false) override
virtual void process_dummy_change_cipher_spec()=0
Session_Manager & session_manager()
bool is_closed() const override
Channel_Impl_13(const Channel_Impl_13 &other)=delete
Channel_Impl_13(Channel_Impl_13 &&other)=delete
void set_selected_certificate_type(Certificate_Type cert_type)
bool is_closed_for_writing() const override
void set_record_size_limits(uint16_t outgoing_limit, uint16_t incoming_limit)
Channel_Impl(const Channel_Impl &other)=delete
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::function< void(std::string_view label, std::span< const uint8_t > secret)> SecretLoggerFn
std::variant< New_Session_Ticket_13, Key_Update > Post_Handshake_Message_13
OctetString SymmetricKey
Definition symkey.h:153