#include <tls_cipher_state.h>

Public Types
enum class	PSK_Type : uint8_t { Resumption , External , Imported }

Public Member Functions
void	advance_with_client_finished (const Transcript_Hash &transcript_hash)
void	advance_with_client_hello (const Transcript_Hash &transcript_hash, const Secret_Logger &channel)
void	advance_with_server_finished (const Transcript_Hash &transcript_hash, const Secret_Logger &channel)
void	advance_with_server_hello (const Ciphersuite &cipher, secure_vector< uint8_t > &&shared_secret, const Transcript_Hash &transcript_hash, const Secret_Logger &channel)
bool	can_decrypt_application_traffic () const
bool	can_encrypt_application_traffic () const
bool	can_export_keys () const
	Cipher_State (Cipher_State &&other)=delete
	Cipher_State (const Cipher_State &other)=delete
void	clear_read_keys ()
void	clear_write_keys ()
size_t	decrypt_output_length (size_t input_length) const
uint64_t	decrypt_record_fragment (const std::vector< uint8_t > &header, secure_vector< uint8_t > &encrypted_fragment)
size_t	encrypt_output_length (size_t input_length) const
uint64_t	encrypt_record_fragment (const std::vector< uint8_t > &header, secure_vector< uint8_t > &fragment)
secure_vector< uint8_t >	export_key (std::string_view label, std::string_view context, size_t length) const
std::vector< uint8_t >	finished_mac (const Transcript_Hash &transcript_hash) const
std::string	hash_algorithm () const
bool	is_compatible_with (const Ciphersuite &cipher) const
size_t	minimum_decryption_input_length () const
bool	must_expect_unprotected_alert_traffic () const
Ticket_Nonce	next_ticket_nonce ()
Cipher_State &	operator= (Cipher_State &&other)=delete
Cipher_State &	operator= (const Cipher_State &other)=delete
secure_vector< uint8_t >	psk (const Ticket_Nonce &nonce) const
std::vector< uint8_t >	psk_binder_mac (const Transcript_Hash &transcript_hash_with_truncated_client_hello) const
void	update_read_keys (const Secret_Logger &channel)
void	update_write_keys (const Secret_Logger &channel)
bool	verify_peer_finished_mac (const Transcript_Hash &transcript_hash, const std::vector< uint8_t > &peer_mac) const
	~Cipher_State ()

Static Public Member Functions
static std::unique_ptr< Cipher_State >	init_with_psk (Connection_Side side, PSK_Type type, secure_vector< uint8_t > &&psk, std::string_view prf_algo)
static std::unique_ptr< Cipher_State >	init_with_server_hello (Connection_Side side, secure_vector< uint8_t > &&shared_secret, const Ciphersuite &cipher, const Transcript_Hash &transcript_hash, const Secret_Logger &channel)

Detailed Description

This class implements the key schedule for TLS 1.3 as described in RFC 8446 7.1.

Internally, it reflects the state machine pictured in the same RFC section. It provides the following entry points and state advancement methods that each facilitate certain cryptographic functionality:

init_with_psk() sets up the cipher state with a pre-shared key (out of band or via session ticket). will allow sending early data in the future
init_with_server_hello() / advance_with_server_hello() allows encrypting and decrypting handshake traffic, as well as producing and validating the client/server handshake finished MACs
advance_with_server_finished() allows encrypting and decrypting application traffic
advance_with_client_finished() allows negotiation of resumption PSKs

While encrypting and decrypting records (RFC 8446 5.2) Cipher_State internally keeps track of the current sequence numbers (RFC 8446 5.3) to calculate the correct Per-Record Nonce. Sequence numbers are reset appropriately, whenever traffic secrets change.

Handshake finished MAC calculation and verification is described in RFC 8446 4.4.4.

PSKs calculation is described in RFC 8446 4.6.1.

Definition at line 61 of file tls_cipher_state.h.

Member Enumeration Documentation

◆ PSK_Type

enum class Botan::TLS::Cipher_State::PSK_Type : uint8_t

strong

Enumerator
Resumption
External
Imported

