#include <tls_client_impl_13.h>

Inheritance diagram for Botan::TLS::Client_Impl_13:

Public Member Functions
std::string	application_protocol () const override
	Client_Impl_13 (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(), const std::vector< std::string > &next_protocols={})
void	close ()
bool	expects_downgrade () const
std::optional< std::string >	external_psk_identity () const override
std::unique_ptr< Downgrade_Information >	extract_downgrade_info ()
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_downgrading () const
bool	is_handshake_complete () const override
SymmetricKey	key_material_export (std::string_view label, std::string_view context, size_t length) const override
virtual bool	new_session_ticket_supported () const
std::vector< X509_Certificate >	peer_cert_chain () const override
std::shared_ptr< const Public_Key >	peer_raw_public_key () const override
void	renegotiate (bool) override
bool	secure_renegotiation_supported () const override
void	send_alert (const Alert &alert) override
void	send_fatal_alert (Alert::Type type)
virtual size_t	send_new_session_tickets (const size_t)
void	send_warning_alert (Alert::Type type)
bool	timeout_check () override
void	to_peer (std::span< const uint8_t > data) override
void	update_traffic_keys (bool request_peer_update=false) override

Protected Member Functions
AggregatedHandshakeMessages	aggregate_handshake_messages ()
AggregatedPostHandshakeMessages	aggregate_post_handshake_messages ()
Callbacks &	callbacks () const
Credentials_Manager &	credentials_manager ()
void	expect_downgrade (const Server_Information &server_info, const std::vector< std::string > &next_protocols)
void	opportunistically_update_traffic_keys ()
const Policy &	policy () const
void	preserve_client_hello (std::span< const uint8_t > msg)
void	preserve_peer_transcript (std::span< const uint8_t > input)
void	request_downgrade ()
void	request_downgrade_for_resumption (Session_with_Handle session)
RandomNumberGenerator &	rng ()
void	send_dummy_change_cipher_spec ()
template<typename... MsgTs>
std::vector< uint8_t >	send_handshake_message (const std::variant< MsgTs... > &message)
template<typename MsgT>
std::vector< uint8_t >	send_handshake_message (std::reference_wrapper< MsgT > message)
std::vector< uint8_t >	send_post_handshake_message (Post_Handshake_Message_13 message)
Session_Manager &	session_manager ()
void	set_io_buffer_size (size_t io_buf_sz)
void	set_record_size_limits (uint16_t outgoing_limit, uint16_t incoming_limit)
void	set_selected_certificate_type (Certificate_Type cert_type)

Protected Attributes
std::unique_ptr< Cipher_State >	m_cipher_state
std::unique_ptr< Downgrade_Information >	m_downgrade_info
const Connection_Side	m_side
Transcript_Hash_State	m_transcript_hash

Detailed Description

SSL/TLS Client 1.3 implementation

Definition at line 28 of file tls_client_impl_13.h.

Constructor & Destructor Documentation

◆ Client_Impl_13()

Botan::TLS::Client_Impl_13::Client_Impl_13	(	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(),
		const std::vector< std::string > &	next_protocols = {} )

explicit

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
next_protocols	specifies protocols to advertise with ALPN

Definition at line 26 of file tls_client_impl_13.cpp.

                                                                           :
      Channel_Impl_13(callbacks, session_manager, creds, rng, policy, false /* is_server */),
      m_info(std::move(info)),
      m_should_send_ccs(false) {
#if defined(BOTAN_HAS_TLS_12)
   if(policy->allow_tls12()) {
      expect_downgrade(m_info, next_protocols);
   }
#endif
 
   if(auto session = find_session_for_resumption()) {
      if(!session->session.version().is_pre_tls_13()) {
         m_resumed_session = std::move(session);
      } else if(expects_downgrade()) {
         // If we found a session that was created with TLS 1.2, we downgrade
         // the implementation right away, before even issuing a Client Hello.
         request_downgrade_for_resumption(std::move(session.value()));
         return;
      }
   }
 
   auto msg = send_handshake_message(m_handshake_state.sending(
      Client_Hello_13(*policy,
                      *callbacks,
                      *rng,
                      m_info.hostname(),
                      next_protocols,
                      m_resumed_session,
                      creds->find_preshared_keys(m_info.hostname(), Connection_Side::Client))));
 
   if(expects_downgrade()) {
      preserve_client_hello(msg);
   }
 
   // RFC 8446 Appendix D.4
   //    If not offering early data, the client sends a dummy change_cipher_spec
   //    record [...] immediately before its second flight. This may either be before
   //    its second ClientHello or before its encrypted handshake flight.
   //
   // TODO: don't schedule ccs here when early data is used
   if(policy->tls_13_middlebox_compatibility_mode()) {
      m_should_send_ccs = true;
   }
 
   m_transitions.set_expected_next({Handshake_Type::ServerHello, Handshake_Type::HelloRetryRequest});
}

