Botan 3.5.0
Crypto and TLS for C&
Botan::TLS::Channel Class Referenceabstract

#include <tls_channel.h>

Inheritance diagram for Botan::TLS::Channel:
Botan::TLS::Client Botan::TLS::Server

Public Member Functions

virtual std::string application_protocol () const =0
 
virtual void close ()=0
 
virtual std::optional< std::string > external_psk_identity () const =0
 
virtual bool is_active () const =0
 
virtual bool is_closed () const =0
 
virtual bool is_closed_for_reading () const =0
 
virtual bool is_closed_for_writing () const =0
 
virtual bool is_handshake_complete () const =0
 
virtual SymmetricKey key_material_export (std::string_view label, std::string_view context, size_t length) const =0
 
virtual std::vector< X509_Certificatepeer_cert_chain () const =0
 
virtual std::shared_ptr< const Public_Keypeer_raw_public_key () const =0
 
size_t received_data (const uint8_t buf[], size_t buf_size)
 
size_t received_data (std::span< const uint8_t > data)
 
virtual void renegotiate (bool force_full_renegotiation=false)=0
 
virtual bool secure_renegotiation_supported () const =0
 
void send (const uint8_t buf[], size_t buf_size)
 
void send (std::span< const uint8_t > data)
 
void send (std::string_view val)
 
virtual void send_alert (const Alert &alert)=0
 
virtual void send_fatal_alert (Alert::Type type)=0
 
virtual void send_warning_alert (Alert::Type type)=0
 
virtual bool timeout_check ()=0
 
virtual void update_traffic_keys (bool request_peer_update=false)=0
 
virtual ~Channel ()=default
 

Static Public Attributes

static constexpr size_t IO_BUF_DEFAULT_SIZE = 10 * 1024
 

Protected Member Functions

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

Detailed Description

Generic interface for TLS endpoint

Definition at line 30 of file tls_channel.h.

Constructor & Destructor Documentation

◆ ~Channel()

virtual Botan::TLS::Channel::~Channel ( )
virtualdefault

Member Function Documentation

◆ application_protocol()

virtual std::string Botan::TLS::Channel::application_protocol ( ) const
pure virtual

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ close()

virtual void Botan::TLS::Channel::close ( )
pure virtual

Send a close notification alert

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ external_psk_identity()

virtual std::optional< std::string > Botan::TLS::Channel::external_psk_identity ( ) const
pure virtual
Returns
identity of the PSK used for this connection or std::nullopt if no PSK was used.

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ from_peer()

virtual size_t Botan::TLS::Channel::from_peer ( std::span< const uint8_t > data)
protectedpure virtual

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ is_active()

virtual bool Botan::TLS::Channel::is_active ( ) const
pure virtual

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.

Returns
true iff the connection is active for sending application data

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ is_closed()

virtual bool Botan::TLS::Channel::is_closed ( ) const
pure virtual

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.

Returns
true iff the connection has been definitely closed

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ is_closed_for_reading()

virtual bool Botan::TLS::Channel::is_closed_for_reading ( ) const
pure virtual
Returns
true iff the peer closed their channel (i.e. no more incoming data expected)

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ is_closed_for_writing()

virtual bool Botan::TLS::Channel::is_closed_for_writing ( ) const
pure virtual
Returns
true iff we closed our channel (i.e. no more outgoing data allowed)

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ is_handshake_complete()

virtual bool Botan::TLS::Channel::is_handshake_complete ( ) const
pure virtual

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

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ key_material_export()

virtual SymmetricKey Botan::TLS::Channel::key_material_export ( std::string_view label,
std::string_view context,
size_t length ) const
pure virtual

Key material export (RFC 5705)

Parameters
labela disambiguating label string
contexta per-association context value
lengththe length of the desired key in bytes
Returns
key of length bytes

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ peer_cert_chain()

virtual std::vector< X509_Certificate > Botan::TLS::Channel::peer_cert_chain ( ) const
pure virtual
Returns
certificate chain of the peer (may be empty)

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ peer_raw_public_key()