Definition at line 63 of file tls_cipher_state.h.

                          : uint8_t {
         Resumption,  // RFC 8446
         External,    // RFC 8446
         Imported,    // RFC 9258 PSK importer - uses "imp binder" label
      };

Constructor & Destructor Documentation

◆ ~Cipher_State()

Botan::TLS::Cipher_State::~Cipher_State ( )

default

◆ Cipher_State() [1/2]

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

delete

References Cipher_State().

Referenced by Cipher_State(), Cipher_State(), init_with_psk(), init_with_server_hello(), operator=(), and operator=().

◆ Cipher_State() [2/2]

Botan::TLS::Cipher_State::Cipher_State ( Cipher_State && other )

delete

References Cipher_State().

Member Function Documentation

◆ advance_with_client_finished()

void Botan::TLS::Cipher_State::advance_with_client_finished ( const Transcript_Hash & transcript_hash )

Transition to the final internal state allowing to create resumptions.

Definition at line 205 of file tls_cipher_state.cpp.

                                                                                      {
   BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic);
 
   zap(m_finished_key);
   zap(m_peer_finished_key);
 
   // With the client's Finished message, the handshake is complete and
   // we can process client application data.
   if(m_connection_side == Connection_Side::Server) {
      derive_read_traffic_key(m_read_application_traffic_secret);
   } else {
      derive_write_traffic_key(m_write_application_traffic_secret);
   }
 
   const auto master_secret = hkdf_extract(secure_vector<uint8_t>(m_hash->output_length(), 0x00));
 
   m_resumption_master_secret = derive_secret(master_secret, "res master", transcript_hash);
 
   // This was the final state change; the salt is no longer needed.
   zap(m_salt);
 
   m_state = State::Completed;
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Server, and Botan::zap().

Referenced by operator=().

◆ advance_with_client_hello()

void Botan::TLS::Cipher_State::advance_with_client_hello	(	const Transcript_Hash &	transcript_hash,
		const Secret_Logger &	channel )

Transition internal secrets/keys for transporting early application data. Note that this state transition is legal only for handshakes using PSK.