Member Function Documentation

◆ aggregate_handshake_messages()

AggregatedHandshakeMessages Botan::TLS::Channel_Impl_13::aggregate_handshake_messages ( )

inlineprotectedinherited

Definition at line 258 of file tls_channel_impl_13.h.

                                                                 {
         return AggregatedHandshakeMessages(*this, m_handshake_layer, m_transcript_hash);
      }

References m_transcript_hash.

Referenced by send_handshake_message().

◆ aggregate_post_handshake_messages()

AggregatedPostHandshakeMessages Botan::TLS::Channel_Impl_13::aggregate_post_handshake_messages ( )

inlineprotectedinherited

Definition at line 262 of file tls_channel_impl_13.h.

                                                                          {
         return AggregatedPostHandshakeMessages(*this, m_handshake_layer);
      }

Referenced by Botan::TLS::Server_Impl_13::send_new_session_tickets(), and send_post_handshake_message().

◆ application_protocol()

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

overridevirtual

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

Implements Botan::TLS::Channel_Impl.

Definition at line 660 of file tls_client_impl_13.cpp.

                                                     {
   if(is_handshake_complete()) {
      const auto& eee = m_handshake_state.encrypted_extensions().extensions();
      if(eee.has<Application_Layer_Protocol_Notification>()) {
         return eee.get<Application_Layer_Protocol_Notification>()->single_protocol();
      }
   }
 
   return "";
}

References is_handshake_complete().

◆ callbacks()

Callbacks & Botan::TLS::Channel_Impl_13::callbacks ( ) const

inlineprotectedinherited

Definition at line 266 of file tls_channel_impl_13.h.

266{ return *m_callbacks; }

Referenced by Channel_Impl_13(), Botan::TLS::Client_Impl_13::Client_Impl_13(), from_peer(), Botan::TLS::Server_Impl_13::send_new_session_tickets(), and Botan::TLS::Server_Impl_13::Server_Impl_13().

◆ close()

void Botan::TLS::Channel_Impl::close ( )

inlineinherited

Send a close notification alert

Definition at line 76 of file tls_channel_impl.h.

76{ send_warning_alert(Alert::CloseNotify); }

Botan::TLS::Channel_Impl::send_warning_alert

void send_warning_alert(Alert::Type type)

Definition tls_channel_impl.h:66

References send_warning_alert().

◆ credentials_manager()

Credentials_Manager & Botan::TLS::Channel_Impl_13::credentials_manager ( )

inlineprotectedinherited

Definition at line 270 of file tls_channel_impl_13.h.

270{ return *m_credentials_manager; }

Referenced by Channel_Impl_13(), and Botan::TLS::Server_Impl_13::Server_Impl_13().

◆ expect_downgrade()

void Botan::TLS::Channel_Impl_13::expect_downgrade	(	const Server_Information &	server_info,
		const std::vector< std::string > &	next_protocols )

protectedinherited

Indicate that we have to expect a downgrade to TLS 1.2. In which case the current implementation (i.e. Client_Impl_13 or Server_Impl_13) will need to be replaced by their respective counter parts.

This will prepare an internal structure where any information required to downgrade can be preserved.

See also: Channel_Impl::Downgrade_Information

Definition at line 401 of file tls_channel_impl_13.cpp.

                                                                                   {
   Downgrade_Information di{
      {},
      {},
      {},
      server_info,
      next_protocols,
      Botan::TLS::Channel::IO_BUF_DEFAULT_SIZE,
      m_callbacks,
      m_session_manager,
      m_credentials_manager,
      m_rng,
      m_policy,
      false,  // received_tls_13_error_alert
      false   // will_downgrade
   };
   m_downgrade_info = std::make_unique<Downgrade_Information>(std::move(di));
}

References Botan::TLS::Channel::IO_BUF_DEFAULT_SIZE, and Botan::TLS::Channel_Impl::m_downgrade_info.

◆ expects_downgrade()

bool Botan::TLS::Channel_Impl::expects_downgrade ( ) const

inlineinherited

Definition at line 276 of file tls_channel_impl.h.

276{ return m_downgrade_info != nullptr; }

References m_downgrade_info.

Referenced by Botan::TLS::Client_Impl_13::Client_Impl_13(), and Botan::TLS::Channel_Impl_13::from_peer().

◆ external_psk_identity()

std::optional< std::string > Botan::TLS::Client_Impl_13::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_Impl.

Definition at line 646 of file tls_client_impl_13.cpp.

                                                                   {
   return m_psk_identity;
}

