#include <tls_cipher_state.h>

Public Types
enum class	PSK_Type { Resumption , External }

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

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

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 62 of file tls_cipher_state.h.

Member Enumeration Documentation

◆ PSK_Type

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

strong

Enumerator
Resumption
External

Definition at line 64 of file tls_cipher_state.h.

                          {
         Resumption,
         External,  // currently not implemented
      };

Constructor & Destructor Documentation

◆ ~Cipher_State()

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

default

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

◆ 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
   loggger.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().

◆ 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.
   loggger.maybe_log_secret("CLIENT_TRAFFIC_SECRET_0", client_application_traffic_secret);
   loggger.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).
   loggger.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.

◆ 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 485 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.
   loggger.maybe_log_secret("CLIENT_HANDSHAKE_TRAFFIC_SECRET", client_handshake_traffic_secret);
   loggger.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.

◆ 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 329 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 313 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 198 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 626 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 632 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 278 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().

◆ 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 259 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");
 
   m_decrypt->set_key(m_read_key);
   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().

◆ 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 273 of file tls_cipher_state.cpp.

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

References BOTAN_ASSERT_NONNULL.

Referenced by 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);
 
   m_encrypt->set_key(m_write_key);
   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 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 422 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().

◆ 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 381 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().

◆ 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 345 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 psk().

◆ 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, loggger);
   return cs;
}

References Botan::TLS::Ciphersuite::prf_algo().

◆ 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 350 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));
   // TODO: Find a better way to check that the instantiated cipher algorithm
   //       is compatible with the one required by the cipher suite.
   // AEAD_Mode::create() sets defaults the tag length to 16 which is then
   // reported via AEAD_Mode::name() and hinders the trivial string comparison.
   if(m_encrypt && m_encrypt->name() != cipher.cipher_algo() && m_encrypt->name() != cipher.cipher_algo() + "(16)") {
      return false;
   }
 
   return true;
}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Ciphersuite::cipher_algo(), 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 283 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().

◆ 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 288 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 410 of file tls_cipher_state.cpp.

                                             {
   BOTAN_STATE_CHECK(m_state == State::Completed);
   if(m_ticket_nonce == std::numeric_limits<decltype(m_ticket_nonce)>::max()) {
      throw Botan::Invalid_State("ticket nonce pool exhausted");
   }
 
   Ticket_Nonce retval(std::vector<uint8_t>(sizeof(m_ticket_nonce)));
   store_be(m_ticket_nonce++, retval.data());
 
   return retval;
}

References BOTAN_STATE_CHECK, and Botan::store_be().

◆ 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 404 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().

◆ 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 371 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.

◆ 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 599 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 613 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 392 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 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()

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

◆ psk()

◆ psk_binder_mac()

◆ update_read_keys()

◆ update_write_keys()

◆ verify_peer_finished_mac()