Definition at line 141 of file tls_cipher_state.cpp.

                                                                                                                {
   BOTAN_ASSERT_NOMSG(m_state == State::PskBinder);
 
   zap(m_binder_key);
 
   // TODO: Currently 0-RTT is not yet implemented, hence we don't derive the
   //       early traffic secret for now.
   //
   // const auto client_early_traffic_secret = derive_secret(m_early_secret, "c e traffic", transcript_hash);
   // derive_write_traffic_key(client_early_traffic_secret);
 
   m_exporter_master_secret = derive_secret(m_early_secret, "e exp master", transcript_hash);
 
   // draft-thomson-tls-keylogfile-00 Section 3.1
   //    An implementation of TLS 1.3 use the label
   //    "EARLY_EXPORTER_MASTER_SECRET" to identify the secret that is using for
   //    early exporters
   logger.maybe_log_secret("EARLY_EXPORTER_MASTER_SECRET", m_exporter_master_secret);
 
   m_salt = derive_secret(m_early_secret, "derived", empty_hash());
   zap(m_early_secret);
 
   m_state = State::EarlyTraffic;
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Secret_Logger::maybe_log_secret(), and Botan::zap().

Referenced by operator=().

◆ advance_with_server_finished()

void Botan::TLS::Cipher_State::advance_with_server_finished	(	const Transcript_Hash &	transcript_hash,
		const Secret_Logger &	channel )

Transition internal secrets/keys for transporting application data.

Definition at line 166 of file tls_cipher_state.cpp.

                                                                                                                   {
   BOTAN_ASSERT_NOMSG(m_state == State::HandshakeTraffic);
 
   const auto master_secret = hkdf_extract(secure_vector<uint8_t>(m_hash->output_length(), 0x00));
 
   auto client_application_traffic_secret = derive_secret(master_secret, "c ap traffic", transcript_hash);
   auto server_application_traffic_secret = derive_secret(master_secret, "s ap traffic", transcript_hash);
 
   // draft-thomson-tls-keylogfile-00 Section 3.1
   //    An implementation of TLS 1.3 use the label "CLIENT_TRAFFIC_SECRET_0"
   //    and "SERVER_TRAFFIC_SECRET_0" to identify the secrets are using to
   //    protect the connection.
   logger.maybe_log_secret("CLIENT_TRAFFIC_SECRET_0", client_application_traffic_secret);
   logger.maybe_log_secret("SERVER_TRAFFIC_SECRET_0", server_application_traffic_secret);
 
   // Note: the secrets for processing client's application data
   //       are not derived before the client's Finished message
   //       was seen and the handshake can be considered finished.
   if(m_connection_side == Connection_Side::Server) {
      derive_write_traffic_key(server_application_traffic_secret);
      m_read_application_traffic_secret = std::move(client_application_traffic_secret);
      m_write_application_traffic_secret = std::move(server_application_traffic_secret);
   } else {
      derive_read_traffic_key(server_application_traffic_secret);
      m_read_application_traffic_secret = std::move(server_application_traffic_secret);
      m_write_application_traffic_secret = std::move(client_application_traffic_secret);
   }
 
   m_exporter_master_secret = derive_secret(master_secret, "exp master", transcript_hash);
 
   // draft-thomson-tls-keylogfile-00 Section 3.1
   //    An implementation of TLS 1.3 use the label "EXPORTER_SECRET" to
   //    identify the secret that is used in generating exporters(rfc8446
   //    Section 7.5).
   logger.maybe_log_secret("EXPORTER_SECRET", m_exporter_master_secret);
 
   m_state = State::ServerApplicationTraffic;
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Secret_Logger::maybe_log_secret(), and Botan::TLS::Server.

Referenced by operator=().

◆ advance_with_server_hello()

void Botan::TLS::Cipher_State::advance_with_server_hello	(	const Ciphersuite &	cipher,
		secure_vector< uint8_t > &&	shared_secret,
		const Transcript_Hash &	transcript_hash,
		const Secret_Logger &	channel )

Transition internal secrets/keys for transporting handshake data.

Definition at line 516 of file tls_cipher_state.cpp.

                                                                          {
   BOTAN_ASSERT_NOMSG(m_state == State::EarlyTraffic);
   BOTAN_ASSERT_NOMSG(!m_encrypt);
   BOTAN_ASSERT_NOMSG(!m_decrypt);
   BOTAN_STATE_CHECK(is_compatible_with(cipher));
 
   m_encrypt = AEAD_Mode::create_or_throw(cipher.cipher_algo(), Cipher_Dir::Encryption);
   m_decrypt = AEAD_Mode::create_or_throw(cipher.cipher_algo(), Cipher_Dir::Decryption);
 
   const auto handshake_secret = hkdf_extract(std::move(shared_secret));
 
   const auto client_handshake_traffic_secret = derive_secret(handshake_secret, "c hs traffic", transcript_hash);
   const auto server_handshake_traffic_secret = derive_secret(handshake_secret, "s hs traffic", transcript_hash);
 
   // draft-thomson-tls-keylogfile-00 Section 3.1
   //    An implementation of TLS 1.3 use the label
   //    "CLIENT_HANDSHAKE_TRAFFIC_SECRET" and "SERVER_HANDSHAKE_TRAFFIC_SECRET"
   //    to identify the secrets are using to protect handshake messages.
   logger.maybe_log_secret("CLIENT_HANDSHAKE_TRAFFIC_SECRET", client_handshake_traffic_secret);
   logger.maybe_log_secret("SERVER_HANDSHAKE_TRAFFIC_SECRET", server_handshake_traffic_secret);
 
   if(m_connection_side == Connection_Side::Server) {
      derive_read_traffic_key(client_handshake_traffic_secret, true);
      derive_write_traffic_key(server_handshake_traffic_secret, true);
   } else {
      derive_read_traffic_key(server_handshake_traffic_secret, true);
      derive_write_traffic_key(client_handshake_traffic_secret, true);
   }
 
   m_salt = derive_secret(handshake_secret, "derived", empty_hash());
 
   m_state = State::HandshakeTraffic;
}

References BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, Botan::TLS::Ciphersuite::cipher_algo(), Botan::AEAD_Mode::create_or_throw(), Botan::Decryption, Botan::Encryption, is_compatible_with(), Botan::TLS::Secret_Logger::maybe_log_secret(), and Botan::TLS::Server.

Referenced by operator=().

◆ can_decrypt_application_traffic()

bool Botan::TLS::Cipher_State::can_decrypt_application_traffic ( ) const

Indicates whether the appropriate secrets to decrypt application traffic are available

Definition at line 339 of file tls_cipher_state.cpp.

                                                         {
   // TODO: when implementing early traffic (0-RTT) this will likely need
   //       to allow `State::EarlyTraffic`.
 
   if(m_connection_side == Connection_Side::Client && m_state != State::ServerApplicationTraffic &&
      m_state != State::Completed) {
      return false;
   }
 
   if(m_connection_side == Connection_Side::Server && m_state != State::Completed) {
      return false;
   }
 
   return !m_read_key.empty() && !m_read_iv.empty();
}

References Botan::TLS::Client, and Botan::TLS::Server.

◆ can_encrypt_application_traffic()

bool Botan::TLS::Cipher_State::can_encrypt_application_traffic ( ) const

Indicates whether the appropriate secrets to encrypt application traffic are available

Definition at line 323 of file tls_cipher_state.cpp.

                                                         {
   // TODO: when implementing early traffic (0-RTT) this will likely need
   //       to allow `State::EarlyTraffic`.
 
   if(m_connection_side == Connection_Side::Client && m_state != State::Completed) {
      return false;
   }
 
   if(m_connection_side == Connection_Side::Server && m_state != State::ServerApplicationTraffic &&
      m_state != State::Completed) {
      return false;
   }
 
   return !m_write_key.empty() && !m_write_iv.empty();
}

References Botan::TLS::Client, and Botan::TLS::Server.

◆ can_export_keys()

bool Botan::TLS::Cipher_State::can_export_keys ( ) const

inline

Indicates whether the appropriate secrets to export keys are available

Definition at line 203 of file tls_cipher_state.h.

                                   {
         return (m_state == State::EarlyTraffic || m_state == State::ServerApplicationTraffic ||
                 m_state == State::Completed) &&
                !m_exporter_master_secret.empty();
      }

Referenced by export_key().

◆ clear_read_keys()

void Botan::TLS::Cipher_State::clear_read_keys ( )

Remove handshake/traffic secrets for decrypting data from peer

Definition at line 661 of file tls_cipher_state.cpp.

                                   {
   zap(m_read_key);
   zap(m_read_iv);
   zap(m_read_application_traffic_secret);
}

References Botan::zap().

◆ clear_write_keys()

void Botan::TLS::Cipher_State::clear_write_keys ( )

Remove handshake/traffic secrets for encrypting data

Definition at line 667 of file tls_cipher_state.cpp.

                                    {
   zap(m_write_key);
   zap(m_write_iv);
   zap(m_write_application_traffic_secret);
}

References Botan::zap().

◆ decrypt_output_length()

size_t Botan::TLS::Cipher_State::decrypt_output_length ( size_t input_length ) const

Returns: number of bytes needed to decrypt input_length bytes

Definition at line 288 of file tls_cipher_state.cpp.

                                                                          {
   BOTAN_ASSERT_NONNULL(m_decrypt);
   return m_decrypt->output_length(input_length);
}

References BOTAN_ASSERT_NONNULL.

Referenced by Botan::TLS::Record_Layer::next_record(), and operator=().

◆ decrypt_record_fragment()

uint64_t Botan::TLS::Cipher_State::decrypt_record_fragment	(	const std::vector< uint8_t > &	header,
		secure_vector< uint8_t > &	encrypted_fragment )

Decrypt a TLS record fragment (RFC 8446 5.2 – TLSCiphertext.encrypted_record) using the currently available traffic secret keys and the current sequence number. This will internally increment the sequence number. Hence, multiple calls with the same input will not produce the same result.

Returns: the sequence number of the decrypted record

Definition at line 264 of file tls_cipher_state.cpp.

                                                                                           {
   BOTAN_ASSERT_NONNULL(m_decrypt);
   BOTAN_ARG_CHECK(encrypted_fragment.size() >= m_decrypt->minimum_final_size(), "fragment too short to decrypt");
 
   // RFC 8446 5.3
   //    Sequence numbers MUST NOT wrap.
   if(m_read_seq_no == std::numeric_limits<uint64_t>::max()) {
      throw Invalid_State("TLS read sequence number overflow");
   }
 
   m_decrypt->set_associated_data(header);
   m_decrypt->start(current_nonce(m_read_seq_no, m_read_iv));
 
   m_decrypt->finish(encrypted_fragment);
 
   return m_read_seq_no++;
}

References BOTAN_ARG_CHECK, and BOTAN_ASSERT_NONNULL.

Referenced by Botan::TLS::Record_Layer::next_record(), and operator=().

◆ encrypt_output_length()

size_t Botan::TLS::Cipher_State::encrypt_output_length ( size_t input_length ) const

Returns: number of bytes needed to encrypt input_length bytes

Definition at line 283 of file tls_cipher_state.cpp.

                                                                          {
   BOTAN_ASSERT_NONNULL(m_encrypt);
   return m_encrypt->output_length(input_length);
}

References BOTAN_ASSERT_NONNULL.

Referenced by operator=(), and Botan::TLS::Record_Layer::prepare_records().

◆ encrypt_record_fragment()

uint64_t Botan::TLS::Cipher_State::encrypt_record_fragment	(	const std::vector< uint8_t > &	header,
		secure_vector< uint8_t > &	fragment )

Encrypt a TLS record fragment (RFC 8446 5.2 – TLSInnerPlaintext) using the currently available traffic secret keys and the current sequence number. This will internally increment the sequence number. Hence, multiple calls with the same input will not produce the same result.

Returns: the sequence number of the encrypted record

Definition at line 248 of file tls_cipher_state.cpp.

                                                                                                                 {
   BOTAN_ASSERT_NONNULL(m_encrypt);
 
   // RFC 8446 5.3
   //    Sequence numbers MUST NOT wrap.
   if(m_write_seq_no == std::numeric_limits<uint64_t>::max()) {
      throw Invalid_State("TLS write sequence number overflow");
   }
 
   m_encrypt->set_associated_data(header);
   m_encrypt->start(current_nonce(m_write_seq_no, m_write_iv));
   m_encrypt->finish(fragment);
 
   return m_write_seq_no++;
}

References BOTAN_ASSERT_NONNULL.

Referenced by operator=(), and Botan::TLS::Record_Layer::prepare_records().

◆ export_key()

secure_vector< uint8_t > Botan::TLS::Cipher_State::export_key	(	std::string_view	label,
		std::string_view	context,
		size_t	length ) const

Derive key material to export (RFC 8446 7.5 and RFC 5705)

TODO: this does not yet support key export based on the early_exporter_master_secret.

RFC 8446 7.5 Implementations MUST use the exporter_master_secret unless explicitly specified by the application. The early_exporter_master_secret is defined for use in settings where an exporter is needed for 0-RTT data. A separate interface for the early exporter is RECOMMENDED [...].

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

Definition at line 442 of file tls_cipher_state.cpp.

                                                                                                                 {
   BOTAN_ASSERT_NOMSG(can_export_keys());
 
   m_hash->update(context);
   const auto context_hash = m_hash->final_stdvec();
   return hkdf_expand_label(
      derive_secret(m_exporter_master_secret, label, empty_hash()), "exporter", context_hash, length);
}

References BOTAN_ASSERT_NOMSG, and can_export_keys().

Referenced by operator=().

◆ finished_mac()

std::vector< uint8_t > Botan::TLS::Cipher_State::finished_mac ( const Transcript_Hash & transcript_hash ) const

Calculate the MAC for a TLS "Finished" handshake message (RFC 8446 4.4.4)

Definition at line 396 of file tls_cipher_state.cpp.

                                                                                          {
   BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Server || m_state == State::HandshakeTraffic);
   BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Client || m_state == State::ServerApplicationTraffic);
   BOTAN_ASSERT_NOMSG(!m_finished_key.empty());
 
   auto hmac = HMAC(m_hash->new_object());
   hmac.set_key(m_finished_key);
   hmac.update(transcript_hash);
   return hmac.final_stdvec();
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Client, and Botan::TLS::Server.

Referenced by Botan::TLS::Finished_13::Finished_13(), and operator=().

◆ hash_algorithm()

std::string Botan::TLS::Cipher_State::hash_algorithm ( ) const

The name of the hash algorithm used for the KDF in this cipher suite

Definition at line 355 of file tls_cipher_state.cpp.

                                             {
   BOTAN_ASSERT_NONNULL(m_hash);
   return m_hash->name();
}

References BOTAN_ASSERT_NONNULL.

Referenced by is_compatible_with().

◆ init_with_psk()

std::unique_ptr< Cipher_State > Botan::TLS::Cipher_State::init_with_psk	(	Connection_Side	side,
		const Cipher_State::PSK_Type	type,
		secure_vector< uint8_t > &&	psk,
		std::string_view	prf_algo )

static

Construct a Cipher_State from a Pre-Shared-Key.

Definition at line 132 of file tls_cipher_state.cpp.

                                                                                   {
   auto cs = std::unique_ptr<Cipher_State>(new Cipher_State(side, prf_algo));
   cs->advance_with_psk(type, std::move(psk));
   return cs;
}

References Cipher_State(), and psk().

Referenced by operator=().

◆ init_with_server_hello()

std::unique_ptr< Cipher_State > Botan::TLS::Cipher_State::init_with_server_hello	(	Connection_Side	side,
		secure_vector< uint8_t > &&	shared_secret,
		const Ciphersuite &	cipher,
		const Transcript_Hash &	transcript_hash,
		const Secret_Logger &	channel )

static

Construct a Cipher_State after receiving a server hello message.

Definition at line 121 of file tls_cipher_state.cpp.

                                                                                                {
   auto cs = std::unique_ptr<Cipher_State>(new Cipher_State(side, cipher.prf_algo()));
   cs->advance_without_psk();
   cs->advance_with_server_hello(cipher, std::move(shared_secret), transcript_hash, logger);
   return cs;
}

References Cipher_State(), and Botan::TLS::Ciphersuite::prf_algo().

Referenced by operator=().

◆ is_compatible_with()

bool Botan::TLS::Cipher_State::is_compatible_with ( const Ciphersuite & cipher ) const

Returns: true if the selected cipher primitives are compatible with the cipher suite.

Note that cipher suites are considered "compatible" as long as the already selected cipher primitives in this cipher state are compatible.

Definition at line 360 of file tls_cipher_state.cpp.

                                                                     {
   if(!cipher.usable_in_version(Protocol_Version::TLS_V13)) {
      return false;
   }
 
   if(hash_algorithm() != cipher.prf_algo()) {
      return false;
   }
 
   BOTAN_ASSERT_NOMSG((m_encrypt == nullptr) == (m_decrypt == nullptr));
   // Compare canonical AEAD names rather than substring-matching cipher_algo
   // against m_encrypt->name(). starts_with() is both too permissive (an
   // AES-128/CCM-8 instance starts with "AES-128/CCM" so it would accept the
   // CCM-16 suite) and too restrictive (cipher_algo "AES-128/CCM(8)" does not
   // prefix the canonical "AES-128/CCM(8,3)"). Re-instantiating the AEAD from
   // cipher_algo yields the same canonical name() the suite would produce.
   if(m_encrypt) {
      auto canonical = AEAD_Mode::create(cipher.cipher_algo(), Cipher_Dir::Encryption);
      if(!canonical || canonical->name() != m_encrypt->name()) {
         return false;
      }
   }
 
   return true;
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Ciphersuite::cipher_algo(), Botan::AEAD_Mode::create(), Botan::Encryption, hash_algorithm(), Botan::TLS::Ciphersuite::prf_algo(), and Botan::TLS::Ciphersuite::usable_in_version().

Referenced by advance_with_server_hello().

◆ minimum_decryption_input_length()

size_t Botan::TLS::Cipher_State::minimum_decryption_input_length ( ) const

Returns: the minimum ciphertext length for decryption

Definition at line 293 of file tls_cipher_state.cpp.

                                                           {
   BOTAN_ASSERT_NONNULL(m_decrypt);
   return m_decrypt->minimum_final_size();
}

References BOTAN_ASSERT_NONNULL.

Referenced by Botan::TLS::Record_Layer::next_record(), and operator=().

◆ must_expect_unprotected_alert_traffic()

bool Botan::TLS::Cipher_State::must_expect_unprotected_alert_traffic ( ) const

Indicates whether unprotected Alert records are to be expected

Definition at line 298 of file tls_cipher_state.cpp.

                                                               {
   // Client side:
   //   After successfully receiving a Server Hello we expect servers to send
   //   alerts as protected records only, just like they start protecting their
   //   handshake data at this point.
   if(m_connection_side == Connection_Side::Client && m_state == State::EarlyTraffic) {
      return true;
   }
 
   // Server side:
   //   Servers must expect clients to send unprotected alerts during the hand-
   //   shake. In particular, in the response to the server's first protected
   //   flight. We don't expect the client to send alerts protected under the
   //   early traffic secret.
   //
   // TODO: when implementing PSK and/or early data for the server, we might
   //       need to reconsider this decision.
   if(m_connection_side == Connection_Side::Server &&
      (m_state == State::HandshakeTraffic || m_state == State::ServerApplicationTraffic)) {
      return true;
   }
 
   return false;
}

References Botan::TLS::Client, and Botan::TLS::Server.

Referenced by Botan::TLS::Record_Layer::next_record().

◆ next_ticket_nonce()

Ticket_Nonce Botan::TLS::Cipher_State::next_ticket_nonce ( )

Generates a nonce value that is unique for any given Cipher_State object. Note that the number of nonces is limited to 2^16 and this method will throw if more nonces are requested.

Definition at line 425 of file tls_cipher_state.cpp.

                                             {
   BOTAN_STATE_CHECK(m_state == State::Completed);
   if(m_ticket_nonce_exhausted) {
      throw Botan::Invalid_State("ticket nonce pool exhausted");
   }
 
   auto retval = store_be<Ticket_Nonce>(m_ticket_nonce);
 
   if(m_ticket_nonce == std::numeric_limits<decltype(m_ticket_nonce)>::max()) {
      m_ticket_nonce_exhausted = true;
   } else {
      ++m_ticket_nonce;
   }
 
   return retval;
}

References BOTAN_STATE_CHECK, and Botan::store_be().

Referenced by operator=().

◆ operator=() [1/2]

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

delete

References advance_with_client_finished(), advance_with_client_hello(), advance_with_server_finished(), advance_with_server_hello(), Cipher_State(), decrypt_output_length(), decrypt_record_fragment(), encrypt_output_length(), encrypt_record_fragment(), export_key(), finished_mac(), init_with_psk(), init_with_server_hello(), minimum_decryption_input_length(), next_ticket_nonce(), psk(), psk_binder_mac(), and verify_peer_finished_mac().

◆ operator=() [2/2]

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

delete

References Cipher_State().

◆ psk()

secure_vector< uint8_t > Botan::TLS::Cipher_State::psk ( const Ticket_Nonce & nonce ) const

Calculate the PSK for the given nonce (RFC 8446 4.6.1)

Definition at line 419 of file tls_cipher_state.cpp.

                                                                        {
   BOTAN_ASSERT_NOMSG(m_state == State::Completed);
 
   return derive_secret(m_resumption_master_secret, "resumption", nonce.get());
}

References BOTAN_ASSERT_NOMSG, and Botan::detail::Strong_Base< T >::get().

Referenced by init_with_psk(), and operator=().

◆ psk_binder_mac()

std::vector< uint8_t > Botan::TLS::Cipher_State::psk_binder_mac ( const Transcript_Hash & transcript_hash_with_truncated_client_hello ) const

Calculates the MAC for a PSK binder value in Client Hellos. Note that the transcript hash passed into this method is computed from a partial Client Hello (RFC 8446 4.2.11.2)

Definition at line 386 of file tls_cipher_state.cpp.

                                                                             {
   BOTAN_ASSERT_NOMSG(m_state == State::PskBinder);
 
   auto hmac = HMAC(m_hash->new_object());
   hmac.set_key(m_binder_key);
   hmac.update(transcript_hash_with_truncated_client_hello);
   return hmac.final_stdvec();
}

References BOTAN_ASSERT_NOMSG.

Referenced by operator=().

◆ update_read_keys()

void Botan::TLS::Cipher_State::update_read_keys ( const Secret_Logger & channel )

Updates the key material used for decrypting data This is triggered after we received a Key_Update from the peer.

Note that this must not be called before the connection is ready for application traffic.

Definition at line 634 of file tls_cipher_state.cpp.

                                                               {
   BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic || m_state == State::Completed);
 
   m_read_application_traffic_secret =
      hkdf_expand_label(m_read_application_traffic_secret, "traffic upd", {}, m_hash->output_length());
 
   const auto secret_label = fmt("{}_TRAFFIC_SECRET_{}",
                                 m_connection_side == Connection_Side::Server ? "CLIENT" : "SERVER",
                                 ++m_read_key_update_count);
   logger.maybe_log_secret(secret_label, m_read_application_traffic_secret);
 
   derive_read_traffic_key(m_read_application_traffic_secret);
}

References BOTAN_ASSERT_NOMSG, Botan::fmt(), Botan::TLS::Secret_Logger::maybe_log_secret(), and Botan::TLS::Server.

◆ update_write_keys()

void Botan::TLS::Cipher_State::update_write_keys ( const Secret_Logger & channel )

Updates the key material used for encrypting data This is triggered after we send a Key_Update to the peer.

Note that this must not be called before the connection is ready for application traffic.

Definition at line 648 of file tls_cipher_state.cpp.

                                                                {
   BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic || m_state == State::Completed);
   m_write_application_traffic_secret =
      hkdf_expand_label(m_write_application_traffic_secret, "traffic upd", {}, m_hash->output_length());
 
   const auto secret_label = fmt("{}_TRAFFIC_SECRET_{}",
                                 m_connection_side == Connection_Side::Server ? "SERVER" : "CLIENT",
                                 ++m_write_key_update_count);
   logger.maybe_log_secret(secret_label, m_write_application_traffic_secret);
 
   derive_write_traffic_key(m_write_application_traffic_secret);
}