◆ extract_downgrade_info()

std::unique_ptr< Downgrade_Information > Botan::TLS::Channel_Impl::extract_downgrade_info ( )

inlineinherited

See also: Downgrade_Information

Definition at line 274 of file tls_channel_impl.h.

274{ return std::exchange(m_downgrade_info, {}); }

References m_downgrade_info.

◆ from_peer()

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

overridevirtualinherited

Inject TLS traffic received from counterparty

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

Implements Botan::TLS::Channel_Impl.

Definition at line 66 of file tls_channel_impl_13.cpp.

                                                             {
   BOTAN_STATE_CHECK(!is_downgrading());
 
   // RFC 8446 6.1
   //    Any data received after a closure alert has been received MUST be ignored.
   if(!m_can_read) {
      return 0;
   }
 
   try {
      if(expects_downgrade()) {
         preserve_peer_transcript(data);
      }
 
      m_record_layer.copy_data(data);
 
      while(true) {
         // RFC 8446 6.1
         //    Any data received after a closure alert has been received MUST be ignored.
         //
         // ... this data might already be in the record layer's read buffer.
         if(!m_can_read) {
            return 0;
         }
 
         auto result = m_record_layer.next_record(m_cipher_state.get());
 
         if(std::holds_alternative<BytesNeeded>(result)) {
            return std::get<BytesNeeded>(result);
         }
 
         const auto& record = std::get<Record>(result);
 
         // RFC 8446 5.1
         //   Handshake messages MUST NOT be interleaved with other record types.
         if(record.type != Record_Type::Handshake && m_handshake_layer.has_pending_data()) {
            throw Unexpected_Message("Expected remainder of a handshake message");
         }
 
         if(record.type == Record_Type::Handshake) {
            m_handshake_layer.copy_data(record.fragment);
 
            if(!is_handshake_complete()) {
               while(auto handshake_msg = m_handshake_layer.next_message(policy(), m_transcript_hash)) {
                  // RFC 8446 5.1
                  //    Handshake messages MUST NOT span key changes.  Implementations
                  //    MUST verify that all messages immediately preceding a key change
                  //    align with a record boundary; if not, then they MUST terminate the
                  //    connection with an "unexpected_message" alert.  Because the
                  //    ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate
                  //    messages can immediately precede a key change, implementations
                  //    MUST send these messages in alignment with a record boundary.
                  //
                  // Note: Hello_Retry_Request was added to the list below although it cannot immediately precede a key change.
                  //       However, there cannot be any further sensible messages in the record after HRR.
                  //
                  // Note: Server_Hello_12 was deliberately not included in the check below because in TLS 1.2 Server Hello and
                  //       other handshake messages can be legally coalesced in a single record.
                  //
                  if(holds_any_of<Client_Hello_12_Shim,
                                  Client_Hello_13 /*, EndOfEarlyData,*/,
                                  Server_Hello_13,
                                  Hello_Retry_Request,
                                  Finished_13>(handshake_msg.value()) &&
                     m_handshake_layer.has_pending_data()) {
                     throw Unexpected_Message("Unexpected additional handshake message data found in record");
                  }
 
                  process_handshake_msg(std::move(handshake_msg.value()));
 
                  if(is_downgrading()) {
                     // Downgrade to TLS 1.2 was detected. Stop everything we do and await being replaced by a 1.2 implementation.
                     return 0;
                  } else if(m_downgrade_info != nullptr) {
                     // We received a TLS 1.3 error alert that could have been a TLS 1.2 warning alert.
                     // Now that we know that we are talking to a TLS 1.3 server, shut down.
                     if(m_downgrade_info->received_tls_13_error_alert) {
                        shutdown();
                     }
 
                     // Downgrade can only be indicated in the first received peer message. This was not the case.
                     m_downgrade_info.reset();
                  }
 
                  // After the initial handshake message is received, the record
                  // layer must be more restrictive.
                  // See RFC 8446 5.1 regarding "legacy_record_version"
                  if(!m_first_message_received) {
                     m_record_layer.disable_receiving_compat_mode();
                     m_first_message_received = true;
                  }
               }
            } else {
               while(auto handshake_msg = m_handshake_layer.next_post_handshake_message(policy())) {
                  process_post_handshake_msg(std::move(handshake_msg.value()));
               }
            }
         } else if(record.type == Record_Type::ChangeCipherSpec) {
            process_dummy_change_cipher_spec();
         } else if(record.type == Record_Type::ApplicationData) {
            BOTAN_ASSERT(record.seq_no.has_value(), "decrypted application traffic had a sequence number");
            callbacks().tls_record_received(record.seq_no.value(), record.fragment);
         } else if(record.type == Record_Type::Alert) {
            process_alert(record.fragment);
         } else {
            throw Unexpected_Message("Unexpected record type " + std::to_string(static_cast<size_t>(record.type)) +
                                     " from counterparty");
         }
      }
   } catch(TLS_Exception& e) {
      send_fatal_alert(e.type());
      throw;
   } catch(Invalid_Authentication_Tag&) {
      // RFC 8446 5.2
      //    If the decryption fails, the receiver MUST terminate the connection
      //    with a "bad_record_mac" alert.
      send_fatal_alert(Alert::BadRecordMac);
      throw;
   } catch(Decoding_Error&) {
      send_fatal_alert(Alert::DecodeError);
      throw;
   } catch(...) {
      send_fatal_alert(Alert::InternalError);
      throw;
   }
}

