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