Botan 3.9.0
Crypto and TLS for C&
tls_channel_impl_12.h
Go to the documentation of this file.
1/*
2* TLS Channel - implementation for TLS 1.2
3* (C) 2011,2012,2014,2015 Jack Lloyd
4* 2016 Matthias Gierlings
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_CHANNEL_IMPL_12_H_
10#define BOTAN_TLS_CHANNEL_IMPL_12_H_
11
12#include <botan/tls_alert.h>
13#include <botan/tls_callbacks.h>
14#include <botan/tls_session.h>
15#include <botan/tls_session_manager.h>
16#include <botan/internal/tls_channel_impl.h>
17#include <functional>
18#include <map>
19#include <memory>
20#include <string>
21#include <vector>
22
23namespace Botan {
24
26
27namespace TLS {
28
31class Handshake_State;
33class Client_Hello_12;
34class Server_Hello_12;
35class Policy;
36
37/**
38* Generic interface for TLSv.12 endpoint
39*/
41 public:
42 typedef std::function<void(const uint8_t[], size_t)> output_fn;
43 typedef std::function<void(const uint8_t[], size_t)> data_cb;
44 typedef std::function<void(Alert, const uint8_t[], size_t)> alert_cb;
45 typedef std::function<bool(const Session&)> handshake_cb;
46 typedef std::function<void(const Handshake_Message&)> handshake_msg_cb;
47
48 /**
49 * Set up a new TLS session
50 *
51 * @param callbacks contains a set of callback function references
52 * required by the TLS endpoint.
53 * @param session_manager manages session state
54 * @param rng a random number generator
55 * @param policy specifies other connection policy information
56 * @param is_server whether this is a server session or not
57 * @param is_datagram whether this is a DTLS session
58 * @param io_buf_sz This many bytes of memory will
59 * be preallocated for the read and write buffers. Smaller
60 * values just mean reallocations and copies are more likely.
61 */
62 explicit Channel_Impl_12(const std::shared_ptr<Callbacks>& callbacks,
63 const std::shared_ptr<Session_Manager>& session_manager,
64 const std::shared_ptr<RandomNumberGenerator>& rng,
65 const std::shared_ptr<const Policy>& policy,
66 bool is_server,
67 bool is_datagram,
68 size_t io_buf_sz = TLS::Channel::IO_BUF_DEFAULT_SIZE);
69
70 Channel_Impl_12(const Channel_Impl_12& other) = delete;
72 Channel_Impl_12& operator=(const Channel_Impl_12& other) = delete;
74
75 ~Channel_Impl_12() override;
76
77 size_t from_peer(std::span<const uint8_t> data) override;
78 void to_peer(std::span<const uint8_t> data) override;
79
80 /**
81 * Send a TLS alert message. If the alert is fatal, the internal
82 * state (keys, etc) will be reset.
83 * @param alert the Alert to send
84 */
85 void send_alert(const Alert& alert) override;
86
87 /**
88 * @return true iff the TLS handshake completed successfully
89 */
90 bool is_handshake_complete() const override;
91
92 /**
93 * @return true iff the connection is active for sending application data
94 */
95 bool is_active() const override;
96
97 /**
98 * @return true iff the connection has been definitely closed
99 */
100 bool is_closed() const override;
101
102 bool is_closed_for_reading() const override { return is_closed(); }
103
104 bool is_closed_for_writing() const override { return is_closed(); }
105
106 /**
107 * @return certificate chain of the peer (may be empty)
108 */
109 std::vector<X509_Certificate> peer_cert_chain() const override;
110
111 /**
112 * Note: Raw public key for authentication (RFC7250) is currently not
113 * implemented for TLS 1.2.
114 *
115 * @return raw public key of the peer (will be nullptr)
116 */
117 std::shared_ptr<const Public_Key> peer_raw_public_key() const override { return nullptr; }
118
119 std::optional<std::string> external_psk_identity() const override;
120
121 /**
122 * Key material export (RFC 5705)
123 * @param label a disambiguating label string
124 * @param context a per-association context value
125 * @param length the length of the desired key in bytes
126 * @return key of length bytes
127 */
128 SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override;
129
130 /**
131 * Attempt to renegotiate the session
132 * @param force_full_renegotiation if true, require a full renegotiation,
133 * otherwise allow session resumption
134 */
135 void renegotiate(bool force_full_renegotiation = false) override;
136
137 /**
138 * Attempt to update the session's traffic key material
139 * Note that this is possible with a TLS 1.3 channel, only.
140 *
141 * @param request_peer_update if true, require a reciprocal key update
142 */
143 void update_traffic_keys(bool request_peer_update = false) override;
144
145 /**
146 * @return true iff the counterparty supports the secure
147 * renegotiation extensions.
148 */
149 bool secure_renegotiation_supported() const override;
150
151 /**
152 * Perform a handshake timeout check. This does nothing unless
153 * this is a DTLS channel with a pending handshake state, in
154 * which case we check for timeout and potentially retransmit
155 * handshake packets.
156 */
157 bool timeout_check() override;
158
159 protected:
160 virtual void process_handshake_msg(const Handshake_State* active_state,
161 Handshake_State& pending_state,
162 Handshake_Type type,
163 const std::vector<uint8_t>& contents,
164 bool epoch0_restart) = 0;
165
167 virtual std::unique_ptr<Handshake_State> new_handshake_state(std::unique_ptr<class Handshake_IO> io) = 0;
168
170
171 void activate_session();
172
174
176
177 /* secure renegotiation handling */
178
179 void secure_renegotiation_check(const Client_Hello_12* client_hello);
180 void secure_renegotiation_check(const Server_Hello_12* server_hello);
181
182 std::vector<uint8_t> secure_renegotiation_data_for_client_hello() const;
183 std::vector<uint8_t> secure_renegotiation_data_for_server_hello() const;
184
185 RandomNumberGenerator& rng() { return *m_rng; }
186
187 Session_Manager& session_manager() { return *m_session_manager; }
188
189 const Policy& policy() const { return *m_policy; }
190
191 Callbacks& callbacks() const { return *m_callbacks; }
192
194
195 virtual void initiate_handshake(Handshake_State& state, bool force_full_renegotiation) = 0;
196
197 virtual std::vector<X509_Certificate> get_peer_cert_chain(const Handshake_State& state) const = 0;
198
199 private:
200 void send_record(Record_Type record_type, const std::vector<uint8_t>& record);
201
202 void send_record_under_epoch(uint16_t epoch, Record_Type record_type, const std::vector<uint8_t>& record);
203
204 void send_record_array(uint16_t epoch, Record_Type record_type, const uint8_t input[], size_t length);
205
206 void write_record(
207 Connection_Cipher_State* cipher_state, uint16_t epoch, Record_Type type, const uint8_t input[], size_t length);
208
209 void reset_state();
210
211 Connection_Sequence_Numbers& sequence_numbers() const;
212
213 std::shared_ptr<Connection_Cipher_State> read_cipher_state_epoch(uint16_t epoch) const;
214
215 std::shared_ptr<Connection_Cipher_State> write_cipher_state_epoch(uint16_t epoch) const;
216
217 const Handshake_State* active_state() const { return m_active_state.get(); }
218
219 const Handshake_State* pending_state() const { return m_pending_state.get(); }
220
221 /* methods to handle incoming traffic through Channel_Impl_12::receive_data. */
222 void process_handshake_ccs(const secure_vector<uint8_t>& record,
223 uint64_t record_sequence,
224 Record_Type record_type,
225 Protocol_Version record_version,
226 bool epoch0_restart);
227
228 void process_application_data(uint64_t req_no, const secure_vector<uint8_t>& record);
229
230 void process_alert(const secure_vector<uint8_t>& record);
231
232 const bool m_is_server;
233 const bool m_is_datagram;
234
235 /* callbacks */
236 std::shared_ptr<Callbacks> m_callbacks;
237
238 /* external state */
239 std::shared_ptr<Session_Manager> m_session_manager;
240 std::shared_ptr<const Policy> m_policy;
241 std::shared_ptr<RandomNumberGenerator> m_rng;
242
243 /* sequence number state */
244 std::unique_ptr<Connection_Sequence_Numbers> m_sequence_numbers;
245
246 /* pending and active connection states */
247 std::unique_ptr<Handshake_State> m_active_state;
248 std::unique_ptr<Handshake_State> m_pending_state;
249
250 /* cipher states for each epoch */
251 std::map<uint16_t, std::shared_ptr<Connection_Cipher_State>> m_write_cipher_states;
252 std::map<uint16_t, std::shared_ptr<Connection_Cipher_State>> m_read_cipher_states;
253
254 /* I/O buffers */
255 secure_vector<uint8_t> m_writebuf;
256 secure_vector<uint8_t> m_readbuf;
257 secure_vector<uint8_t> m_record_buf;
258
259 bool m_has_been_closed;
260};
261
262} // namespace TLS
263
264} // namespace Botan
265
266#endif
RandomNumberGenerator & rng()
virtual std::vector< X509_Certificate > get_peer_cert_chain(const Handshake_State &state) const =0
void change_cipher_spec_reader(Connection_Side side)
void inspect_handshake_message(const Handshake_Message &msg)
std::function< void(const uint8_t[], size_t)> data_cb
void update_traffic_keys(bool request_peer_update=false) override
Handshake_State & create_handshake_state(Protocol_Version version)
std::vector< uint8_t > secure_renegotiation_data_for_server_hello() const
bool is_handshake_complete() const override
Channel_Impl_12 & operator=(const Channel_Impl_12 &other)=delete
std::function< bool(const Session &)> handshake_cb
std::shared_ptr< const Public_Key > peer_raw_public_key() const override
size_t from_peer(std::span< const uint8_t > data) override
bool is_closed_for_reading() const override
void secure_renegotiation_check(const Client_Hello_12 *client_hello)
Channel_Impl_12 & operator=(Channel_Impl_12 &&other)=delete
Session_Manager & session_manager()
const Policy & policy() const
void send_alert(const Alert &alert) override
virtual void initiate_handshake(Handshake_State &state, bool force_full_renegotiation)=0
std::function< void(const uint8_t[], size_t)> output_fn
std::vector< X509_Certificate > peer_cert_chain() const override
void to_peer(std::span< const uint8_t > data) override
bool is_closed_for_writing() const override
std::function< void(const Handshake_Message &)> handshake_msg_cb
void change_cipher_spec_writer(Connection_Side side)
std::vector< uint8_t > secure_renegotiation_data_for_client_hello() const
virtual std::unique_ptr< Handshake_State > new_handshake_state(std::unique_ptr< class Handshake_IO > io)=0
Channel_Impl_12(const std::shared_ptr< Callbacks > &callbacks, const std::shared_ptr< Session_Manager > &session_manager, const std::shared_ptr< RandomNumberGenerator > &rng, const std::shared_ptr< const Policy > &policy, bool is_server, bool is_datagram, size_t io_buf_sz=TLS::Channel::IO_BUF_DEFAULT_SIZE)
Channel_Impl_12(const Channel_Impl_12 &other)=delete
SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override
Channel_Impl_12(Channel_Impl_12 &&other)=delete
std::function< void(Alert, const uint8_t[], size_t)> alert_cb
std::optional< std::string > external_psk_identity() const override
virtual void process_handshake_msg(const Handshake_State *active_state, Handshake_State &pending_state, Handshake_Type type, const std::vector< uint8_t > &contents, bool epoch0_restart)=0
bool secure_renegotiation_supported() const override
void renegotiate(bool force_full_renegotiation=false) override
Channel_Impl(const Channel_Impl &other)=delete
static constexpr size_t IO_BUF_DEFAULT_SIZE
Definition tls_channel.h:32
OctetString SymmetricKey
Definition symkey.h:140
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69