References Botan::TLS::Alert, Botan::TLS::ApplicationData, BOTAN_ASSERT, BOTAN_STATE_CHECK, callbacks(), Botan::TLS::ChangeCipherSpec, Botan::TLS::Channel_Impl::expects_downgrade(), Botan::TLS::Handshake, Botan::holds_any_of(), Botan::TLS::Channel_Impl::is_downgrading(), Botan::TLS::Channel_Impl::is_handshake_complete(), m_cipher_state, Botan::TLS::Channel_Impl::m_downgrade_info, m_transcript_hash, policy(), Botan::TLS::Channel_Impl::preserve_peer_transcript(), process_dummy_change_cipher_spec(), process_handshake_msg(), process_post_handshake_msg(), Botan::TLS::Channel_Impl::send_fatal_alert(), Botan::TLS::Callbacks::tls_record_received(), and Botan::TLS::TLS_Exception::type().

◆ is_active()

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

overridevirtualinherited

Returns: true iff the connection is active for sending application data

Note that the connection is active until the application has called close(), even if a CloseNotify has been received from the peer.

Implements Botan::TLS::Channel_Impl.

Definition at line 303 of file tls_channel_impl_13.cpp.

                                      {
   return m_cipher_state != nullptr && m_cipher_state->can_encrypt_application_traffic()  // handshake done
          && m_can_write;                                                                 // close() hasn't been called
}

References m_cipher_state.

Referenced by to_peer().

◆ is_closed()

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

inlineoverridevirtualinherited

Returns: true iff the connection has been closed, i.e. CloseNotify has been received from the peer.

Implements Botan::TLS::Channel_Impl.

Definition at line 169 of file tls_channel_impl_13.h.

169{ return is_closed_for_reading() && is_closed_for_writing(); }

Botan::TLS::Channel_Impl_13::is_closed_for_reading

bool is_closed_for_reading() const override

Definition tls_channel_impl_13.h:171

Botan::TLS::Channel_Impl_13::is_closed_for_writing

bool is_closed_for_writing() const override

Definition tls_channel_impl_13.h:173

References is_closed_for_reading(), and is_closed_for_writing().

◆ is_closed_for_reading()

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

inlineoverridevirtualinherited

Returns: true iff the connection is active for sending application data

Implements Botan::TLS::Channel_Impl.

Definition at line 171 of file tls_channel_impl_13.h.

171{ return !m_can_read; }

Referenced by is_closed().

◆ is_closed_for_writing()

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

inlineoverridevirtualinherited

Returns: true iff the connection has been definitely closed

Implements Botan::TLS::Channel_Impl.

Definition at line 173 of file tls_channel_impl_13.h.

173{ return !m_can_write; }

Referenced by is_closed().

◆ is_downgrading()

bool Botan::TLS::Channel_Impl::is_downgrading ( ) const

inlineinherited

Indicates whether a downgrade to TLS 1.2 or lower is in progress

See also: Downgrade_Information

Definition at line 269 of file tls_channel_impl.h.

269{ return m_downgrade_info && m_downgrade_info->will_downgrade; }

References m_downgrade_info.

Referenced by Botan::TLS::Channel_Impl_13::from_peer(), Botan::TLS::Channel_Impl_13::key_material_export(), and Botan::TLS::Channel_Impl_13::update_traffic_keys().

◆ is_handshake_complete()

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

overridevirtual

Returns: true if the TLS handshake finished successfully

Implements Botan::TLS::Channel_Impl.

Definition at line 118 of file tls_client_impl_13.cpp.

                                                 {
   return m_handshake_state.handshake_finished();
}

Referenced by application_protocol().

◆ key_material_export()

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

overridevirtualinherited

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_Impl.

