Botan::TLS::Client_Impl_12 Class Reference

#include <tls_client_impl_12.h>

Inheritance diagram for Botan::TLS::Client_Impl_12:

Public Member Functions
std::string	application_protocol () const override
	Client_Impl_12 (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(), bool datagram=false, const std::vector< std::string > &next_protocols={}, size_t reserved_io_buffer_size=TLS::Channel::IO_BUF_DEFAULT_SIZE)
void	close ()
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
virtual bool	new_session_ticket_supported () const
std::optional< std::chrono::milliseconds >	next_retransmission_timeout () const override
std::vector< X509_Certificate >	peer_cert_chain () const override
std::shared_ptr< const Public_Key >	peer_raw_public_key () const override
void	renegotiate (bool force_full_renegotiation=false) 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
void	activate_session ()
const std::optional< Active_Connection_State_12 > &	active_state () const
Callbacks &	callbacks () const
void	change_cipher_spec_reader (Connection_Side side)
void	change_cipher_spec_writer (Connection_Side side)
Handshake_State &	create_handshake_state (Protocol_Version version, bool epoch0_restart=false)
bool	expects_downgrade () const
void	inspect_handshake_message (const Handshake_Message &msg)
bool	is_downgrading () const
void	note_resumption_handle (std::optional< Session_Handle > handle)
const Policy &	policy () const
void	reset_active_association_state ()
RandomNumberGenerator &	rng ()
void	secure_renegotiation_check (const Client_Hello_12 *client_hello)
void	secure_renegotiation_check (const Server_Hello_12 *server_hello)
std::vector< uint8_t >	secure_renegotiation_data_for_client_hello () const
std::vector< uint8_t >	secure_renegotiation_data_for_server_hello () const
Session_Manager &	session_manager ()

Detailed Description

SSL/TLS Client 1.2 implementation

Definition at line 23 of file tls_client_impl_12.h.

Constructor & Destructor Documentation

Client_Impl_12()

Botan::TLS::Client_Impl_12::Client_Impl_12 ( 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(), bool datagram = false, const std::vector< std::string > & next_protocols = {}, size_t reserved_io_buffer_size = TLS::Channel::IO_BUF_DEFAULT_SIZE )

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
datagram	specifies whether to use TLS 1.2 or DTLS 1.2
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 103 of file tls_client_impl_12.cpp.

                                                 :
      Channel_Impl_12(callbacks, session_manager, rng, policy, false, datagram, io_buf_sz),
      m_creds(creds),
      m_info(std::move(info)) {
   BOTAN_ASSERT_NONNULL(m_creds);
   const auto version = datagram ? Protocol_Version::DTLS_V12 : Protocol_Version::TLS_V12;
   Handshake_State& state = create_handshake_state(version);
   send_client_hello(state, false, version, std::nullopt /* no a-priori session to resume */, next_protocols);
}

References BOTAN_ASSERT_NONNULL, Botan::TLS::Channel_Impl_12::callbacks(), Botan::TLS::Channel_Impl_12::Channel_Impl_12(), Botan::TLS::Channel_Impl_12::create_handshake_state(), Botan::TLS::Channel_Impl_12::policy(), Botan::TLS::Channel_Impl_12::rng(), and Botan::TLS::Channel_Impl_12::session_manager().

Member Function Documentation

activate_session()

void Botan::TLS::Channel_Impl_12::activate_session ( )

protectedinherited

Definition at line 484 of file tls_channel_impl_12.cpp.

                                       {
   BOTAN_ASSERT_NONNULL(m_pending_state);
 
   const auto& state = *m_pending_state;
 
   if(!state.version().is_datagram_protocol()) {
      // TLS is easy just remove all but the current state
      const uint16_t current_epoch = sequence_numbers().current_write_epoch();
 
      const auto not_current_epoch = [current_epoch](uint16_t epoch) { return (epoch != current_epoch); };
 
      map_remove_if(not_current_epoch, m_write_cipher_states);
      map_remove_if(not_current_epoch, m_read_cipher_states);
   }
 
   // RFC 6347 4.2.4: "the node that transmits the last flight (the server in an
   // ordinary handshake or the client in a resumed handshake) MUST respond to a
   // retransmit of the peer's last flight with a retransmit of the last
   // flight." Both endpoints retain handshake sequence state, but only that
   // node replays its outgoing flight.
   const bool sent_terminal_dtls_flight = m_is_datagram && (m_is_server == (state.server_hello_done() != nullptr));
 
   if(m_is_datagram) {
      m_active_state = Active_Connection_State_12(state, application_protocol(), m_pending_state->take_handshake_io());
      if(auto* dtls_io = m_active_state->dtls_handshake_io()) {
         // Retain receive sequence state on both endpoints to distinguish a
         // retransmission from an unexpected new handshake message. Only the
         // terminal-flight sender responds by replaying its final flight.
         dtls_io->finalize_handshake(sent_terminal_dtls_flight);
      }
   } else {
      m_active_state = Active_Connection_State_12(state, application_protocol());
   }
 
   clear_pending_handshake_state();
 
   callbacks().tls_session_activated();
}

