/src/botan/build/include/public/botan/tls_channel.h

Source
/*
* TLS Channel
* (C) 2011,2012,2014,2015 Jack Lloyd
*     2016 Matthias Gierlings
*     2021 Elektrobit Automotive GmbH
*     2022 René Meusel, Hannes Rantzsch - neXenio GmbH
*
* Botan is released under the Simplified BSD License (see license.txt)
*/

#ifndef BOTAN_TLS_CHANNEL_H_
#define BOTAN_TLS_CHANNEL_H_

#include <botan/symkey.h>
#include <botan/tls_alert.h>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <vector>

namespace Botan {

class Public_Key;
class X509_Certificate;

}  // namespace Botan

namespace Botan::TLS {

/**
* Generic interface for TLS endpoint
*/
class BOTAN_PUBLIC_API(2, 0) Channel {
   public:
      static constexpr size_t IO_BUF_DEFAULT_SIZE = 10 * 1024;

      virtual ~Channel() = default;

      Channel(const Channel& other) = delete;
      Channel(Channel&& other) = default;
      Channel& operator=(const Channel& other) = delete;
      Channel& operator=(Channel&& other) = delete;

   protected:
      Channel() = default;

      virtual size_t from_peer(std::span<const uint8_t> data) = 0;
      virtual void to_peer(std::span<const uint8_t> data) = 0;

   public:
      /**
      * Inject TLS traffic received from counterparty
      * @return a hint as to how many more bytes we need to process the
      *         current record (this may be 0 if on a record boundary)
      */
      size_t received_data(std::span<const uint8_t> data) { return this->from_peer(data); }

      size_t received_data(const uint8_t buf[], size_t buf_size) { return this->from_peer(std::span(buf, buf_size)); }

      /**
      * Inject plaintext intended for counterparty
      * Throws an exception if is_active() is false
      */
      void send(std::span<const uint8_t> data) { this->to_peer(data); }

      void send(const uint8_t buf[], size_t buf_size) { this->to_peer(std::span(buf, buf_size)); }

      /**
      * Inject plaintext intended for counterparty
      * Throws an exception if is_active() is false
      */
      void send(std::string_view s) { this->send({reinterpret_cast<const uint8_t*>(s.data()), s.size()}); }

      /**
      * Inject plaintext intended for counterparty
      * Throws an exception if is_active() is false
      */

      /**
      * Send a TLS alert message. If the alert is fatal, the internal
      * state (keys, etc) will be reset.
      * @param alert the Alert to send
      */
      virtual void send_alert(const Alert& alert) = 0;

      /**
      * Send a warning alert
      */
      virtual void send_warning_alert(Alert::Type type) = 0;

      /**
      * Send a fatal alert
      */
      virtual void send_fatal_alert(Alert::Type type) = 0;

      /**
      * Send a close notification alert
      */
      virtual void close() = 0;

      /**
      * Becomes true as soon as the TLS handshake is fully complete and all
      * security assurances TLS provides can be guaranteed.
      *
      * @returns true once the TLS handshake has finished successfully
      */
      virtual bool is_handshake_complete() const = 0;

      /**
      * Check whether the connection is ready to send application data. Note
      * that a TLS 1.3 server MAY send data _before_ receiving the client's
      * Finished message. Only _after_ receiving the client's Finished, can the
      * server be sure about the client's liveness and (optional) identity.
      *
      * Consider using is_handshake_complete() if you need to wait until the
      * handshake if fully complete.
      *
      * @return true iff the connection is active for sending application data
      */
      virtual bool is_active() const = 0;

      /**
      * Note: For TLS 1.3 a connection is closed only after both peers have
      *       signaled a "close_notify". While TLS 1.2 automatically responded
      *       in suit once the peer had sent "close_notify", TLS 1.3 allows to
      *       continue transmitting data even if the peer closed their writing
      *       end.
      *
      * @return true iff the connection has been definitely closed
      */
      virtual bool is_closed() const = 0;

      /**
      * @return true iff the peer closed their channel
      *         (i.e. no more incoming data expected)
      */
      virtual bool is_closed_for_reading() const = 0;

      /**
      * @return true iff we closed our channel
      *         (i.e. no more outgoing data allowed)
      */
      virtual bool is_closed_for_writing() const = 0;

      /**
      * @return certificate chain of the peer (may be empty)
      */
      virtual std::vector<X509_Certificate> peer_cert_chain() const = 0;

      /**
      * @return raw public key of the peer (may be nullptr)
      */
      virtual std::shared_ptr<const Public_Key> peer_raw_public_key() const = 0;

      /**
       * @return identity of the PSK used for this connection
       *         or std::nullopt if no PSK was used.
       */
      virtual std::optional<std::string> external_psk_identity() const = 0;

      /**
      * Key material export (RFC 5705)
      * @param label a disambiguating label string
      * @param context a per-association context value
      * @param length the length of the desired key in bytes
      * @return key of length bytes
      */
      virtual SymmetricKey key_material_export(std::string_view label,
                                               std::string_view context,
                                               size_t length) const = 0;

      /**
      * Attempt to renegotiate the session
      * @param force_full_renegotiation if true, require a full renegotiation,
      * otherwise allow session resumption
      */
      virtual void renegotiate(bool force_full_renegotiation = false) = 0;

      /**
      * Attempt to update the session's traffic key material
      * Note that this is possible with a TLS 1.3 channel, only.
      *
      * @param request_peer_update if true, require a reciprocal key update
      */
      virtual void update_traffic_keys(bool request_peer_update = false) = 0;

      /**
      * @return true iff the counterparty supports the secure
      * renegotiation extensions.
      */
      virtual bool secure_renegotiation_supported() const = 0;

      /**
      * Perform a handshake timeout check.
      *
      * This function does nothing unless the channel represents a DTLS
      * connection and a handshake is actively in progress. In this case it will
      * check the current timeout state and potentially initiate retransmission
      * of handshake packets.
      *
      * @returns true if a timeout condition occurred
      */
      virtual bool timeout_check() = 0;

      virtual std::string application_protocol() const = 0;
};
}  // namespace Botan::TLS

#endif

Coverage Report

Created: 2026-03-19 06:24

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