Definition at line 308 of file tls_channel_impl_13.cpp.

                                                                       {
   BOTAN_STATE_CHECK(!is_downgrading());
   BOTAN_STATE_CHECK(m_cipher_state != nullptr && m_cipher_state->can_export_keys());
   return SymmetricKey(m_cipher_state->export_key(label, context, length));
}

References BOTAN_STATE_CHECK, Botan::TLS::Channel_Impl::is_downgrading(), and m_cipher_state.

◆ new_session_ticket_supported()

virtual bool Botan::TLS::Channel_Impl::new_session_ticket_supported ( ) const

inlinevirtualinherited

Returns: true if this channel can issue TLS 1.3 style session tickets.

Reimplemented in Botan::TLS::Server_Impl_13.

Definition at line 140 of file tls_channel_impl.h.

140{ return false; }

◆ opportunistically_update_traffic_keys()

void Botan::TLS::Channel_Impl_13::opportunistically_update_traffic_keys ( )

inlineprotectedinherited

Schedule a traffic key update to opportunistically happen before the channel sends application data the next time. Such a key update will never request a reciprocal key update from the peer.

Definition at line 240 of file tls_channel_impl_13.h.

240{ m_opportunistic_key_update = true; }

Referenced by handle().

◆ peer_cert_chain()

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

overridevirtual

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

Implements Botan::TLS::Channel_Impl.

Definition at line 621 of file tls_client_impl_13.cpp.

                                                                  {
   if(m_handshake_state.has_server_certificate_msg() &&
      m_handshake_state.server_certificate().has_certificate_chain()) {
      return m_handshake_state.server_certificate().cert_chain();
   }
 
   if(m_resumed_session.has_value()) {
      return m_resumed_session->session.peer_certs();
   }
 
   return {};
}

◆ peer_raw_public_key()

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

overridevirtual

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

Implements Botan::TLS::Channel_Impl.

Definition at line 634 of file tls_client_impl_13.cpp.

                                                                          {
   if(m_handshake_state.has_server_certificate_msg() && m_handshake_state.server_certificate().is_raw_public_key()) {
      return m_handshake_state.server_certificate().public_key();
   }
 
   if(m_resumed_session.has_value()) {
      return m_resumed_session->session.peer_raw_public_key();
   }
 
   return nullptr;
}

◆ policy()

const Policy & Botan::TLS::Channel_Impl_13::policy ( ) const

inlineprotectedinherited

Definition at line 274 of file tls_channel_impl_13.h.

274{ return *m_policy; }

Referenced by Channel_Impl_13(), Botan::TLS::Client_Impl_13::Client_Impl_13(), from_peer(), Botan::TLS::Server_Impl_13::send_new_session_tickets(), and Botan::TLS::Server_Impl_13::Server_Impl_13().

◆ preserve_client_hello()

void Botan::TLS::Channel_Impl::preserve_client_hello ( std::span< const uint8_t > msg )

inlineprotectedinherited

Definition at line 229 of file tls_channel_impl.h.

                                                             {
         BOTAN_STATE_CHECK(m_downgrade_info);
         m_downgrade_info->client_hello_message.assign(msg.begin(), msg.end());
      }

References BOTAN_STATE_CHECK, and m_downgrade_info.

Referenced by Botan::TLS::Client_Impl_13::Client_Impl_13().

◆ preserve_peer_transcript()

void Botan::TLS::Channel_Impl::preserve_peer_transcript ( std::span< const uint8_t > input )

inlineprotectedinherited

Definition at line 224 of file tls_channel_impl.h.

                                                                  {
         BOTAN_STATE_CHECK(m_downgrade_info);
         m_downgrade_info->peer_transcript.insert(m_downgrade_info->peer_transcript.end(), input.begin(), input.end());
      }

References BOTAN_STATE_CHECK, and m_downgrade_info.

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

◆ renegotiate()

void Botan::TLS::Channel_Impl_13::renegotiate ( bool )

inlineoverridevirtualinherited

Attempt to renegotiate the session

Implements Botan::TLS::Channel_Impl.

Definition at line 187 of file tls_channel_impl_13.h.

                                        {
         throw Invalid_Argument("renegotiation is not allowed in TLS 1.3");
      }

◆ request_downgrade()

void Botan::TLS::Channel_Impl::request_downgrade ( )

inlineprotectedinherited

Implementations use this to signal that the peer indicated a protocol version downgrade. After calling request_downgrade() no further state changes must be performed by the implementation. Particularly, no further handshake messages must be emitted. Instead, they must yield control flow back to the underlying Channel implementation to perform the protocol version downgrade.

Definition at line 250 of file tls_channel_impl.h.

                               {
         BOTAN_STATE_CHECK(m_downgrade_info && !m_downgrade_info->will_downgrade);
         m_downgrade_info->will_downgrade = true;
      }