References Botan::TLS::Channel_Impl::application_protocol(), BOTAN_ASSERT_NONNULL, callbacks(), Botan::map_remove_if(), and Botan::TLS::Callbacks::tls_session_activated().

active_state()

const std::optional< Active_Connection_State_12 > & Botan::TLS::Channel_Impl_12::active_state ( ) const

inlineprotectedinherited

Definition at line 154 of file tls_channel_impl_12.h.

{ return m_active_state; }

application_protocol()

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

inlineoverridevirtual

Returns

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

Implements Botan::TLS::Channel_Impl.

Definition at line 68 of file tls_client_impl_12.h.

{ return m_application_protocol; }

callbacks()

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

inlineprotectedinherited

Definition at line 186 of file tls_channel_impl_12.h.

{ return *m_callbacks; }

Referenced by activate_session(), change_cipher_spec_reader(), Channel_Impl_12(), Botan::TLS::Client_Impl_12::Client_Impl_12(), create_handshake_state(), key_material_export(), and Botan::TLS::Server_Impl_12::Server_Impl_12().

change_cipher_spec_reader()

void Botan::TLS::Channel_Impl_12::change_cipher_spec_reader ( Connection_Side side )

protectedinherited

Definition at line 401 of file tls_channel_impl_12.cpp.

                                                                    {
   const auto* pending = pending_state();
 
   BOTAN_ASSERT(pending && pending->server_hello(), "Have received server hello");
 
   if(pending->server_hello()->compression_method() != 0) {
      throw Internal_Error("Negotiated unknown compression algorithm");
   }
 
   sequence_numbers().new_read_cipher_state();
 
   const uint16_t epoch = sequence_numbers().current_read_epoch();
 
   BOTAN_ASSERT(!m_read_cipher_states.contains(epoch), "No read cipher state currently set for next epoch");
 
   // flip side as we are reading
   auto read_state = std::make_shared<Connection_Cipher_State>(
      pending->version(),
      (side == Connection_Side::Client) ? Connection_Side::Server : Connection_Side::Client,
      false,
      pending->ciphersuite(),
      pending->session_keys(),
      pending->server_hello()->supports_encrypt_then_mac());
 
   // The epoch we just left is retained only to absorb reordering, so start its
   // clock now (see read_cipher_state_epoch). Epoch 0 is the plaintext
   // placeholder and holds no keys, so the window does not apply to it.
   if(m_is_datagram && epoch > 1) {
      if(auto prev = m_read_cipher_states.find(static_cast<uint16_t>(epoch - 1)); prev != m_read_cipher_states.end()) {
         prev->second.retired_at = callbacks().tls_current_monotonic_clock_ms();
      }
   }
 
   m_read_cipher_states[epoch] = Retained_Read_Cipher_State{.state = read_state, .retired_at = std::nullopt};
   prune_old_cipher_states(m_read_cipher_states);
}

References BOTAN_ASSERT, callbacks(), Botan::TLS::Client, Botan::TLS::Server, and Botan::TLS::Callbacks::tls_current_monotonic_clock_ms().

change_cipher_spec_writer()

void Botan::TLS::Channel_Impl_12::change_cipher_spec_writer ( Connection_Side side )

protectedinherited

Definition at line 438 of file tls_channel_impl_12.cpp.

                                                                    {
   const auto* pending = pending_state();
 
   BOTAN_ASSERT(pending && pending->server_hello(), "Have received server hello");
 
   if(pending->server_hello()->compression_method() != 0) {
      throw Internal_Error("Negotiated unknown compression algorithm");
   }
 
   sequence_numbers().new_write_cipher_state();
 
   const uint16_t epoch = sequence_numbers().current_write_epoch();
 
   BOTAN_ASSERT(!m_write_cipher_states.contains(epoch), "No write cipher state currently set for next epoch");
 
   auto write_state = std::make_shared<Connection_Cipher_State>(pending->version(),
                                                                side,
                                                                true,
                                                                pending->ciphersuite(),
                                                                pending->session_keys(),
                                                                pending->server_hello()->supports_encrypt_then_mac());
 
   m_write_cipher_states[epoch] = write_state;
   prune_old_cipher_states(m_write_cipher_states);
}

References BOTAN_ASSERT.

close()

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

inlineinherited

Send a close notification alert

