Botan 3.3.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
25class X509_Certificate;
26
27namespace TLS {
28
29class Connection_Cipher_State;
30class Connection_Sequence_Numbers;
31class Handshake_State;
32class Handshake_Message;
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 explicit Channel_Impl_12(const Channel_Impl_12&) = delete;
71
73
74 ~Channel_Impl_12() override;
75
76 size_t from_peer(std::span<const uint8_t> data) override;
77 void to_peer(std::span<const uint8_t> data) override;
78
79 /**
80 * Send a TLS alert message. If the alert is fatal, the internal
81 * state (keys, etc) will be reset.
82 * @param alert the Alert to send
83 */
84 void send_alert(const Alert& alert) override;
85
86 /**
87 * @return true iff the TLS handshake completed successfully
88 */
89 bool is_handshake_complete() const override;
90
91 /**
92 * @return true iff the connection is active for sending application data
93 */
94 bool is_active() const override;
95
96 /**
97 * @return true iff the connection has been definitely closed
98 */
99 bool is_closed() const override;
100
101 bool is_closed_for_reading() const override { return is_closed(); }
102
103 bool is_closed_for_writing() const override { return is_closed(); }
104
105 /**
106 * @return certificate chain of the peer (may be empty)
107 */
108 std::vector<X509_Certificate> peer_cert_chain() const override;
109
110 /**
111 * Note: Raw public key for authentication (RFC7250) is currently not
112 * implemented for TLS 1.2.
113 *
114 * @return raw public key of the peer (will be nullptr)
115 */
116 std::shared_ptr<const Public_Key> peer_raw_public_key() const override { return nullptr; }
117
118 std::optional<std::string> external_psk_identity() const override;
119
120 /**
121 * Key material export (RFC 5705)
122 * @param label a disambiguating label string
123 * @param context a per-association context value
124 * @param length the length of the desired key in bytes
125 * @return key of length bytes
126 */
127 SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override;
128
129 /**
130 * Attempt to renegotiate the session
131 * @param force_full_renegotiation if true, require a full renegotiation,
132 * otherwise allow session resumption
133 */
134 void renegotiate(bool force_full_renegotiation = false) override;
135
136 /**
137 * Attempt to update the session's traffic key material
138 * Note that this is possible with a TLS 1.3 channel, only.
139 *
140 * @param request_peer_update if true, require a reciprocal key update
141 */
142 void update_traffic_keys(bool request_peer_update = false) override;
143
144 /**
145 * @return true iff the counterparty supports the secure
146 * renegotiation extensions.
147 */
148 bool secure_renegotiation_supported() const override;
149
150 /**
151 * Perform a handshake timeout check. This does nothing unless
152 * this is a DTLS channel with a pending handshake state, in
153 * which case we check for timeout and potentially retransmit
154 * handshake packets.
155 */
156 bool timeout_check() override;
157
158 protected:
159 virtual void process_handshake_msg(const Handshake_State* active_state,
160 Handshake_State& pending_state,
161 Handshake_Type type,
162 const std::vector<uint8_t>& contents,
163 bool epoch0_restart) = 0;
164
166 virtual std::unique_ptr<Handshake_State> new_handshake_state(std::unique_ptr<class Handshake_IO> io) = 0;
167
169
170 void activate_session();
171
173
175
176 /* secure renegotiation handling */
177
178 void secure_renegotiation_check(const Client_Hello_12* client_hello);
179 void secure_renegotiation_check(const Server_Hello_12* server_hello);
180
181 std::vector<uint8_t> secure_renegotiation_data_for_client_hello() const;
182 std::vector<uint8_t> secure_renegotiation_data_for_server_hello() const;
183
184 RandomNumberGenerator& rng() { return *m_rng; }
185
186 Session_Manager& session_manager() { return *m_session_manager; }
187
188 const Policy& policy() const { return *m_policy; }
189
190 Callbacks& callbacks() const { return *m_callbacks; }
191
193
194 virtual void initiate_handshake(Handshake_State& state, bool force_full_renegotiation) = 0;
195
196 virtual std::vector<X509_Certificate> get_peer_cert_chain(const Handshake_State& state) const = 0;
197
198 private:
199 void send_record(Record_Type record_type, const std::vector<uint8_t>& record);
200
201 void send_record_under_epoch(uint16_t epoch, Record_Type record_type, const std::vector<uint8_t>& record);
202
203 void send_record_array(uint16_t epoch, Record_Type record_type, const uint8_t input[], size_t length);
204
205 void write_record(
206 Connection_Cipher_State* cipher_state, uint16_t epoch, Record_Type type, const uint8_t input[], size_t length);
207
208 void reset_state();
209
210 Connection_Sequence_Numbers& sequence_numbers() const;
211
212 std::shared_ptr<Connection_Cipher_State> read_cipher_state_epoch(uint16_t epoch) const;
213
214 std::shared_ptr<Connection_Cipher_State> write_cipher_state_epoch(uint16_t epoch) const;
215
216 const Handshake_State* active_state() const { return m_active_state.get(); }
217
218 const Handshake_State* pending_state() const { return m_pending_state.get(); }
219
220 /* methods to handle incoming traffic through Channel_Impl_12::receive_data. */
221 void process_handshake_ccs(const secure_vector<uint8_t>& record,
222 uint64_t record_sequence,
223 Record_Type record_type,
224 Protocol_Version record_version,
225 bool epoch0_restart);
226
227 void process_application_data(uint64_t req_no, const secure_vector<uint8_t>& record);
228
229 void process_alert(const secure_vector<uint8_t>& record);
230
231 const bool m_is_server;
232 const bool m_is_datagram;
233
234 /* callbacks */
235 std::shared_ptr<Callbacks> m_callbacks;
236
237 /* external state */
238 std::shared_ptr<Session_Manager> m_session_manager;
239 std::shared_ptr<const Policy> m_policy;
240 std::shared_ptr<RandomNumberGenerator> m_rng;
241
242 /* sequence number state */
243 std::unique_ptr<Connection_Sequence_Numbers> m_sequence_numbers;
244
245 /* pending and active connection states */
246 std::unique_ptr<Handshake_State> m_active_state;
247 std::unique_ptr<Handshake_State> m_pending_state;
248
249 /* cipher states for each epoch */
250 std::map<uint16_t, std::shared_ptr<Connection_Cipher_State>> m_write_cipher_states;
251 std::map<uint16_t, std::shared_ptr<Connection_Cipher_State>> m_read_cipher_states;
252
253 /* I/O buffers */
254 secure_vector<uint8_t> m_writebuf;
255 secure_vector<uint8_t> m_readbuf;
256 secure_vector<uint8_t> m_record_buf;
257
258 bool m_has_been_closed;
259};
260
261} // namespace TLS
262
263} // namespace Botan
264
265#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)
Channel_Impl_12 & operator=(const Channel_Impl_12 &)=delete
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
std::function< void(const Handshake_Message &) handshake_msg_cb)
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
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)
Session_Manager & session_manager()
Channel_Impl_12(const Channel_Impl_12 &)=delete
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< bool(const Session &) handshake_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)
SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override
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
static constexpr size_t IO_BUF_DEFAULT_SIZE
Definition tls_channel.h:32
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61