References BOTAN_STATE_CHECK, and m_downgrade_info.

Referenced by request_downgrade_for_resumption().

◆ request_downgrade_for_resumption()

void Botan::TLS::Channel_Impl::request_downgrade_for_resumption ( Session_with_Handle session )

inlineprotectedinherited

Definition at line 255 of file tls_channel_impl.h.

                                                                         {
         BOTAN_STATE_CHECK(m_downgrade_info && m_downgrade_info->client_hello_message.empty() &&
                           m_downgrade_info->peer_transcript.empty() && !m_downgrade_info->tls12_session.has_value());
         BOTAN_ASSERT_NOMSG(session.session.version().is_pre_tls_13());
         m_downgrade_info->tls12_session = std::move(session);
         request_downgrade();
      }

References BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, Botan::TLS::Protocol_Version::is_pre_tls_13(), m_downgrade_info, request_downgrade(), Botan::TLS::Session_with_Handle::session, and Botan::TLS::Session_Base::version().

Referenced by Botan::TLS::Client_Impl_13::Client_Impl_13().

◆ rng()

RandomNumberGenerator & Botan::TLS::Channel_Impl_13::rng ( )

inlineprotectedinherited

Definition at line 272 of file tls_channel_impl_13.h.

272{ return *m_rng; }

Referenced by Channel_Impl_13(), Botan::TLS::Client_Impl_13::Client_Impl_13(), Botan::TLS::Server_Impl_13::send_new_session_tickets(), and Botan::TLS::Server_Impl_13::Server_Impl_13().

◆ secure_renegotiation_supported()

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

inlineoverridevirtualinherited

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

Implements Botan::TLS::Channel_Impl.

Definition at line 203 of file tls_channel_impl_13.h.

                                                           {
         // Secure renegotiation is not supported in TLS 1.3, though BoGo
         // tests expect us to claim that it is available.
         return true;
      }

◆ send_alert()

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

overridevirtualinherited

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_Impl.

Definition at line 278 of file tls_channel_impl_13.cpp.

                                                   {
   if(alert.is_valid() && m_can_write) {
      try {
         send_record(Record_Type::Alert, alert.serialize());
      } catch(...) { /* swallow it */
      }
   }
 
   // Note: In TLS 1.3 sending a CloseNotify must not immediately lead to closing the reading end.
   // RFC 8446 6.1
   //    Each party MUST send a "close_notify" alert before closing its write
   //    side of the connection, unless it has already sent some error alert.
   //    This does not have any effect on its read side of the connection.
   if(is_close_notify_alert(alert) && m_can_write) {
      m_can_write = false;
      if(m_cipher_state) {
         m_cipher_state->clear_write_keys();
      }
   }
 
   if(is_error_alert(alert)) {
      shutdown();
   }
}

References Botan::TLS::Alert, Botan::TLS::Alert::is_valid(), m_cipher_state, and Botan::TLS::Alert::serialize().

◆ send_dummy_change_cipher_spec()

void Botan::TLS::Channel_Impl_13::send_dummy_change_cipher_spec ( )

protectedinherited

Definition at line 247 of file tls_channel_impl_13.cpp.

                                                    {
   // RFC 8446 5.
   //    The change_cipher_spec record is used only for compatibility purposes
   //    (see Appendix D.4).
   //
   // The only allowed CCS message content is 0x01, all other CCS records MUST
   // be rejected by TLS 1.3 implementations.
   send_record(Record_Type::ChangeCipherSpec, {0x01});
}

References Botan::TLS::ChangeCipherSpec.

◆ send_fatal_alert()

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

inlineinherited

Send a fatal alert

Definition at line 71 of file tls_channel_impl.h.

71{ send_alert(Alert(type, true)); }

Botan::TLS::Channel_Impl::send_alert

virtual void send_alert(const Alert &alert)=0

References Botan::TLS::Alert, and send_alert().

Referenced by Botan::TLS::Channel_Impl_12::from_peer(), and Botan::TLS::Channel_Impl_13::from_peer().

◆ send_handshake_message() [1/2]

template<typename... MsgTs>

std::vector< uint8_t > Botan::TLS::Channel_Impl_13::send_handshake_message ( const std::variant< MsgTs... > & message )

inlineprotectedinherited

Definition at line 243 of file tls_channel_impl_13.h.

                                                                                     {
         return aggregate_handshake_messages().add(generalize_to<Handshake_Message_13_Ref>(message)).send();
      }

References Botan::TLS::Channel_Impl_13::AggregatedHandshakeMessages::add(), aggregate_handshake_messages(), Botan::generalize_to(), and Botan::TLS::Channel_Impl_13::AggregatedMessages::send().