Definition at line 80 of file tls_channel_impl.h.

{ send_warning_alert(Alert::CloseNotify); }

References send_warning_alert().

create_handshake_state()

Handshake_State & Botan::TLS::Channel_Impl_12::create_handshake_state ( Protocol_Version version, bool epoch0_restart = false )

protectedinherited

Definition at line 240 of file tls_channel_impl_12.cpp.

                                                                                                      {
   if(pending_state() != nullptr) {
      throw Internal_Error("create_handshake_state called during handshake");
   }
 
   if(m_active_state.has_value()) {
      const Protocol_Version active_version = m_active_state->version();
 
      if(active_version.is_datagram_protocol() != version.is_datagram_protocol()) {
         throw TLS_Exception(Alert::ProtocolVersion,
                             "Active state using version " + active_version.to_string() + " cannot change to " +
                                version.to_string() + " in pending");
      }
   }
 
   if(!m_sequence_numbers) {
      if(version.is_datagram_protocol()) {
         m_sequence_numbers = std::make_unique<Datagram_Sequence_Numbers>();
      } else {
         m_sequence_numbers = std::make_unique<Stream_Sequence_Numbers>();
      }
   }
 
   // Read epochs at or below this one belong to the association already in place,
   // so application data under them stays deliverable while this handshake runs.
   // Anything above it is this handshake's own, unauthenticated until its
   // Finished. See the application-data gate in from_peer.
   m_epochs_before_latest_renegotiation = Epochs_Before_Latest_Renegotiation{sequence_numbers().current_read_epoch(),
                                                                             sequence_numbers().current_write_epoch()};
 
   // Floor for the pending handshake's reassembly: a delayed record from the
   // handshake arrives under a lower epoch and must be rejected. It would
   // otherwise take the sequence slot the real message needs.
   //
   // Zero on an epoch-zero restart, because there the peer legitimately
   // begins again at epoch zero and the floor would reject it. This is keyed
   // on the restart actually occurring, not on the policy allowing it: an
   // ordinary renegotiation needs the floor either way.
   const uint16_t initial_epoch = epoch0_restart ? 0 : m_epochs_before_latest_renegotiation->read_epoch;
 
   using namespace std::placeholders;
 
   std::unique_ptr<Handshake_IO> io;
   if(version.is_datagram_protocol()) {
      const uint16_t mtu = static_cast<uint16_t>(policy().dtls_default_mtu());
      const size_t initial_timeout_ms = policy().dtls_initial_timeout();
      const size_t max_timeout_ms = policy().dtls_maximum_timeout();
      const std::optional<size_t> max_retransmissions = policy().dtls_maximum_retransmissions();
 
      auto send_record_f = [this](uint16_t epoch, Record_Type record_type, const std::vector<uint8_t>& record) {
         send_record_under_epoch(epoch, record_type, record);
      };
      auto clock_f = [this]() { return callbacks().tls_current_monotonic_clock_ms(); };
      io = std::make_unique<Datagram_Handshake_IO>(send_record_f,
                                                   clock_f,
                                                   sequence_numbers(),
                                                   mtu,
                                                   initial_timeout_ms,
                                                   max_timeout_ms,
                                                   max_retransmissions,
                                                   policy().maximum_handshake_message_size(),
                                                   initial_epoch);
   } else {
      auto send_record_f = [this](Record_Type rec_type, const std::vector<uint8_t>& record) {
         send_record(rec_type, record);
      };
      io = std::make_unique<Stream_Handshake_IO>(send_record_f);
   }
 
   m_pending_state = new_handshake_state(std::move(io));
 
   if(m_active_state.has_value()) {
      m_pending_state->set_version(m_active_state->version());
   }
 
   return *m_pending_state;
}

References callbacks(), Botan::TLS::Policy::dtls_default_mtu(), Botan::TLS::Policy::dtls_initial_timeout(), Botan::TLS::Policy::dtls_maximum_retransmissions(), Botan::TLS::Policy::dtls_maximum_timeout(), Botan::TLS::Protocol_Version::is_datagram_protocol(), new_handshake_state(), policy(), Botan::TLS::Callbacks::tls_current_monotonic_clock_ms(), and Botan::TLS::Protocol_Version::to_string().

Referenced by Botan::TLS::Client_Impl_12::Client_Impl_12(), and renegotiate().

expects_downgrade()

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

inlineprotectedinherited

Definition at line 290 of file tls_channel_impl.h.

                                     {
#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
         return m_downgrade_info != nullptr;
#else
         return false;
#endif
      }

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::Channel_Impl_12::external_psk_identity ( ) const

