#include <tls_client.h>

Inheritance diagram for Botan::TLS::Client:

Public Member Functions
std::string	application_protocol () const override

	Client (const std::shared_ptr< Callbacks > &callbacks, const std::shared_ptr< Session_Manager > &session_manager, const std::shared_ptr< Credentials_Manager > &creds, const std::shared_ptr< const Policy > &policy, const std::shared_ptr< RandomNumberGenerator > &rng, Server_Information server_info=Server_Information(), Protocol_Version offer_version=Protocol_Version::latest_tls_version(), const std::vector< std::string > &next_protocols={}, size_t reserved_io_buffer_size=TLS::Client::IO_BUF_DEFAULT_SIZE)

void	close () override

std::optional< std::string >	external_psk_identity () const override

size_t	from_peer (std::span< const uint8_t > data) override

bool	is_active () const override

bool	is_closed () const override

bool	is_closed_for_reading () const override

bool	is_closed_for_writing () const override

bool	is_handshake_complete () const override

SymmetricKey	key_material_export (std::string_view label, std::string_view context, size_t length) const override

std::vector< X509_Certificate >	peer_cert_chain () const override

std::shared_ptr< const Public_Key >	peer_raw_public_key () const override

size_t	received_data (const uint8_t buf[], size_t buf_size)

size_t	received_data (std::span< const uint8_t > data)

void	renegotiate (bool force_full_renegotiation=false) override

bool	secure_renegotiation_supported () const override

void	send (const uint8_t buf[], size_t buf_size)

void	send (std::span< const uint8_t > data)

void	send (std::string_view val)

void	send_alert (const Alert &alert) override

void	send_fatal_alert (Alert::Type type) override

void	send_warning_alert (Alert::Type type) override

bool	timeout_check () override

void	to_peer (std::span< const uint8_t > data) override

void	update_traffic_keys (bool request_peer_update=false) override

	~Client () override

Static Public Attributes
static constexpr size_t	IO_BUF_DEFAULT_SIZE = 10 * 1024

Detailed Description

SSL/TLS Client

Definition at line 28 of file tls_client.h.

Constructor & Destructor Documentation

◆ Client()

Botan::TLS::Client::Client	(	const std::shared_ptr< Callbacks > &	callbacks,
		const std::shared_ptr< Session_Manager > &	session_manager,
		const std::shared_ptr< Credentials_Manager > &	creds,
		const std::shared_ptr< const Policy > &	policy,
		const std::shared_ptr< RandomNumberGenerator > &	rng,
		Server_Information	server_info = Server_Information(),
		Protocol_Version	offer_version = Protocol_Version::latest_tls_version(),
		const std::vector< std::string > &	next_protocols = {},
		size_t	reserved_io_buffer_size = TLS::Client::IO_BUF_DEFAULT_SIZE )

Set up a new TLS client session

Parameters

callbacks	contains a set of callback function references required by the TLS client.
session_manager	manages session state
creds	manages application/user credentials
policy	specifies other connection policy information
rng	a random number generator
server_info	is identifying information about the TLS server
offer_version	specifies which version we will offer to the TLS server.
next_protocols	specifies protocols to advertise with ALPN
reserved_io_buffer_size	This many bytes of memory will be preallocated for the read and write buffers. Smaller values just mean reallocations and copies are more likely.

Definition at line 30 of file tls_client.cpp.

                                 {
   BOTAN_ARG_CHECK(policy->acceptable_protocol_version(offer_version),
                   "Policy does not allow to offer requested protocol version");
 
#if defined(BOTAN_HAS_TLS_13)
   if(offer_version == Protocol_Version::TLS_V13) {
      m_impl = std::make_unique<Client_Impl_13>(
         callbacks, session_manager, creds, policy, rng, std::move(info), next_protocols);
 
      if(m_impl->expects_downgrade()) {
         m_impl->set_io_buffer_size(io_buf_sz);
      }
 
      if(m_impl->is_downgrading()) {
         // TLS 1.3 implementation found a resumable TLS 1.2 session and
         // requested a downgrade right away.
         downgrade();
      }
 
      return;
   }
#endif
 
   m_impl = std::make_unique<Client_Impl_12>(callbacks,
                                             session_manager,
                                             creds,
                                             policy,
                                             rng,
                                             std::move(info),
                                             offer_version.is_datagram_protocol(),
                                             next_protocols,
                                             io_buf_sz);
}