Referenced by Botan::TLS::Client_Impl_13::Client_Impl_13(), and send_handshake_message().

◆ send_handshake_message() [2/2]

template<typename MsgT>

std::vector< uint8_t > Botan::TLS::Channel_Impl_13::send_handshake_message ( std::reference_wrapper< MsgT > message )

inlineprotectedinherited

Definition at line 248 of file tls_channel_impl_13.h.

                                                                                    {
         return send_handshake_message(generalize_to<Handshake_Message_13_Ref>(message));
      }

References Botan::generalize_to(), and send_handshake_message().

◆ send_new_session_tickets()

virtual size_t Botan::TLS::Channel_Impl::send_new_session_tickets ( const size_t )

inlinevirtualinherited

Send tickets new session tickets to the peer. This is only supported on TLS 1.3 servers.

If the server's Session_Manager does not accept the generated Session objects, the server implementation won't be able to send new tickets. Additionally, anything but TLS 1.3 servers will return 0 (because they don't support sending such session tickets).

Returns: the number of session tickets successfully sent to the client

Reimplemented in Botan::TLS::Server_Impl_13.

Definition at line 153 of file tls_channel_impl.h.

153{ return 0; }

◆ send_post_handshake_message()

std::vector< uint8_t > Botan::TLS::Channel_Impl_13::send_post_handshake_message ( Post_Handshake_Message_13 message )

inlineprotectedinherited

Definition at line 252 of file tls_channel_impl_13.h.

                                                                                        {
         return aggregate_post_handshake_messages().add(std::move(message)).send();
      }

References Botan::TLS::Channel_Impl_13::AggregatedPostHandshakeMessages::add(), aggregate_post_handshake_messages(), and Botan::TLS::Channel_Impl_13::AggregatedMessages::send().

Referenced by update_traffic_keys().

◆ send_warning_alert()

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

inlineinherited

Send a warning alert

Definition at line 66 of file tls_channel_impl.h.

66{ send_alert(Alert(type, false)); }

References Botan::TLS::Alert, and send_alert().

Referenced by close().

◆ session_manager()

Session_Manager & Botan::TLS::Channel_Impl_13::session_manager ( )

inlineprotectedinherited

Definition at line 268 of file tls_channel_impl_13.h.

268{ return *m_session_manager; }

Referenced by Channel_Impl_13(), Botan::TLS::Client_Impl_13::Client_Impl_13(), Botan::TLS::Server_Impl_13::send_new_session_tickets(), and Botan::TLS::Server_Impl_13::Server_Impl_13().

◆ set_io_buffer_size()

void Botan::TLS::Channel_Impl::set_io_buffer_size ( size_t io_buf_sz )

inlineprotectedinherited

Definition at line 237 of file tls_channel_impl.h.

                                                {
         BOTAN_STATE_CHECK(m_downgrade_info);
         m_downgrade_info->io_buffer_size = io_buf_sz;
      }

References BOTAN_STATE_CHECK, and m_downgrade_info.

◆ set_record_size_limits()

void Botan::TLS::Channel_Impl_13::set_record_size_limits	(	uint16_t	outgoing_limit,
		uint16_t	incoming_limit )

protectedinherited

Set the record size limits as negotiated by the "record_size_limit" extension (RFC 8449).

Parameters

outgoing_limit	the maximal number of plaintext bytes to be sent in a protected record
incoming_limit	the maximal number of plaintext bytes to be accepted in a received protected record

Definition at line 421 of file tls_channel_impl_13.cpp.

                                                                                                         {
   m_record_layer.set_record_size_limits(outgoing_limit, incoming_limit);
}

◆ set_selected_certificate_type()

void Botan::TLS::Channel_Impl_13::set_selected_certificate_type ( Certificate_Type cert_type )

protectedinherited

Set the expected certificate type needed to parse Certificate messages in the handshake layer. See RFC 7250 and 8446 4.4.2 for further details.

Definition at line 425 of file tls_channel_impl_13.cpp.

                                                                                    {
   m_handshake_layer.set_selected_certificate_type(cert_type);
}

◆ timeout_check()

bool Botan::TLS::Channel_Impl_13::timeout_check ( )

inlineoverridevirtualinherited

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.

In the TLS 1.3 implementation, this always returns false.

Implements Botan::TLS::Channel_Impl.

Definition at line 217 of file tls_channel_impl_13.h.

217{ return false; }

◆ to_peer()

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

overridevirtualinherited

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

Implements Botan::TLS::Channel_Impl.

Definition at line 257 of file tls_channel_impl_13.cpp.

                                                         {
   if(!is_active()) {
      throw Invalid_State("Data cannot be sent on inactive TLS connection");
   }
 
   // RFC 8446 4.6.3
   //    If the request_update field [of a received KeyUpdate] is set to
   //    "update_requested", then the receiver MUST send a KeyUpdate of its own
   //    with request_update set to "update_not_requested" prior to sending its
   //    next Application Data record.
   //    This mechanism allows either side to force an update to the entire
   //    connection, but causes an implementation which receives multiple
   //    KeyUpdates while it is silent to respond with a single update.
   if(m_opportunistic_key_update) {
      update_traffic_keys(false /* update_requested */);
      m_opportunistic_key_update = false;
   }
 
   send_record(Record_Type::ApplicationData, {data.begin(), data.end()});
}

References Botan::TLS::ApplicationData, is_active(), and update_traffic_keys().

◆ update_traffic_keys()

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

overridevirtualinherited

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_Impl.

Definition at line 316 of file tls_channel_impl_13.cpp.

                                                                  {
   BOTAN_STATE_CHECK(!is_downgrading());
   BOTAN_STATE_CHECK(is_handshake_complete());
   BOTAN_ASSERT_NONNULL(m_cipher_state);
   send_post_handshake_message(Key_Update(request_peer_update));
   m_cipher_state->update_write_keys(*this);
}

References BOTAN_ASSERT_NONNULL, BOTAN_STATE_CHECK, Botan::TLS::Channel_Impl::is_downgrading(), Botan::TLS::Channel_Impl::is_handshake_complete(), m_cipher_state, and send_post_handshake_message().

Referenced by to_peer().

Member Data Documentation

◆ m_cipher_state

std::unique_ptr<Cipher_State> Botan::TLS::Channel_Impl_13::m_cipher_state

protectedinherited

Definition at line 290 of file tls_channel_impl_13.h.

Referenced by from_peer(), handle(), is_active(), key_material_export(), send_alert(), Botan::TLS::Server_Impl_13::send_new_session_tickets(), and update_traffic_keys().

◆ m_downgrade_info

std::unique_ptr<Downgrade_Information> Botan::TLS::Channel_Impl::m_downgrade_info

protectedinherited

Definition at line 222 of file tls_channel_impl.h.

Referenced by Botan::TLS::Channel_Impl_13::expect_downgrade(), expects_downgrade(), extract_downgrade_info(), Botan::TLS::Channel_Impl_13::from_peer(), is_downgrading(), preserve_client_hello(), preserve_peer_transcript(), request_downgrade(), request_downgrade_for_resumption(), and set_io_buffer_size().

◆ m_side

const Connection_Side Botan::TLS::Channel_Impl_13::m_side

protectedinherited

Definition at line 288 of file tls_channel_impl_13.h.

Referenced by Channel_Impl_13().

◆ m_transcript_hash

Transcript_Hash_State Botan::TLS::Channel_Impl_13::m_transcript_hash

protectedinherited

Definition at line 289 of file tls_channel_impl_13.h.

Referenced by aggregate_handshake_messages(), and from_peer().

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

src/lib/tls/tls13/tls_client_impl_13.h
src/lib/tls/tls13/tls_client_impl_13.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Client_Impl_13()

Member Function Documentation

◆ aggregate_handshake_messages()

◆ aggregate_post_handshake_messages()

◆ application_protocol()

◆ callbacks()

◆ close()

◆ credentials_manager()

◆ expect_downgrade()

◆ expects_downgrade()

◆ external_psk_identity()

◆ extract_downgrade_info()

◆ from_peer()

◆ is_active()

◆ is_closed()

◆ is_closed_for_reading()

◆ is_closed_for_writing()

◆ is_downgrading()

◆ is_handshake_complete()

◆ key_material_export()

◆ new_session_ticket_supported()

◆ opportunistically_update_traffic_keys()

◆ peer_cert_chain()

◆ peer_raw_public_key()

◆ policy()

◆ preserve_client_hello()

◆ preserve_peer_transcript()

◆ renegotiate()

◆ request_downgrade()

◆ request_downgrade_for_resumption()

◆ rng()

◆ secure_renegotiation_supported()

◆ send_alert()

◆ send_dummy_change_cipher_spec()

◆ send_fatal_alert()

◆ send_handshake_message() [1/2]

◆ send_handshake_message() [2/2]

◆ send_new_session_tickets()

◆ send_post_handshake_message()

◆ send_warning_alert()

◆ session_manager()

◆ set_io_buffer_size()

◆ set_record_size_limits()

◆ set_selected_certificate_type()

◆ timeout_check()

◆ to_peer()

◆ update_traffic_keys()

Member Data Documentation

◆ m_cipher_state

◆ m_downgrade_info

◆ m_side

◆ m_transcript_hash