overridevirtualinherited

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 230 of file tls_channel_impl_12.cpp.

                                                                    {
   if(m_active_state.has_value()) {
      return m_active_state->psk_identity();
   }
   if(const auto* state = pending_state()) {
      return state->psk_identity();
   }
   return std::nullopt;
}

from_peer()

size_t Botan::TLS::Channel_Impl_12::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 523 of file tls_channel_impl_12.cpp.

                                                             {
   const bool allow_epoch0_restart = m_is_datagram && m_is_server && policy().allow_dtls_epoch0_restart();
 
   const auto* input = data.data();
   auto input_size = data.size();
 
   try {
      while(input_size > 0) {
         // A fatal alert destroys the cipher states, so nothing further can even
         // be decrypted. Closure by close_notify is different: the responding
         // close_notify still has to be read, so those records keep flowing
         // through the loop and are filtered per record type below.
         if(m_had_fatal_alert) {
            return 0;
         }
 
         size_t consumed = 0;
 
         auto get_epoch = [this](uint16_t epoch) { return read_cipher_state_epoch(epoch); };
 
         const Record_Header record = read_record(m_is_datagram,
                                                  m_readbuf,
                                                  input,
                                                  input_size,
                                                  consumed,
                                                  m_record_buf,
                                                  m_sequence_numbers.get(),
                                                  get_epoch,
                                                  allow_epoch0_restart);
 
         const size_t needed = record.needed();
 
         BOTAN_ASSERT(consumed > 0, "Got to eat something");
 
         BOTAN_ASSERT(consumed <= input_size, "Record reader consumed sane amount");
 
         input += consumed;
         input_size -= consumed;
 
         BOTAN_ASSERT(input_size == 0 || needed == 0, "Got a full record or consumed all input");
 
         if(input_size == 0 && needed != 0) {
            return needed;  // need more data to complete record
         }
 
         // Ignore invalid records in DTLS
         if(m_is_datagram && record.type() == Record_Type::Invalid) {
            return 0;
         }
 
         const bool old_unprotected_record = m_is_datagram && record.epoch() == 0 && m_active_state.has_value() &&
                                             sequence_numbers().current_read_epoch() > 0;
 
         // Once encrypted traffic is expected, epoch-zero records are
         // unauthenticated. Only handshake records can be useful as part of a
         // retransmitted flight or an explicitly allowed association restart.
         if(old_unprotected_record && record.type() != Record_Type::Handshake &&
            record.type() != Record_Type::ChangeCipherSpec) {
            continue;
         }
 
         if(m_record_buf.size() > MAX_PLAINTEXT_SIZE) {
            if(old_unprotected_record) {
               continue;
            }
 
            throw TLS_Exception(Alert::RecordOverflow, "TLS plaintext record is larger than allowed maximum");
         }
 
         const bool epoch0_restart = allow_epoch0_restart && record.epoch() == 0 && m_active_state.has_value();
         BOTAN_ASSERT_IMPLICATION(epoch0_restart, allow_epoch0_restart, "Allowed state");
 
         const bool initial_record = epoch0_restart || (pending_state() == nullptr && !m_active_state.has_value());
         bool initial_handshake_message = false;
         if(record.type() == Record_Type::Handshake && !m_record_buf.empty()) {
            const Handshake_Type type = static_cast<Handshake_Type>(m_record_buf[0]);
            initial_handshake_message = (type == Handshake_Type::ClientHello);
         }
 
         if(record.type() != Record_Type::Alert && !old_unprotected_record) {
            if(initial_record) {
               // For initial records just check for basic sanity
               if(record.version().major_version() != 3 && record.version().major_version() != 0xFE) {
                  throw TLS_Exception(Alert::ProtocolVersion, "Received unexpected record version in initial record");
               }
            } else if(const auto* pending = pending_state()) {
               if(pending->server_hello() != nullptr && !initial_handshake_message &&
                  record.version() != pending->version()) {
                  throw TLS_Exception(Alert::ProtocolVersion, "Received unexpected record version");
               }
            } else if(m_active_state.has_value()) {
               if(record.version() != m_active_state->version() && !initial_handshake_message) {
                  throw TLS_Exception(Alert::ProtocolVersion, "Received unexpected record version");
               }
            }
         }
 
         // RFC 5246 7.2.1: "Any data received after a closure alert is ignored."
         // This is about a closure alert the peer sent us. A peer that keeps
         // talking after *our* close_notify is a different case, kept as an
         // error below; BoGo's Shutdown-Shim-ApplicationData requires it.
         if(m_peer_closed_connection && record.type() != Record_Type::Alert) {
            continue;
         }
 
         if(record.type() == Record_Type::Handshake || record.type() == Record_Type::ChangeCipherSpec) {
            if(m_has_been_closed) {
               throw TLS_Exception(Alert::UnexpectedMessage, "Received handshake data after connection closure");
            }
            process_handshake_ccs(m_record_buf, record.sequence(), record.type(), record.version(), epoch0_restart);
         } else if(record.type() == Record_Type::ApplicationData) {
            if(m_has_been_closed) {
               throw TLS_Exception(Alert::UnexpectedMessage, "Received application data after connection closure");
            }
            if(pending_state() != nullptr) {
               /*
               What matters is which epoch the record belongs to, not which role we
               are playing.
 
               RFC 6347 4.2.4: "Implementations MUST either discard or buffer all
               application data packets for the new epoch until they have received
               the Finished message for that epoch." Data under the epoch this
               handshake installed is not authenticated until its Finished, so it
               must not reach the application; equally it is not an error, because
               ordinary reordering produces it whenever a peer writes immediately
               after activating.
 
               Data under an epoch the established association owns stays valid
               while a renegotiation is in flight, per 4.1.
 
               Epoch zero is neither: application data there is plaintext, so it is
               never legitimate and no association is at stake.
               */
               if(m_is_datagram && record.epoch() > 0) {
                  const uint16_t active_epoch =
                     m_epochs_before_latest_renegotiation ? m_epochs_before_latest_renegotiation->read_epoch : 0;
 
                  if(!m_active_state.has_value() || record.epoch() > active_epoch) {
                     continue;  // this handshake's epoch, still unauthenticated
                  }
               } else {
                  throw TLS_Exception(Alert::UnexpectedMessage, "Can't interleave application and handshake data");
               }
            }
            process_application_data(record.sequence(), m_record_buf);
         } else if(record.type() == Record_Type::Alert) {
            process_alert(m_record_buf);
         } else if(record.type() != Record_Type::Invalid) {
            throw Unexpected_Message("Unexpected record type " + std::to_string(static_cast<size_t>(record.type())) +
                                     " from counterparty");
         }
      }
 
      return 0;  // on a record boundary
   } catch(TLS_Exception& e) {
      send_fatal_alert(e.type());
      throw;
   } catch(Invalid_Authentication_Tag&) {
      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::Policy::allow_dtls_epoch0_restart(), Botan::TLS::ApplicationData, BOTAN_ASSERT, BOTAN_ASSERT_IMPLICATION, Botan::TLS::ChangeCipherSpec, Botan::TLS::ClientHello, Botan::TLS::Record_Header::epoch(), Botan::TLS::Handshake, Botan::TLS::Invalid, Botan::TLS::Protocol_Version::major_version(), Botan::TLS::MAX_PLAINTEXT_SIZE, Botan::TLS::Record_Header::needed(), policy(), Botan::TLS::read_record(), Botan::TLS::Channel_Impl::send_fatal_alert(), Botan::TLS::Record_Header::sequence(), Botan::TLS::Record_Header::type(), Botan::TLS::TLS_Exception::type(), and Botan::TLS::Record_Header::version().

inspect_handshake_message()

void Botan::TLS::Channel_Impl_12::inspect_handshake_message ( const Handshake_Message & msg )

protectedinherited

is_active()

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

overridevirtualinherited

Returns

true iff the connection is active for sending application data

Implements Botan::TLS::Channel_Impl.

Definition at line 468 of file tls_channel_impl_12.cpp.

                                      {
   return !is_closed() && is_handshake_complete();
}

References is_closed(), and is_handshake_complete().

Referenced by to_peer().

is_closed()

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

overridevirtualinherited

Returns

true iff the connection has been definitely closed

Implements Botan::TLS::Channel_Impl.

Definition at line 480 of file tls_channel_impl_12.cpp.

                                      {
   return m_has_been_closed;
}

Referenced by is_active(), is_closed_for_reading(), is_closed_for_writing(), and send_alert().

is_closed_for_reading()

bool Botan::TLS::Channel_Impl_12::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 98 of file tls_channel_impl_12.h.

{ return is_closed(); }

References is_closed().

is_closed_for_writing()

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

inlineoverridevirtualinherited

Returns

true iff the connection has been definitely closed

Implements Botan::TLS::Channel_Impl.

Definition at line 100 of file tls_channel_impl_12.h.

{ return is_closed(); }

References is_closed().

is_downgrading()

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

inlineprotectedinherited

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

See also

Downgrade_Information

Definition at line 282 of file tls_channel_impl.h.

                                  {
#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
         return m_downgrade_info && m_downgrade_info->will_downgrade;
#else
         return false;
#endif
      }

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::Channel_Impl_12::is_handshake_complete ( ) const

overridevirtualinherited

Returns

true iff the TLS handshake completed successfully

Implements Botan::TLS::Channel_Impl.

Definition at line 464 of file tls_channel_impl_12.cpp.

                                                  {
   return m_active_state.has_value();
}

Referenced by is_active().

key_material_export()

SymmetricKey Botan::TLS::Channel_Impl_12::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 1022 of file tls_channel_impl_12.cpp.

                                                                       {
   if(!m_active_state.has_value()) {
      throw Invalid_State("Channel_Impl_12::key_material_export connection not active");
   }
 
   // A fatal alert should have already cleared the active state:
   BOTAN_ASSERT_NOMSG(!m_had_fatal_alert);
 
   if(pending_state() != nullptr) {
      throw Invalid_State("Channel_Impl_12::key_material_export cannot export during renegotiation");
   }
 
   auto prf = callbacks().tls12_protocol_specific_kdf(m_active_state->prf_algo());
 
   const auto salt = [&] {
      if(context.empty()) {
         return concat(m_active_state->client_random(), m_active_state->server_random());
      } else {
         return concat(m_active_state->client_random(),
                       m_active_state->server_random(),
                       store_be(static_cast<uint16_t>(context.size())),
                       as_span_of_bytes(context));
      }
   }();
 
   return SymmetricKey(prf->derive_key(length, m_active_state->master_secret(), salt, as_span_of_bytes(label)));
}

References Botan::as_span_of_bytes(), BOTAN_ASSERT_NOMSG, callbacks(), Botan::concat(), Botan::store_be(), and Botan::TLS::Callbacks::tls12_protocol_specific_kdf().

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

{ return false; }

next_retransmission_timeout()

std::optional< std::chrono::milliseconds > Botan::TLS::Channel_Impl_12::next_retransmission_timeout ( ) const

overridevirtualinherited

Reimplemented from Botan::TLS::Channel_Impl.

Definition at line 472 of file tls_channel_impl_12.cpp.

                                                                                      {
   if(m_is_datagram && !m_has_been_closed && m_pending_state) {
      return m_pending_state->handshake_io().next_retransmission_timeout();
   }
 
   return std::nullopt;
}

note_resumption_handle()

void Botan::TLS::Channel_Impl_12::note_resumption_handle ( std::optional< Session_Handle > handle )

protectedinherited

Record the resumption handle this connection was established or resumed under, so that a fatal alert can invalidate it. The ServerHello session ID does not identify a ticket-backed session.

Definition at line 127 of file tls_channel_impl_12.cpp.

                                                                               {
   m_resumption_handle = std::move(handle);
}

peer_cert_chain()

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

overridevirtualinherited

Returns

certificate chain of the peer (may be empty)

Implements Botan::TLS::Channel_Impl.

Definition at line 223 of file tls_channel_impl_12.cpp.

                                                                   {
   if(m_active_state.has_value()) {
      return m_active_state->peer_certs();
   }
   return std::vector<X509_Certificate>();
}

peer_raw_public_key()

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

inlineoverridevirtualinherited

Note: Raw public key for authentication (RFC7250) is currently not implemented for TLS 1.2.

Returns

raw public key of the peer (will be nullptr)

Implements Botan::TLS::Channel_Impl.

Definition at line 113 of file tls_channel_impl_12.h.

{ return nullptr; }

policy()

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

inlineprotectedinherited

Definition at line 184 of file tls_channel_impl_12.h.

{ return *m_policy; }

Referenced by Channel_Impl_12(), Botan::TLS::Client_Impl_12::Client_Impl_12(), create_handshake_state(), from_peer(), renegotiate(), and Botan::TLS::Server_Impl_12::Server_Impl_12().

renegotiate()

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

overridevirtualinherited

Attempt to renegotiate the session

Parameters

force_full_renegotiation

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

Implements Botan::TLS::Channel_Impl.

Definition at line 373 of file tls_channel_impl_12.cpp.

                                                               {
   if(pending_state() != nullptr) {  // currently in handshake?
      return;
   }
 
   if(m_active_state.has_value()) {
      // A DTLS handshake consumes one read and one write epoch. Refuse here if
      // either is spent, so the caller learns before the handshake tears the
      // working association down partway through. See next_epoch().
      if(m_is_datagram &&
         (sequence_numbers().current_read_epoch() == 0xFFFF || sequence_numbers().current_write_epoch() == 0xFFFF)) {
         throw Invalid_State("DTLS epoch counter exhausted, a new association is required");
      }
 
      if(!force_full_renegotiation) {
         force_full_renegotiation = !policy().allow_resumption_for_renegotiation();
      }
 
      initiate_handshake(create_handshake_state(m_active_state->version()), force_full_renegotiation);
   } else {
      throw Invalid_State("Cannot renegotiate on inactive connection");
   }
}

References Botan::TLS::Policy::allow_resumption_for_renegotiation(), create_handshake_state(), initiate_handshake(), and policy().

reset_active_association_state()

void Botan::TLS::Channel_Impl_12::reset_active_association_state ( )

protectedinherited

Definition at line 169 of file tls_channel_impl_12.cpp.

                                                     {
   // This operation only makes sense for DTLS
   BOTAN_ASSERT_NOMSG(m_is_datagram);
   m_active_state.reset();
   m_read_cipher_states.clear();
   m_write_cipher_states.clear();
 
   m_write_cipher_states[0] = nullptr;
   m_read_cipher_states[0] = {};
 
   if(m_sequence_numbers) {
      m_sequence_numbers->reset();  // NOLINT(*-ambiguous-smartptr-reset-call)
   }
}

References BOTAN_ASSERT_NOMSG.

rng()

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

inlineprotectedinherited

Definition at line 180 of file tls_channel_impl_12.h.

{ return *m_rng; }

Referenced by Channel_Impl_12(), Botan::TLS::Client_Impl_12::Client_Impl_12(), and Botan::TLS::Server_Impl_12::Server_Impl_12().

secure_renegotiation_check() [1/2]

void Botan::TLS::Channel_Impl_12::secure_renegotiation_check ( const Client_Hello_12 * client_hello )

protectedinherited

Definition at line 957 of file tls_channel_impl_12.cpp.

                                                                                    {
   BOTAN_ASSERT_NONNULL(client_hello);
   const bool secure_renegotiation = client_hello->secure_renegotiation();
 
   if(m_active_state && m_active_state->client_supports_secure_renegotiation() != secure_renegotiation) {
      throw TLS_Exception(Alert::HandshakeFailure, "Client changed its mind about secure renegotiation");
   }
 
   if(secure_renegotiation) {
      const std::vector<uint8_t>& data = client_hello->renegotiation_info();
 
      const auto expected = secure_renegotiation_data_for_client_hello();
      if(!CT::is_equal<uint8_t>(data, expected).as_bool()) {
         throw TLS_Exception(Alert::HandshakeFailure, "Client sent bad values for secure renegotiation");
      }
   }
}

References BOTAN_ASSERT_NONNULL, Botan::CT::is_equal(), Botan::TLS::Client_Hello_12::renegotiation_info(), Botan::TLS::Client_Hello_12::secure_renegotiation(), and secure_renegotiation_data_for_client_hello().

secure_renegotiation_check() [2/2]

void Botan::TLS::Channel_Impl_12::secure_renegotiation_check ( const Server_Hello_12 * server_hello )

protectedinherited

Definition at line 975 of file tls_channel_impl_12.cpp.

                                                                                    {
   BOTAN_ASSERT_NONNULL(server_hello);
   const bool secure_renegotiation = server_hello->secure_renegotiation();
 
   if(m_active_state && m_active_state->server_supports_secure_renegotiation() != secure_renegotiation) {
      throw TLS_Exception(Alert::HandshakeFailure, "Server changed its mind about secure renegotiation");
   }
 
   if(secure_renegotiation) {
      const std::vector<uint8_t>& data = server_hello->renegotiation_info();
 
      const auto expected = secure_renegotiation_data_for_server_hello();
      if(!CT::is_equal<uint8_t>(data, expected).as_bool()) {
         throw TLS_Exception(Alert::HandshakeFailure, "Server sent bad values for secure renegotiation");
      }
   }
}

References BOTAN_ASSERT_NONNULL, Botan::CT::is_equal(), Botan::TLS::Server_Hello_12::renegotiation_info(), Botan::TLS::Server_Hello_12::secure_renegotiation(), and secure_renegotiation_data_for_server_hello().

secure_renegotiation_data_for_client_hello()

std::vector< uint8_t > Botan::TLS::Channel_Impl_12::secure_renegotiation_data_for_client_hello ( ) const

protectedinherited

Definition at line 993 of file tls_channel_impl_12.cpp.

                                                                                     {
   if(m_active_state.has_value()) {
      return m_active_state->client_finished_verify_data();
   }
   return std::vector<uint8_t>();
}

Referenced by secure_renegotiation_check().

secure_renegotiation_data_for_server_hello()

std::vector< uint8_t > Botan::TLS::Channel_Impl_12::secure_renegotiation_data_for_server_hello ( ) const

protectedinherited

Definition at line 1000 of file tls_channel_impl_12.cpp.

                                                                                     {
   if(m_active_state.has_value()) {
      return concat(m_active_state->client_finished_verify_data(), m_active_state->server_finished_verify_data());
   } else {
      return {};
   }
}

References Botan::concat().

Referenced by secure_renegotiation_check().

secure_renegotiation_supported()

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

overridevirtualinherited

Returns

true iff the counterparty supports the secure renegotiation extensions.

Implements Botan::TLS::Channel_Impl.

Definition at line 1008 of file tls_channel_impl_12.cpp.

                                                           {
   if(m_active_state.has_value()) {
      return m_active_state->server_supports_secure_renegotiation();
   }
 
   if(const auto* pending = pending_state()) {
      if(const auto* hello = pending->server_hello()) {
         return hello->secure_renegotiation();
      }
   }
 
   return false;
}

send_alert()

void Botan::TLS::Channel_Impl_12::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 908 of file tls_channel_impl_12.cpp.

                                                   {
   const bool ready_to_send_anything = !is_closed() && m_sequence_numbers;
   if(alert.is_valid() && ready_to_send_anything) {
      try {
         send_record(Record_Type::Alert, alert.serialize());
      } catch(...) { /* swallow it */
      }
   }
 
   // RFC 5246 7.2.2:
   //    no_renegotiation
   //       Sent by the client in response to a hello request or by the
   //       server in response to a client hello after initial handshaking.
   //
   // In this case we are the peer sending the refusal, so there is no reason
   // for our epochs to have moved. If they somehow did, clear the pending
   // state. A strictly better approach here would be to simply throw
   // Internal_Error, but send_alert is called from within catch handlers
   // so this is not currently viable.
   if(alert.type() == Alert::NoRenegotiation && m_active_state.has_value()) {
      if(pending_handshake_epochs_unmoved()) {
         clear_pending_handshake_state();
      }
   }
 
   if(alert.is_fatal()) {
      // Order matters: the channel is made unusable and its secrets destroyed
      // before any application-supplied storage is touched, so a throwing
      // session manager cannot leave is_active() true with live keys.
      m_had_fatal_alert = true;
      m_has_been_closed = true;
 
      // Alert::None is the local teardown that is never sent to the peer, used
      // where the trigger was unauthenticated input or a local timeout. Evicting
      // the resumption state on that basis would hand anyone able to reach the
      // address the ability to destroy it, which is what keeping the teardown
      // local exists to prevent.
      const auto invalidated =
         (alert.type() == Alert::None) ? std::vector<Session_Handle>() : take_sessions_to_invalidate();
 
      reset_state();
      invalidate_sessions(invalidated);
   }
 
   if(alert.type() == Alert::CloseNotify || alert.is_fatal()) {
      m_has_been_closed = true;
   }
}

References Botan::TLS::Alert, is_closed(), Botan::TLS::Alert::is_fatal(), Botan::TLS::Alert::is_valid(), Botan::TLS::Alert::serialize(), and Botan::TLS::Alert::type().

send_fatal_alert()

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

inlineinherited

Send a fatal alert

Definition at line 75 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_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 159 of file tls_channel_impl.h.

{ return 0; }

send_warning_alert()

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

inlineinherited

Send a warning alert

Definition at line 70 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_12::session_manager ( )

inlineprotectedinherited

Definition at line 182 of file tls_channel_impl_12.h.

{ return *m_session_manager; }

Referenced by Channel_Impl_12(), Botan::TLS::Client_Impl_12::Client_Impl_12(), and Botan::TLS::Server_Impl_12::Server_Impl_12().

timeout_check()

bool Botan::TLS::Channel_Impl_12::timeout_check ( )

overridevirtualinherited

Perform a handshake timeout check. This does nothing unless this is a DTLS channel with a handshake in progress.

Implements Botan::TLS::Channel_Impl.

Definition at line 358 of file tls_channel_impl_12.cpp.

                                    {
   if(m_is_datagram && !m_has_been_closed && m_pending_state) {
      try {
         return m_pending_state->handshake_io().timeout_check();
      } catch(const TLS_Exception&) {
         abandon_timed_out_handshake();
         throw;
      }
   }
 
   // Old cipher states are pruned at install time (see prune_old_cipher_states),
   // so no periodic cleanup is needed here.
   return false;
}

to_peer()

void Botan::TLS::Channel_Impl_12::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 900 of file tls_channel_impl_12.cpp.

                                                         {
   if(!is_active()) {
      throw Invalid_State("Data cannot be sent on inactive TLS connection");
   }
 
   send_record_array(sequence_numbers().current_write_epoch(), Record_Type::ApplicationData, data.data(), data.size());
}

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

update_traffic_keys()

void Botan::TLS::Channel_Impl_12::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 397 of file tls_channel_impl_12.cpp.

                                                {
   throw Invalid_Argument("cannot update traffic keys on a TLS 1.2 channel");
}

---

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

• src/lib/tls/tls12/tls_client_impl_12.h
• src/lib/tls/tls12/tls_client_impl_12.cpp