References BOTAN_ARG_CHECK, and Botan::TLS::Protocol_Version::is_datagram_protocol().

◆ ~Client()

Botan::TLS::Client::~Client ( )

overridedefault

Member Function Documentation

◆ application_protocol()

std::string Botan::TLS::Client::application_protocol ( ) const

overridevirtual

Returns: network protocol as advertised by the TLS server, if server sent the ALPN extension

Implements Botan::TLS::Channel.

Definition at line 172 of file tls_client.cpp.

                                             {
   return m_impl->application_protocol();
}

◆ close()

void Botan::TLS::Client::close ( )

overridevirtual

Send a close notification alert

Implements Botan::TLS::Channel.

Definition at line 164 of file tls_client.cpp.

                   {
   m_impl->close();
}

◆ external_psk_identity()

std::optional< std::string > Botan::TLS::Client::external_psk_identity ( ) const

overridevirtual

Returns: identity of the PSK used for this connection or std::nullopt if no PSK was used.

Implements Botan::TLS::Channel.

Definition at line 128 of file tls_client.cpp.

                                                           {
   return m_impl->external_psk_identity();
}

◆ from_peer()

size_t Botan::TLS::Client::from_peer ( std::span< const uint8_t > data )

overridevirtual

Implements Botan::TLS::Channel.

Definition at line 90 of file tls_client.cpp.

                                                    {
   auto read = m_impl->from_peer(data);
 
   if(m_impl->is_downgrading()) {
      read = downgrade();
   }
 
   return read;
}

◆ is_active()

bool Botan::TLS::Client::is_active ( ) const

overridevirtual

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

Implements Botan::TLS::Channel.

Definition at line 104 of file tls_client.cpp.

                             {
   return m_impl->is_active();
}

◆ is_closed()

bool Botan::TLS::Client::is_closed ( ) const

overridevirtual

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

Implements Botan::TLS::Channel.

Definition at line 108 of file tls_client.cpp.

                             {
   return m_impl->is_closed();
}

◆ is_closed_for_reading()

bool Botan::TLS::Client::is_closed_for_reading ( ) const

overridevirtual

Returns: true iff the peer closed their channel (i.e. no more incoming data expected)

Implements Botan::TLS::Channel.

Definition at line 112 of file tls_client.cpp.

                                         {
   return m_impl->is_closed_for_reading();
}

◆ is_closed_for_writing()

bool Botan::TLS::Client::is_closed_for_writing ( ) const

overridevirtual

Returns: true iff we closed our channel (i.e. no more outgoing data allowed)

Implements Botan::TLS::Channel.

Definition at line 116 of file tls_client.cpp.

                                         {
   return m_impl->is_closed_for_writing();
}

◆ is_handshake_complete()

bool Botan::TLS::Client::is_handshake_complete ( ) const

overridevirtual

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

Implements Botan::TLS::Channel.

Definition at line 100 of file tls_client.cpp.

                                         {
   return m_impl->is_handshake_complete();
}

◆ key_material_export()

SymmetricKey Botan::TLS::Client::key_material_export	(	std::string_view	label,
		std::string_view	context,
		size_t	length ) const

overridevirtual

Key material export (RFC 5705)

Parameters

label	a disambiguating label string
context	a per-association context value
length	the length of the desired key in bytes

Returns: key of length bytes

Implements Botan::TLS::Channel.

Definition at line 132 of file tls_client.cpp.

                                                                                                          {
   return m_impl->key_material_export(label, context, length);
}

◆ peer_cert_chain()

std::vector< X509_Certificate > Botan::TLS::Client::peer_cert_chain ( ) const

overridevirtual

Returns: certificate chain of the peer (may be empty)

Implements Botan::TLS::Channel.

Definition at line 120 of file tls_client.cpp.

                                                          {
   return m_impl->peer_cert_chain();
}

◆ peer_raw_public_key()

std::shared_ptr< const Public_Key > Botan::TLS::Client::peer_raw_public_key ( ) const

overridevirtual

Returns: raw public key of the peer (may be nullptr)

Implements Botan::TLS::Channel.

Definition at line 124 of file tls_client.cpp.

                                                                  {
   return m_impl->peer_raw_public_key();
}

◆ received_data() [1/2]

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

inlineinherited