References BOTAN_ASSERT_NOMSG, Botan::fmt(), Botan::TLS::Secret_Logger::maybe_log_secret(), and Botan::TLS::Server.

◆ verify_peer_finished_mac()

bool Botan::TLS::Cipher_State::verify_peer_finished_mac	(	const Transcript_Hash &	transcript_hash,
		const std::vector< uint8_t > &	peer_mac ) const

Validate a MAC received in a TLS "Finished" handshake message (RFC 8446 4.4.4)

Definition at line 407 of file tls_cipher_state.cpp.

                                                                                      {
   BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Server || m_state == State::ServerApplicationTraffic);
   BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Client || m_state == State::HandshakeTraffic);
   BOTAN_ASSERT_NOMSG(!m_peer_finished_key.empty());
 
   auto hmac = HMAC(m_hash->new_object());
   hmac.set_key(m_peer_finished_key);
   hmac.update(transcript_hash);
   return hmac.verify_mac(peer_mac);
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Client, and Botan::TLS::Server.

Referenced by operator=(), and Botan::TLS::Finished_13::verify().

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

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

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ PSK_Type

Constructor & Destructor Documentation

◆ ~Cipher_State()

◆ Cipher_State() [1/2]

◆ Cipher_State() [2/2]

Member Function Documentation

◆ advance_with_client_finished()

◆ advance_with_client_hello()

◆ advance_with_server_finished()

◆ advance_with_server_hello()

◆ can_decrypt_application_traffic()

◆ can_encrypt_application_traffic()

◆ can_export_keys()

◆ clear_read_keys()

◆ clear_write_keys()

◆ decrypt_output_length()

◆ decrypt_record_fragment()

◆ encrypt_output_length()

◆ encrypt_record_fragment()

◆ export_key()

◆ finished_mac()

◆ hash_algorithm()

◆ init_with_psk()

◆ init_with_server_hello()

◆ is_compatible_with()

◆ minimum_decryption_input_length()

◆ must_expect_unprotected_alert_traffic()

◆ next_ticket_nonce()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ psk()

◆ psk_binder_mac()

◆ update_read_keys()

◆ update_write_keys()

◆ verify_peer_finished_mac()