virtual std::shared_ptr< const Public_Key > Botan::TLS::Channel::peer_raw_public_key ( ) const
pure virtual
Returns
raw public key of the peer (may be nullptr)

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ received_data() [1/2]

size_t Botan::TLS::Channel::received_data ( const uint8_t buf[],
size_t buf_size )
inline

Definition at line 48 of file tls_channel.h.

48{ return this->from_peer(std::span(buf, buf_size)); }
virtual size_t from_peer(std::span< const uint8_t > data)=0

◆ received_data() [2/2]

size_t Botan::TLS::Channel::received_data ( std::span< const uint8_t > data)
inline

Inject TLS traffic received from counterparty

Returns
a hint as to how many more bytes we need to process the current record (this may be 0 if on a record boundary)

Definition at line 46 of file tls_channel.h.

46{ return this->from_peer(data); }

◆ renegotiate()

virtual void Botan::TLS::Channel::renegotiate ( bool force_full_renegotiation = false)
pure virtual

Attempt to renegotiate the session

Parameters
force_full_renegotiationif true, require a full renegotiation, otherwise allow session resumption

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ secure_renegotiation_supported()

virtual bool Botan::TLS::Channel::secure_renegotiation_supported ( ) const
pure virtual
Returns
true iff the counterparty supports the secure renegotiation extensions.

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ send() [1/3]

void Botan::TLS::Channel::send ( const uint8_t buf[],
size_t buf_size )
inline

Definition at line 56 of file tls_channel.h.

56{ this->to_peer(std::span(buf, buf_size)); }
virtual void to_peer(std::span< const uint8_t > data)=0

◆ send() [2/3]

void Botan::TLS::Channel::send ( std::span< const uint8_t > data)
inline

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

Definition at line 54 of file tls_channel.h.

54{ this->to_peer(data); }

◆ send() [3/3]

void Botan::TLS::Channel::send ( std::string_view val)
inline

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

Definition at line 62 of file tls_channel.h.

62{ this->send(std::span(cast_char_ptr_to_uint8(val.data()), val.size())); }
void send(std::span< const uint8_t > data)
Definition tls_channel.h:54
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition mem_ops.h:273

References Botan::cast_char_ptr_to_uint8(), and send().

Referenced by send().

◆ send_alert()

virtual void Botan::TLS::Channel::send_alert ( const Alert & alert)
pure virtual

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.

Parameters
alertthe Alert to send

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ send_fatal_alert()

virtual void Botan::TLS::Channel::send_fatal_alert ( Alert::Type type)
pure virtual

Send a fatal alert

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ send_warning_alert()

virtual void Botan::TLS::Channel::send_warning_alert ( Alert::Type type)
pure virtual

Send a warning alert

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ timeout_check()

virtual bool Botan::TLS::Channel::timeout_check ( )
pure virtual

Perform a handshake timeout check. This does nothing unless this is a DTLS channel with a pending handshake state, in which case we check for timeout and potentially retransmit handshake packets.

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ to_peer()

virtual void Botan::TLS::Channel::to_peer ( std::span< const uint8_t > data)
protectedpure virtual

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

◆ update_traffic_keys()

virtual void Botan::TLS::Channel::update_traffic_keys ( bool request_peer_update = false)
pure virtual

Attempt to update the session's traffic key material Note that this is possible with a TLS 1.3 channel, only.

Parameters
request_peer_updateif true, require a reciprocal key update

Implemented in Botan::TLS::Client, and Botan::TLS::Server.

Member Data Documentation

◆ IO_BUF_DEFAULT_SIZE

size_t Botan::TLS::Channel::IO_BUF_DEFAULT_SIZE = 10 * 1024
staticconstexpr

Definition at line 32 of file tls_channel.h.

Referenced by Botan::TLS::Channel_Impl_13::expect_downgrade().


The documentation for this class was generated from the following file: