Botan::TLS::Channel_Impl_13 Class Reference

#include <tls_channel_impl_13.h>

Inheritance diagram for Botan::TLS::Channel_Impl_13:

Classes
class	AggregatedHandshakeMessages
class	AggregatedMessages
class	AggregatedPostHandshakeMessages

Public Member Functions
virtual std::string	application_protocol () const =0
	Channel_Impl_13 (Channel_Impl_13 &&other)=delete
	Channel_Impl_13 (const Channel_Impl_13 &other)=delete
	Channel_Impl_13 (const std::shared_ptr< Callbacks > &callbacks, const std::shared_ptr< Session_Manager > &session_manager, const std::shared_ptr< Credentials_Manager > &credentials_manager, const std::shared_ptr< RandomNumberGenerator > &rng, const std::shared_ptr< const Policy > &policy, bool is_server)
void	close ()
bool	expects_downgrade () const
virtual std::optional< std::string >	external_psk_identity () const =0
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
virtual bool	is_handshake_complete () const =0
SymmetricKey	key_material_export (std::string_view label, std::string_view context, size_t length) const override
virtual bool	new_session_ticket_supported () const
Channel_Impl_13 &	operator= (Channel_Impl_13 &&other)=delete
Channel_Impl_13 &	operator= (const Channel_Impl_13 &other)=delete
virtual std::vector< X509_Certificate >	peer_cert_chain () const =0
virtual std::shared_ptr< const Public_Key >	peer_raw_public_key () const =0
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
	~Channel_Impl_13 () 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	handle (const Key_Update &key_update)
virtual void	maybe_log_secret (std::string_view label, std::span< const uint8_t > secret) const =0
void	opportunistically_update_traffic_keys ()
const Policy &	policy () const
virtual bool	prepend_ccs ()
void	preserve_client_hello (std::span< const uint8_t > msg)
void	preserve_peer_transcript (std::span< const uint8_t > input)
virtual void	process_dummy_change_cipher_spec ()=0
virtual void	process_handshake_msg (Handshake_Message_13 msg)=0
virtual void	process_post_handshake_msg (Post_Handshake_Message_13 msg)=0
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

Generic interface for TLS 1.3 endpoint

Definition at line 48 of file tls_channel_impl_13.h.

Constructor & Destructor Documentation

Channel_Impl_13() [1/3]

Botan::TLS::Channel_Impl_13::Channel_Impl_13 ( const std::shared_ptr< Callbacks > & callbacks, const std::shared_ptr< Session_Manager > & session_manager, const std::shared_ptr< Credentials_Manager > & credentials_manager, const std::shared_ptr< RandomNumberGenerator > & rng, const std::shared_ptr< const Policy > & policy, bool is_server )

explicit

Set up a new TLS 1.3 session

Parameters

callbacks	contains a set of callback function references required by the TLS endpoint.
session_manager	manages session state
credentials_manager	manages application/user credentials
rng	a random number generator
policy	specifies other connection policy information
is_server	whether this is a server session or not

Definition at line 38 of file tls_channel_impl_13.cpp.

                                                 :
      m_side(is_server ? Connection_Side::Server : Connection_Side::Client),
      m_callbacks(callbacks),
      m_session_manager(session_manager),
      m_credentials_manager(credentials_manager),
      m_rng(rng),
      m_policy(policy),
      m_record_layer(m_side),
      m_handshake_layer(m_side),
      m_can_read(true),
      m_can_write(true),
      m_opportunistic_key_update(false),
      m_first_message_sent(false),
      m_first_message_received(false) {
   BOTAN_ASSERT_NONNULL(m_callbacks);
   BOTAN_ASSERT_NONNULL(m_session_manager);
   BOTAN_ASSERT_NONNULL(m_credentials_manager);
   BOTAN_ASSERT_NONNULL(m_rng);
   BOTAN_ASSERT_NONNULL(m_policy);
}

References BOTAN_ASSERT_NONNULL, callbacks(), Botan::TLS::Channel_Impl::Client, credentials_manager(), m_side, policy(), rng(), Botan::TLS::Channel_Impl::Server, and session_manager().

Referenced by Botan::TLS::Channel_Impl_13::AggregatedHandshakeMessages::AggregatedHandshakeMessages(), Botan::TLS::Channel_Impl_13::AggregatedMessages::AggregatedMessages(), Channel_Impl_13(), Channel_Impl_13(), Botan::TLS::Client_Impl_13::Client_Impl_13(), operator=(), operator=(), and Botan::TLS::Server_Impl_13::Server_Impl_13().

Channel_Impl_13() [2/3]

Botan::TLS::Channel_Impl_13::Channel_Impl_13 ( const Channel_Impl_13 & other )

delete

References Channel_Impl_13().

Channel_Impl_13() [3/3]

Botan::TLS::Channel_Impl_13::Channel_Impl_13 ( Channel_Impl_13 && other )

delete

References Channel_Impl_13().

~Channel_Impl_13()

Botan::TLS::Channel_Impl_13::~Channel_Impl_13 ( )

overridedefault

Member Function Documentation

aggregate_handshake_messages()

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

inlineprotected

Definition at line 257 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 ( )

inlineprotected

Definition at line 261 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()

virtual std::string Botan::TLS::Channel_Impl::application_protocol ( ) const

pure virtualinherited

Return the protocol notification set for this connection, if any (ALPN). This value is not tied to the session and a later renegotiation of the same session can choose a new protocol.

Implemented in Botan::TLS::Client_Impl_12, Botan::TLS::Client_Impl_13, and Botan::TLS::Server_Impl_13.

callbacks()

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

inlineprotected

Definition at line 265 of file tls_channel_impl_13.h.

{ 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 86 of file tls_channel_impl.h.

{ send_warning_alert(Alert::CloseNotify); }

References send_warning_alert().

credentials_manager()

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

inlineprotected

Definition at line 269 of file tls_channel_impl_13.h.

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

protected

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 400 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 286 of file tls_channel_impl.h.

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

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

pure virtualinherited

Returns

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

Implemented in Botan::TLS::Channel_Impl_12, Botan::TLS::Client_Impl_13, and Botan::TLS::Server_Impl_13.

extract_downgrade_info()

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

inlineinherited

See also

Downgrade_Information

Definition at line 284 of file tls_channel_impl.h.

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

overridevirtual

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

handle()

void Botan::TLS::Channel_Impl_13::handle ( const Key_Update & key_update )

protected

Definition at line 193 of file tls_channel_impl_13.cpp.

                                                         {
   // make sure Key_Update appears only at the end of a record; see description above
   if(m_handshake_layer.has_pending_data()) {
      throw Unexpected_Message("Unexpected additional post-handshake message data found in record");
   }
 
   m_cipher_state->update_read_keys(*this);
 
   // TODO: introduce some kind of rate limit of key updates, otherwise we
   //       might be forced into an endless loop of key updates.
 
   // RFC 8446 4.6.3
   //    If the request_update field 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.
   if(key_update.expects_reciprocation()) {
      // RFC 8446 4.6.3
      //    This mechanism allows either side to force an update to the
      //    multiple KeyUpdates while it is silent to respond with a single
      //    update.
      opportunistically_update_traffic_keys();
   }
}

References Botan::TLS::Key_Update::expects_reciprocation(), m_cipher_state, and opportunistically_update_traffic_keys().

is_active()

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

overridevirtual

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 302 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

inlineoverridevirtual

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 168 of file tls_channel_impl_13.h.

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

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

inlineoverridevirtual

Returns

true iff the connection is active for sending application data

Implements Botan::TLS::Channel_Impl.

Definition at line 170 of file tls_channel_impl_13.h.

{ return !m_can_read; }

Referenced by is_closed().

is_closed_for_writing()

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

inlineoverridevirtual

Returns

true iff the connection has been definitely closed

Implements Botan::TLS::Channel_Impl.

Definition at line 172 of file tls_channel_impl_13.h.

{ 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 279 of file tls_channel_impl.h.

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

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

pure virtualinherited

Returns

true iff the TLS handshake has finished successfully

Implemented in Botan::TLS::Channel_Impl_12, Botan::TLS::Client_Impl_13, and Botan::TLS::Server_Impl_13.

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

key_material_export()

SymmetricKey Botan::TLS::Channel_Impl_13::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_Impl.

Definition at line 307 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.

maybe_log_secret()

virtual void Botan::TLS::Secret_Logger::maybe_log_secret ( std::string_view label, std::span< const uint8_t > secret ) const

protectedpure virtualinherited

Used exclusively in the Cipher_State to pass secret data to a user-provided Callbacks::tls_ssl_key_log_data() iff Policy::allow_ssl_key_log_file() returns true.

Referenced by Botan::TLS::Cipher_State::advance_with_client_hello(), Botan::TLS::Cipher_State::advance_with_server_finished(), Botan::TLS::Cipher_State::advance_with_server_hello(), Botan::TLS::Cipher_State::update_read_keys(), and Botan::TLS::Cipher_State::update_write_keys().

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 150 of file tls_channel_impl.h.

{ return false; }

operator=() [1/2]

Channel_Impl_13 & Botan::TLS::Channel_Impl_13::operator= ( Channel_Impl_13 && other )

delete

References Channel_Impl_13().

operator=() [2/2]

Channel_Impl_13 & Botan::TLS::Channel_Impl_13::operator= ( const Channel_Impl_13 & other )

delete

References Channel_Impl_13().

opportunistically_update_traffic_keys()

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

inlineprotected

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 239 of file tls_channel_impl_13.h.

{ m_opportunistic_key_update = true; }

Referenced by handle().

peer_cert_chain()

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

pure virtualinherited

Returns

certificate chain of the peer (may be empty)

Implemented in Botan::TLS::Channel_Impl_12, Botan::TLS::Client_Impl_13, and Botan::TLS::Server_Impl_13.

peer_raw_public_key()

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

pure virtualinherited

Returns

raw public key of the peer (may be nullptr)

Implemented in Botan::TLS::Channel_Impl_12, Botan::TLS::Client_Impl_13, and Botan::TLS::Server_Impl_13.

policy()

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

inlineprotected

Definition at line 273 of file tls_channel_impl_13.h.

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

prepend_ccs()

virtual bool Botan::TLS::Channel_Impl_13::prepend_ccs ( )

inlineprotectedvirtual

Returns

whether a change cipher spec record should be prepended now

This method can be used by subclasses to indicate that send_record should prepend a CCS before the actual record. This is useful for middlebox compatibility mode. See RFC 8446 D.4.

Definition at line 230 of file tls_channel_impl_13.h.

{ return false; }

preserve_client_hello()

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

inlineprotectedinherited

Definition at line 239 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 234 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().

process_dummy_change_cipher_spec()

virtual void Botan::TLS::Channel_Impl_13::process_dummy_change_cipher_spec ( )

protectedpure virtual

Referenced by from_peer().

process_handshake_msg()

virtual void Botan::TLS::Channel_Impl_13::process_handshake_msg ( Handshake_Message_13 msg )

protectedpure virtual

Referenced by from_peer().

process_post_handshake_msg()

virtual void Botan::TLS::Channel_Impl_13::process_post_handshake_msg ( Post_Handshake_Message_13 msg )

protectedpure virtual

Referenced by from_peer().

renegotiate()

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

inlineoverridevirtual

Attempt to renegotiate the session

Implements Botan::TLS::Channel_Impl.

Definition at line 186 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 260 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 265 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 ( )

inlineprotected

Definition at line 271 of file tls_channel_impl_13.h.

{ 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

inlineoverridevirtual

Returns

true iff the counterparty supports the secure renegotiation extensions.

Implements Botan::TLS::Channel_Impl.

Definition at line 202 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 )

overridevirtual

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

protected

Definition at line 246 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 81 of file tls_channel_impl.h.

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

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 )

inlineprotected

Definition at line 242 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 )

inlineprotected

Definition at line 247 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 163 of file tls_channel_impl.h.

{ return 0; }

send_post_handshake_message()

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

inlineprotected

Definition at line 251 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 76 of file tls_channel_impl.h.

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

inlineprotected

Definition at line 267 of file tls_channel_impl_13.h.

{ 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 247 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 )

protected

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

protected

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

inlineoverridevirtual

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 216 of file tls_channel_impl_13.h.

{ return false; }

to_peer()

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

overridevirtual

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

Implements Botan::TLS::Channel_Impl.

Definition at line 256 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 )

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

Definition at line 315 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

protected

Definition at line 289 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 232 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

protected

Definition at line 287 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

protected

Definition at line 288 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_channel_impl_13.h
• src/lib/tls/tls13/tls_channel_impl_13.cpp