Definition at line 48 of file tls_channel.h.

48{ return this->from_peer(std::span(buf, buf_size)); }

Botan::TLS::Channel::from_peer

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 )

inlineinherited

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()

void Botan::TLS::Client::renegotiate ( bool force_full_renegotiation = false )

overridevirtual

Attempt to renegotiate the session

Parameters

force_full_renegotiation if true, require a full renegotiation, otherwise allow session resumption

Implements Botan::TLS::Channel.

Definition at line 136 of file tls_client.cpp.

                                                      {
   m_impl->renegotiate(force_full_renegotiation);
}

◆ secure_renegotiation_supported()

bool Botan::TLS::Client::secure_renegotiation_supported ( ) const

overridevirtual

Returns: true iff the counterparty supports the secure renegotiation extensions.

Implements Botan::TLS::Channel.

Definition at line 144 of file tls_client.cpp.

                                                  {
   return m_impl->secure_renegotiation_supported();
}

◆ send() [1/3]

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

inlineinherited

Definition at line 56 of file tls_channel.h.

56{ this->to_peer(std::span(buf, buf_size)); }

Botan::TLS::Channel::to_peer

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 )

inlineinherited

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 )

inlineinherited

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())); }

Botan::TLS::Channel::send

void send(std::span< const uint8_t > data)

Definition tls_channel.h:54

Botan::cast_char_ptr_to_uint8

const uint8_t * cast_char_ptr_to_uint8(const char *s)

Definition mem_ops.h:275

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

Referenced by Botan::TLS::Channel::send().

◆ send_alert()

void Botan::TLS::Client::send_alert ( const Alert & alert )

overridevirtual

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

alert the Alert to send

Implements Botan::TLS::Channel.

Definition at line 152 of file tls_client.cpp.

                                          {
   m_impl->send_alert(alert);
}

◆ send_fatal_alert()

void Botan::TLS::Client::send_fatal_alert ( Alert::Type type )

overridevirtual

Send a fatal alert

Implements Botan::TLS::Channel.

Definition at line 160 of file tls_client.cpp.

                                            {
   m_impl->send_fatal_alert(type);
}

◆ send_warning_alert()

void Botan::TLS::Client::send_warning_alert ( Alert::Type type )

overridevirtual

Send a warning alert

Implements Botan::TLS::Channel.

Definition at line 156 of file tls_client.cpp.

                                              {
   m_impl->send_warning_alert(type);
}

◆ timeout_check()

bool Botan::TLS::Client::timeout_check ( )

overridevirtual

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.

Implements Botan::TLS::Channel.

Definition at line 168 of file tls_client.cpp.

                           {
   return m_impl->timeout_check();
}

◆ to_peer()

void Botan::TLS::Client::to_peer ( std::span< const uint8_t > data )

overridevirtual

Implements Botan::TLS::Channel.

Definition at line 148 of file tls_client.cpp.

                                                {
   m_impl->to_peer(data);
}

◆ update_traffic_keys()

void Botan::TLS::Client::update_traffic_keys ( bool request_peer_update = false )

overridevirtual

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

Parameters

request_peer_update if true, require a reciprocal key update

Implements Botan::TLS::Channel.

Definition at line 140 of file tls_client.cpp.

                                                         {
   m_impl->update_traffic_keys(request_peer_update);
}

Member Data Documentation

◆ IO_BUF_DEFAULT_SIZE

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

staticconstexprinherited

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 files:

src/lib/tls/tls_client.h
src/lib/tls/tls_client.cpp

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Client()

◆ ~Client()

Member Function Documentation

◆ application_protocol()

◆ close()

◆ external_psk_identity()

◆ from_peer()

◆ is_active()

◆ is_closed()

◆ is_closed_for_reading()

◆ is_closed_for_writing()

◆ is_handshake_complete()

◆ key_material_export()

◆ peer_cert_chain()

◆ peer_raw_public_key()

◆ received_data() [1/2]

◆ received_data() [2/2]

◆ renegotiate()

◆ secure_renegotiation_supported()

◆ send() [1/3]

◆ send() [2/3]

◆ send() [3/3]

◆ send_alert()

◆ send_fatal_alert()

◆ send_warning_alert()

◆ timeout_check()

◆ to_peer()

◆ update_traffic_keys()

Member Data Documentation

◆ IO_BUF_DEFAULT_SIZE