Botan 3.14.1
Crypto and TLS for C&
tls_channel.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_H_
12#define BOTAN_TLS_CHANNEL_H_
13
14#include <botan/symkey.h>
15#include <botan/tls_alert.h>
16#include <chrono>
17#include <memory>
18#include <optional>
19#include <span>
20#include <string>
21#include <string_view>
22#include <vector>
23
24namespace Botan {
25
26class Public_Key;
28
29} // namespace Botan
30
31namespace Botan::TLS {
32
33/**
34* Generic interface for TLS endpoint
35*/
37 public:
38 static constexpr size_t IO_BUF_DEFAULT_SIZE = 10 * 1024;
39
40 virtual ~Channel() = default;
41
42 Channel(const Channel& other) = delete;
43 Channel(Channel&& other) = default;
44 Channel& operator=(const Channel& other) = delete;
45 Channel& operator=(Channel&& other) = delete;
46
47 protected:
48 Channel() = default;
49
50 virtual size_t from_peer(std::span<const uint8_t> data) = 0;
51 virtual void to_peer(std::span<const uint8_t> data) = 0;
52
53 public:
54 /**
55 * Inject TLS traffic received from counterparty
56 * @return a hint as to how many more bytes we need to process the
57 * current record (this may be 0 if on a record boundary)
58 */
59 size_t received_data(std::span<const uint8_t> data) { return this->from_peer(data); }
60
61 size_t received_data(const uint8_t buf[], size_t buf_size) { return this->from_peer(std::span(buf, buf_size)); }
62
63 /**
64 * Inject plaintext intended for counterparty
65 * Throws an exception if is_active() is false
66 */
67 void send(std::span<const uint8_t> data) { this->to_peer(data); }
68
69 void send(const uint8_t buf[], size_t buf_size) { this->to_peer(std::span(buf, buf_size)); }
70
71 /**
72 * Inject plaintext intended for counterparty
73 * Throws an exception if is_active() is false
74 */
75 void send(std::string_view s) { this->send({reinterpret_cast<const uint8_t*>(s.data()), s.size()}); }
76
77 /**
78 * Inject plaintext intended for counterparty
79 * Throws an exception if is_active() is false
80 */
81
82 /**
83 * Send a TLS alert message. If the alert is fatal, the internal
84 * state (keys, etc) will be reset.
85 * @param alert the Alert to send
86 */
87 virtual void send_alert(const Alert& alert) = 0;
88
89 /**
90 * Send a warning alert
91 */
92 virtual void send_warning_alert(Alert::Type type) = 0;
93
94 /**
95 * Send a fatal alert
96 */
97 virtual void send_fatal_alert(Alert::Type type) = 0;
98
99 /**
100 * Send a close notification alert
101 */
102 virtual void close() = 0;
103
104 /**
105 * Becomes true as soon as the TLS handshake is fully complete and all
106 * security assurances TLS provides can be guaranteed.
107 *
108 * @returns true once the TLS handshake has finished successfully
109 */
110 virtual bool is_handshake_complete() const = 0;
111
112 /**
113 * Check whether the connection is ready to send application data. Note
114 * that a TLS 1.3 server MAY send data _before_ receiving the client's
115 * Finished message. Only _after_ receiving the client's Finished, can the
116 * server be sure about the client's liveness and (optional) identity.
117 *
118 * Consider using is_handshake_complete() if you need to wait until the
119 * handshake if fully complete.
120 *
121 * @return true iff the connection is active for sending application data
122 */
123 virtual bool is_active() const = 0;
124
125 /**
126 * @return the remaining time until timeout_check() might retransmit
127 * handshake data, or std::nullopt if no timeout check is needed.
128 */
129 BOTAN_DEPRECATED("Use TLS::Callbacks::tls_register_deferred_operation instead") //
130 virtual std::optional<std::chrono::milliseconds> next_retransmission_timeout() const = 0;
131
132 /**
133 * Note: For TLS 1.3 a connection is closed only after both peers have
134 * signaled a "close_notify". While TLS 1.2 automatically responded
135 * in suit once the peer had sent "close_notify", TLS 1.3 allows to
136 * continue transmitting data even if the peer closed their writing
137 * end.
138 *
139 * @return true iff the connection has been definitely closed
140 */
141 virtual bool is_closed() const = 0;
142
143 /**
144 * @return true iff the peer closed their channel
145 * (i.e. no more incoming data expected)
146 */
147 virtual bool is_closed_for_reading() const = 0;
148
149 /**
150 * @return true iff we closed our channel
151 * (i.e. no more outgoing data allowed)
152 */
153 virtual bool is_closed_for_writing() const = 0;
154
155 /**
156 * @return certificate chain of the peer (may be empty)
157 */
158 virtual std::vector<X509_Certificate> peer_cert_chain() const = 0;
159
160 /**
161 * @return raw public key of the peer (may be nullptr)
162 */
163 virtual std::shared_ptr<const Public_Key> peer_raw_public_key() const = 0;
164
165 /**
166 * @return identity of the PSK used for this connection
167 * or std::nullopt if no PSK was used.
168 */
169 virtual std::optional<std::string> external_psk_identity() const = 0;
170
171 /**
172 * Key material export (RFC 5705)
173 * @param label a disambiguating label string
174 * @param context a per-association context value
175 * @param length the length of the desired key in bytes
176 * @return key of length bytes
177 */
178 virtual SymmetricKey key_material_export(std::string_view label,
179 std::string_view context,
180 size_t length) const = 0;
181
182 /**
183 * Attempt to renegotiate the session
184 * @param force_full_renegotiation if true, require a full renegotiation,
185 * otherwise allow session resumption
186 */
187 virtual void renegotiate(bool force_full_renegotiation = false) = 0;
188
189 /**
190 * Attempt to update the session's traffic key material
191 * Note that this is possible with a TLS 1.3 channel, only.
192 *
193 * @param request_peer_update if true, require a reciprocal key update
194 */
195 virtual void update_traffic_keys(bool request_peer_update = false) = 0;
196
197 /**
198 * @return true iff the counterparty supports the secure
199 * renegotiation extensions.
200 */
201 virtual bool secure_renegotiation_supported() const = 0;
202
203 /**
204 * Perform a handshake timeout check.
205 *
206 * This function does nothing unless the channel represents a DTLS connection with
207 * a handshake in progress.
208 *
209 * Consider using ``Callbacks::tls_register_deferred_operation`` introduced
210 * in Botan 3.14.0 to handle retransmission timers transparently instead of
211 * polling this function at regular intervals. Never do both, though!
212 *
213 * By default after a certain interval where no progress has been made in the
214 * handshake (controlled by the policy values `TLS::Policy::dtls_initial_timeout`,
215 * `TLS::Policy::dtls_maximum_timeout`, and `TLS::Policy::dtls_maximum_retransmissions`),
216 * calling `timeout_check` will throw indicating the handshake has failed to
217 * complete. If you wish to never fully timeout, this can be accomplished by
218 * overriding `TLS::Policy::dtls_maximum_retransmissions` to return `std::nullopt`,
219 * in which case a handshake attempt will retry indefinitely.
220 *
221 * @returns true if a timeout condition occurred
222 */
223 BOTAN_DEPRECATED("Use TLS::Callbacks::tls_register_deferred_operation instead") //
224 virtual bool timeout_check() = 0;
225
226 virtual std::string application_protocol() const = 0;
227};
228} // namespace Botan::TLS
229
230#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
AlertType Type
Definition tls_alert.h:73
virtual size_t from_peer(std::span< const uint8_t > data)=0
virtual bool secure_renegotiation_supported() const =0
virtual void update_traffic_keys(bool request_peer_update=false)=0
Channel(const Channel &other)=delete
virtual void send_fatal_alert(Alert::Type type)=0
virtual ~Channel()=default
virtual bool timeout_check()=0
virtual bool is_handshake_complete() const =0
size_t received_data(std::span< const uint8_t > data)
Definition tls_channel.h:59
virtual SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const =0
void send(const uint8_t buf[], size_t buf_size)
Definition tls_channel.h:69
virtual std::string application_protocol() const =0
virtual std::vector< X509_Certificate > peer_cert_chain() const =0
virtual bool is_closed_for_writing() const =0
Channel & operator=(const Channel &other)=delete
virtual std::optional< std::chrono::milliseconds > next_retransmission_timeout() const =0
virtual bool is_closed_for_reading() const =0
virtual std::shared_ptr< const Public_Key > peer_raw_public_key() const =0
virtual void send_warning_alert(Alert::Type type)=0
virtual bool is_active() const =0
virtual void close()=0
size_t received_data(const uint8_t buf[], size_t buf_size)
Definition tls_channel.h:61
Channel & operator=(Channel &&other)=delete
virtual void to_peer(std::span< const uint8_t > data)=0
void send(std::span< const uint8_t > data)
Definition tls_channel.h:67
static constexpr size_t IO_BUF_DEFAULT_SIZE
Definition tls_channel.h:38
virtual void send_alert(const Alert &alert)=0
void send(std::string_view s)
Definition tls_channel.h:75
Channel(Channel &&other)=default
virtual std::optional< std::string > external_psk_identity() const =0
virtual bool is_closed() const =0
virtual void renegotiate(bool force_full_renegotiation=false)=0
OctetString SymmetricKey
Definition symkey.h:153