Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::TLS_Cipher_State Class Referencefinal

#include <tls_cipher_state.h>

Inheritance diagram for Botan::TLS::TLS_Cipher_State:
Botan::TLS::Cipher_State

Public Types

using ExpansionLabelPrefix = std::array<uint8_t, 6>
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)
void advance_with_server_finished (const Transcript_Hash &transcript_hash)
void advance_with_server_hello (const Ciphersuite &cipher, secure_vector< uint8_t > &&shared_secret, const Transcript_Hash &transcript_hash)
bool can_decrypt_application_traffic () const
bool can_encrypt_application_traffic () const
bool can_export_keys () const
void clear_read_keys () override
void clear_write_keys () override
size_t decrypt_output_length (size_t input_length) const
Record deprotect_record (Record_TLS record, size_t incoming_record_size_limit)
size_t encrypt_output_length (size_t input_length) const
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
bool is_handshake_complete () const
size_t minimum_decryption_input_length () const
bool must_expect_unprotected_alert_traffic () const
Ticket_Nonce next_ticket_nonce ()
TLS_Cipher_State & operator= (const TLS_Cipher_State &)=delete
TLS_Cipher_State & operator= (TLS_Cipher_State &&)=delete
void protect_record (Record_Type type, std::span< const uint8_t > payload, size_t padding_bytes, secure_vector< uint8_t > &out)
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
uint64_t records_decrypted_with_current_key () const
uint64_t records_encrypted_with_current_key () const
void set_secret_logger (SecretLoggerFn secret_logger)
 TLS_Cipher_State (Connection_Side side, std::string_view prf_algo)
 TLS_Cipher_State (const TLS_Cipher_State &)=delete
 TLS_Cipher_State (TLS_Cipher_State &&)=delete
void update_read_keys ()
void update_write_keys ()
bool verify_peer_finished_mac (const Transcript_Hash &transcript_hash, const std::vector< uint8_t > &peer_mac) const
 ~TLS_Cipher_State () override

Static Public Member Functions

static std::unique_ptr< Cipher_State > init_with_psk (Connection_Side side, TLS_Flavor flavor, 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, TLS_Flavor flavor, secure_vector< uint8_t > &&shared_secret, const Ciphersuite &cipher, const Transcript_Hash &transcript_hash, SecretLoggerFn secret_logger)

Protected Member Functions

const Ciphersuite & ciphersuite () const
Cipher_State::Epoch create_epoch (Cipher_Dir direction, const secure_vector< uint8_t > &traffic_secret, bool handshake_epoch) const
void deprotect_and_hydrate_content_type (Epoch &epoch, std::span< const uint8_t > header, Record_Content &protected_record, size_t incoming_record_size_limit) const
secure_vector< uint8_t > hkdf_expand_label (const secure_vector< uint8_t > &secret, std::string_view label, const std::vector< uint8_t > &context, size_t length) const

Static Protected Member Functions

static void marshall_and_protect (Epoch &epoch, std::span< const uint8_t > header, std::span< const uint8_t > payload, Record_Type type, size_t padding_bytes, secure_vector< uint8_t > &out)
static size_t protected_record_length (Epoch &epoch, size_t payload_length, size_t padding_bytes)

Detailed Description

Cipher State implementation for TLS 1.3 (RFC 9846).

This re-uses the key schedule implementation in the Cipher_State base class and implements record (de)protection and epoch management for TLS 1.3. Epochs in TLS 1.3 are simply rolled over whenever necessary. No historic epochs are kept.

Definition at line 421 of file tls_cipher_state.h.

Member Typedef Documentation

◆ ExpansionLabelPrefix

using Botan::TLS::Cipher_State::ExpansionLabelPrefix = std::array<uint8_t, 6>
inherited

Definition at line 97 of file tls_cipher_state.h.

Member Enumeration Documentation

◆ PSK_Type

enum class Botan::TLS::Cipher_State::PSK_Type : uint8_t
stronginherited
Enumerator
Resumption 
External 
Imported 

Definition at line 73 of file tls_cipher_state.h.

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

Constructor & Destructor Documentation

◆ TLS_Cipher_State() [1/3]

Botan::TLS::TLS_Cipher_State::TLS_Cipher_State ( Connection_Side side,
std::string_view prf_algo )

Definition at line 806 of file tls_cipher_state.cpp.

806 :
807 Cipher_State(side, prf_algo, {'t', 'l', 's', '1', '3', ' '} /* RFC 9846 7.1 */) {}
Cipher_State(const Cipher_State &other)=delete

References Botan::TLS::Cipher_State::Cipher_State().

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

◆ ~TLS_Cipher_State()

Botan::TLS::TLS_Cipher_State::~TLS_Cipher_State ( )
overridedefault

◆ TLS_Cipher_State() [2/3]

Botan::TLS::TLS_Cipher_State::TLS_Cipher_State ( const TLS_Cipher_State & )
delete

References TLS_Cipher_State().

◆ TLS_Cipher_State() [3/3]

Botan::TLS::TLS_Cipher_State::TLS_Cipher_State ( TLS_Cipher_State && )
delete

References TLS_Cipher_State().

Member Function Documentation

◆ advance_with_client_finished()

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

Transition to the final internal state allowing to create resumptions.

Definition at line 234 of file tls_cipher_state.cpp.

234 {
235 BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic);
236 BOTAN_ASSERT_NONNULL(m_hash);
237 BOTAN_ASSERT_NOMSG(!m_client_application_traffic_secret_0.empty());
238
239 // With the client's Finished message, the handshake is complete and
240 // we can process client application data.
241 if(m_connection_side == Connection_Side::Server) {
242 advance_read_epoch(m_client_application_traffic_secret_0);
243 } else {
244 advance_write_epoch(m_client_application_traffic_secret_0);
245 }
246
247 // The handshake is complete, we won't need the stashed client application
248 // traffic secret any longer.
249 zap(m_client_application_traffic_secret_0);
250
251 const auto master_secret = hkdf_extract(secure_vector<uint8_t>(m_hash->output_length(), 0x00));
252
253 m_resumption_master_secret = derive_secret(master_secret, "res master", transcript_hash);
254
255 // This was the final state change; the salt is no longer needed.
256 zap(m_salt);
257
258 m_state = State::Completed;
259}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
virtual void advance_read_epoch(const secure_vector< uint8_t > &traffic_secret, bool handshake_epoch=false)=0
virtual void advance_write_epoch(const secure_vector< uint8_t > &traffic_secret, bool handshake_epoch=false)=0
void zap(std::vector< T, Alloc > &vec)
Definition secmem.h:261
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128

References advance_read_epoch(), advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, 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)
inherited

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

Definition at line 170 of file tls_cipher_state.cpp.

170 {
171 BOTAN_ASSERT_NOMSG(m_state == State::PskBinder);
172
173 zap(m_binder_key);
174
175 // TODO: Currently 0-RTT is not yet implemented, hence we don't derive the
176 // early traffic secret for now.
177 //
178 // const auto client_early_traffic_secret = derive_secret(m_early_secret, "c e traffic", transcript_hash);
179 // derive_write_traffic_key(client_early_traffic_secret);
180
181 m_exporter_master_secret = derive_secret(m_early_secret, "e exp master", transcript_hash);
182
183 // draft-thomson-tls-keylogfile-00 Section 3.1
184 // An implementation of TLS 1.3 use the label
185 // "EARLY_EXPORTER_MASTER_SECRET" to identify the secret that is using for
186 // early exporters
187 maybe_log_secret("EARLY_EXPORTER_MASTER_SECRET", m_exporter_master_secret);
188
189 m_salt = derive_secret(m_early_secret, "derived", empty_hash());
190 zap(m_early_secret);
191
192 m_state = State::EarlyTraffic;
193}

References BOTAN_ASSERT_NOMSG, and Botan::zap().

Referenced by operator=().

◆ advance_with_server_finished()

void Botan::TLS::Cipher_State::advance_with_server_finished ( const Transcript_Hash & transcript_hash)
inherited

Transition internal secrets/keys for transporting application data.

Definition at line 195 of file tls_cipher_state.cpp.

195 {
196 BOTAN_ASSERT_NOMSG(m_state == State::HandshakeTraffic);
197 BOTAN_ASSERT_NONNULL(m_hash);
198
199 const auto master_secret = hkdf_extract(secure_vector<uint8_t>(m_hash->output_length(), 0x00));
200
201 // We have to stash the client traffic application secret until the client's
202 // Finished message is available. Only then can we update the respective
203 // encryption/decryption epoch. See `advance_with_client_finished()`.
204 m_client_application_traffic_secret_0 = derive_secret(master_secret, "c ap traffic", transcript_hash);
205 auto server_application_traffic_secret = derive_secret(master_secret, "s ap traffic", transcript_hash);
206
207 // draft-thomson-tls-keylogfile-00 Section 3.1
208 // An implementation of TLS 1.3 use the label "CLIENT_TRAFFIC_SECRET_0"
209 // and "SERVER_TRAFFIC_SECRET_0" to identify the secrets are using to
210 // protect the connection.
211 maybe_log_secret("CLIENT_TRAFFIC_SECRET_0", m_client_application_traffic_secret_0);
212 maybe_log_secret("SERVER_TRAFFIC_SECRET_0", server_application_traffic_secret);
213
214 // Note: the secrets for processing client's application data
215 // are not derived before the client's Finished message
216 // was seen and the handshake can be considered finished.
217 if(m_connection_side == Connection_Side::Server) {
218 advance_write_epoch(server_application_traffic_secret);
219 } else {
220 advance_read_epoch(server_application_traffic_secret);
221 }
222
223 m_exporter_master_secret = derive_secret(master_secret, "exp master", transcript_hash);
224
225 // draft-thomson-tls-keylogfile-00 Section 3.1
226 // An implementation of TLS 1.3 use the label "EXPORTER_SECRET" to
227 // identify the secret that is used in generating exporters(rfc8446
228 // Section 7.5).
229 maybe_log_secret("EXPORTER_SECRET", m_exporter_master_secret);
230
231 m_state = State::ServerApplicationTraffic;
232}

References advance_read_epoch(), advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, 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 )
inherited

Transition internal secrets/keys for transporting handshake data.

Definition at line 656 of file tls_cipher_state.cpp.

658 {
659 BOTAN_ASSERT_NOMSG(m_state == State::EarlyTraffic);
661 BOTAN_STATE_CHECK(!m_ciphersuite.has_value());
662
663 m_ciphersuite = cipher;
664
665 const auto handshake_secret = hkdf_extract(std::move(shared_secret));
666
667 const auto client_handshake_traffic_secret = derive_secret(handshake_secret, "c hs traffic", transcript_hash);
668 const auto server_handshake_traffic_secret = derive_secret(handshake_secret, "s hs traffic", transcript_hash);
669
670 // draft-thomson-tls-keylogfile-00 Section 3.1
671 // An implementation of TLS 1.3 use the label
672 // "CLIENT_HANDSHAKE_TRAFFIC_SECRET" and "SERVER_HANDSHAKE_TRAFFIC_SECRET"
673 // to identify the secrets are using to protect handshake messages.
674 maybe_log_secret("CLIENT_HANDSHAKE_TRAFFIC_SECRET", client_handshake_traffic_secret);
675 maybe_log_secret("SERVER_HANDSHAKE_TRAFFIC_SECRET", server_handshake_traffic_secret);
676
677 if(m_connection_side == Connection_Side::Server) {
678 advance_read_epoch(client_handshake_traffic_secret, true /* handshake epoch */);
679 advance_write_epoch(server_handshake_traffic_secret, true /* handshake epoch */);
680 } else {
681 advance_read_epoch(server_handshake_traffic_secret, true /* handshake epoch */);
682 advance_write_epoch(client_handshake_traffic_secret, true /* handshake epoch */);
683 }
684
685 m_salt = derive_secret(handshake_secret, "derived", empty_hash());
686
687 m_state = State::HandshakeTraffic;
688}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
bool is_compatible_with(const Ciphersuite &cipher) const

References advance_read_epoch(), advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, is_compatible_with(), and Botan::TLS::Server.

Referenced by operator=().

◆ can_decrypt_application_traffic()

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

Indicates whether the appropriate secrets to decrypt application traffic are available

Definition at line 320 of file tls_cipher_state.cpp.

320 {
321 // TODO: when implementing early traffic (0-RTT) this will likely need
322 // to allow `State::EarlyTraffic`.
323
324 if(m_connection_side == Connection_Side::Client && m_state != State::ServerApplicationTraffic &&
325 m_state != State::Completed) {
326 return false;
327 }
328
329 if(m_connection_side == Connection_Side::Server && m_state != State::Completed) {
330 return false;
331 }
332
333 return has_read_epoch();
334}
virtual bool has_read_epoch() const =0

References Botan::TLS::Client, has_read_epoch(), and Botan::TLS::Server.

Referenced by deprotect_and_hydrate_content_type().

◆ can_encrypt_application_traffic()

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

Indicates whether the appropriate secrets to encrypt application traffic are available

Definition at line 304 of file tls_cipher_state.cpp.

304 {
305 // TODO: when implementing early traffic (0-RTT) this will likely need
306 // to allow `State::EarlyTraffic`.
307
308 if(m_connection_side == Connection_Side::Client && m_state != State::Completed) {
309 return false;
310 }
311
312 if(m_connection_side == Connection_Side::Server && m_state != State::ServerApplicationTraffic &&
313 m_state != State::Completed) {
314 return false;
315 }
316
317 return has_write_epoch();
318}
virtual bool has_write_epoch() const =0

References Botan::TLS::Client, has_write_epoch(), and Botan::TLS::Server.

Referenced by Botan::TLS::TLS_Cipher_State::protect_record().

◆ can_export_keys()

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

Indicates whether the appropriate secrets to export keys are available

Definition at line 217 of file tls_cipher_state.h.

217 {
218 return (m_state == State::EarlyTraffic || m_state == State::ServerApplicationTraffic ||
219 m_state == State::Completed) &&
220 !m_exporter_master_secret.empty();
221 }

Referenced by export_key().

◆ ciphersuite()

const Ciphersuite & Botan::TLS::Cipher_State::ciphersuite ( ) const
protectedinherited

Definition at line 716 of file tls_cipher_state.cpp.

716 {
717 BOTAN_ASSERT_NOMSG(m_ciphersuite.has_value());
718 return *m_ciphersuite;
719}

References BOTAN_ASSERT_NOMSG.

◆ clear_read_keys()

void Botan::TLS::TLS_Cipher_State::clear_read_keys ( )
overridevirtual

Remove handshake/traffic secrets for decrypting data from peer

Implements Botan::TLS::Cipher_State.

Definition at line 926 of file tls_cipher_state.cpp.

926 {
927 m_read_epoch.reset();
928}

Referenced by operator=().

◆ clear_write_keys()

void Botan::TLS::TLS_Cipher_State::clear_write_keys ( )
overridevirtual

Remove handshake/traffic secrets for encrypting data

Implements Botan::TLS::Cipher_State.

Definition at line 922 of file tls_cipher_state.cpp.

922 {
923 m_write_epoch.reset();
924}

Referenced by operator=().

◆ create_epoch()

Cipher_State::Epoch Botan::TLS::Cipher_State::create_epoch ( Cipher_Dir direction,
const secure_vector< uint8_t > & traffic_secret,
bool handshake_epoch ) const
protectedinherited

Definition at line 690 of file tls_cipher_state.cpp.

692 {
693 BOTAN_ASSERT_NONNULL(m_hash);
694 BOTAN_ASSERT_NOMSG(m_ciphersuite.has_value());
695
696 return {
697 .cipher = [&]() -> std::unique_ptr<AEAD_Mode> {
698 auto cipher = AEAD_Mode::create_or_throw(m_ciphersuite->cipher_algo(), direction);
699 cipher->set_key(hkdf_expand_label(traffic_secret, "key", {}, cipher->minimum_keylength()));
700 return cipher;
701 }(),
702 .iv = hkdf_expand_label(traffic_secret, "iv", {}, NONCE_LENGTH),
703 .sequence_number = 0,
704 .traffic_secret = traffic_secret,
705 .finished_key = [&]() -> std::optional<secure_vector<uint8_t>> {
706 if(handshake_epoch) {
707 // Key derivation for the MAC in the "Finished" handshake message
708 // as described in RFC 8446 4.4.4
709 return hkdf_expand_label(traffic_secret, "finished", {}, m_hash->output_length());
710 }
711 return {};
712 }(),
713 };
714}
static std::unique_ptr< AEAD_Mode > create_or_throw(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
Definition aead.cpp:51
secure_vector< uint8_t > hkdf_expand_label(const secure_vector< uint8_t > &secret, std::string_view label, const std::vector< uint8_t > &context, size_t length) const

References BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::AEAD_Mode::create_or_throw(), and hkdf_expand_label().

◆ decrypt_output_length()

size_t Botan::TLS::Cipher_State::decrypt_output_length ( size_t input_length) const
inherited
Returns
number of bytes needed to decrypt input_length bytes

Definition at line 267 of file tls_cipher_state.cpp.

267 {
268 // This assumes that the AEAD cipher's output length does not change
269 // between epochs.
270 return latest_read_epoch().cipher->output_length(input_length);
271}
virtual Epoch & latest_read_epoch()=0
std::unique_ptr< AEAD_Mode > cipher

References Botan::TLS::Cipher_State::Epoch::cipher, and latest_read_epoch().

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

◆ deprotect_and_hydrate_content_type()

void Botan::TLS::Cipher_State::deprotect_and_hydrate_content_type ( Epoch & epoch,
std::span< const uint8_t > header,
Record_Content & protected_record,
size_t incoming_record_size_limit ) const
protectedinherited

Definition at line 535 of file tls_cipher_state.cpp.

538 {
539 BOTAN_ASSERT_NOMSG(protected_record.sequence_number.has_value());
540 BOTAN_ASSERT_NONNULL(epoch.cipher);
541 BOTAN_ASSERT_NOMSG(protected_record.payload.size() <= MAX_CIPHERTEXT_SIZE_TLS13);
542
543 epoch.cipher->set_associated_data(header);
544 epoch.cipher->start(current_nonce(*protected_record.sequence_number, epoch.iv));
545 epoch.cipher->finish(protected_record.payload);
546
547 // RFC 8449 Section 4
548 // A TLS endpoint that receives a record larger than its advertised limit
549 // MUST generate a fatal "record_overflow" alert; a DTLS endpoint that
550 // receives a record larger than its advertised limit MAY either generate
551 // a fatal "record_overflow" alert or discard the record.
552 //
553 // We choose to generate a fatal alert for DTLS as well, given that this
554 // error is detected after decryption only.
555 if(protected_record.payload.size() > incoming_record_size_limit) {
556 throw TLS_Exception(Alert::RecordOverflow, "Received an encrypted record that exceeds maximum plaintext size");
557 }
558
559 // Remove record padding (RFC 9846 5.4). The TLSInnerPlaintext layout is
560 // content || content_type || zero_padding
561 //
562 // This is intentionally not constant time. Checking it in constant time
563 // requires scanning the entire record which significantly impacts receive
564 // throughput, and in any case doing so seems pointless since the same
565 // information (namely the length of the unpadded record) still leaks to the
566 // same side channels later on during processing, when the application
567 // actually receives and looks at the record.
568 const auto end_of_content = std::find_if(
569 protected_record.payload.crbegin(), protected_record.payload.crend(), [](uint8_t b) { return b != 0x00; });
570
571 // RFC 9846 5.4
572 // If a receiving implementation does not find a non-zero octet in the
573 // cleartext, it MUST terminate the connection with an
574 // "unexpected_message" alert.
575 if(end_of_content == protected_record.payload.crend()) {
576 throw TLS_Exception(Alert::UnexpectedMessage, "No content type found in encrypted record");
577 }
578
579 // hydrate the actual content type from TLSInnerPlaintext
580 protected_record.type = static_cast<Record_Type>(*end_of_content);
581
582 // Truncate to drop the content_type byte and padding. resize() on a
583 // vector of trivially-destructible elements is bookkeeping-only and
584 // does not allocate or iterate over the dropped suffix.
585 protected_record.payload.resize(protected_record.payload.size() -
586 std::distance(protected_record.payload.crbegin(), end_of_content) -
587 1 /* content type byte */);
588
589 // RFC 9846 4.5.3
590 // Once a side has sent its Finished message and has received and
591 // validated the Finished message from its peer, it may begin to send and
592 // receive Application Data over the connection.
593 //
594 // See also:
595 // * https://github.com/randombit/botan/security/advisories/GHSA-pxcj-9ppx-g86g (CVE-2026-34582)
596 if(protected_record.type == Record_Type::ApplicationData && !can_decrypt_application_traffic()) {
597 throw TLS_Exception(Alert::UnexpectedMessage, "Application data received before handshake completion");
598 }
599
600 // RFC 9846 5.4
601 // Implementations MUST NOT send Handshake and Alert records that have
602 // a zero-length TLSInnerPlaintext.content; if such a message is
603 // received, the receiving implementation MUST terminate the connection
604 // with an "unexpected_message" alert.
605 if(protected_record.payload.empty() && protected_record.type != Record_Type::ApplicationData) {
606 throw TLS_Exception(Alert::UnexpectedMessage, "Received a protected record with empty TLSInnerPlaintext content");
607 }
608}
bool can_decrypt_application_traffic() const
@ MAX_CIPHERTEXT_SIZE_TLS13
Definition tls_magic.h:47

References Botan::TLS::ApplicationData, BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, can_decrypt_application_traffic(), Botan::TLS::Cipher_State::Epoch::cipher, Botan::TLS::Cipher_State::Epoch::iv, Botan::TLS::MAX_CIPHERTEXT_SIZE_TLS13, Botan::TLS::Record_Content::payload, Botan::TLS::Record_Content::sequence_number, and Botan::TLS::Record_Content::type.

Referenced by Botan::TLS::TLS_Cipher_State::deprotect_record().

◆ deprotect_record()

Record Botan::TLS::TLS_Cipher_State::deprotect_record ( Record_TLS record,
size_t incoming_record_size_limit )
nodiscard

Deprotect a TLS record (RFC 9846 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.

Parameters
recordthe record to be deprotected in-place
incoming_record_size_limitthe maximum allowed size for the incoming record
Returns
the record payload and deprotected content type

Definition at line 845 of file tls_cipher_state.cpp.

845 {
846 BOTAN_ASSERT_NOMSG(m_read_epoch.has_value());
847 BOTAN_ARG_CHECK(record.type() == Record_Type::ApplicationData, "Record type must be ApplicationData");
848
849 // RFC 9846 5.2
850 // length: The length (in bytes) [...], which is the sum of the lengths of
851 // the content and the padding, plus one for the inner content
852 // type, plus any expansion added by the AEAD algorithm.
853 // [...]
854 // If the decryption fails, the receiver MUST terminate the connection
855 // with a "bad_record_mac" alert.
856 //
857 // If the protected record contains less bytes than the expected AEAD tag we
858 // can already fail early because the decryption will fail anyway.
859 if(record.payload().size() < m_read_epoch->cipher->minimum_final_size()) {
860 throw TLS_Exception(Alert::BadRecordMac, "incomplete record mac received");
861 }
862
863 // RFC 9846 6.2
864 // record_overflow: A TLSCiphertext record was received that had a length
865 // more than 2^14 + 256 bytes, or a record decrypted to a TLSPlaintext
866 // record with more than 214 bytes (or some other negotiated limit).
867 //
868 // RFC 8449 4.
869 // A TLS endpoint that receives a record larger than its advertised limit
870 // MUST generate a fatal "record_overflow" alert [...].
871 if(decrypt_output_length(record.payload().size()) > incoming_record_size_limit) {
872 throw TLS_Exception(Alert::RecordOverflow, "Received an encrypted record that exceeds maximum plaintext size");
873 }
874
875 // RFC 8446 5.3
876 // Sequence numbers MUST NOT wrap.
877 if(m_read_epoch->sequence_number == std::numeric_limits<uint64_t>::max()) {
878 throw Invalid_State("TLS read sequence number overflow");
879 }
880
881 auto result = Record_Content{
882 .type = Record_Type::Invalid,
883 .sequence_number = m_read_epoch->sequence_number++,
884 .payload = record.take_payload(),
885 };
886
887 deprotect_and_hydrate_content_type(*m_read_epoch, record.header(), result, incoming_record_size_limit);
888
889 // RFC 9846 5.
890 // An implementation [...] which receives a protected change_cipher_spec
891 // record MUST abort the handshake with an "unexpected_message" alert.
892 // [....]
893 // If a TLS implementation receives an unexpected record type, it MUST
894 // terminate the connection with an "unexpected_message" alert.
895 //
896 // RFC 9846 5.1
897 // enum {
898 // invalid(0),
899 // change_cipher_spec(20),
900 // alert(21),
901 // handshake(22),
902 // application_data(23),
903 // (255)
904 // } ContentType;
905 if(result.type != Record_Type::ApplicationData && //
906 result.type != Record_Type::Handshake && //
907 result.type != Record_Type::Alert) {
908 throw TLS_Exception(Alert::UnexpectedMessage, "protected TLS record type had unexpected value");
909 }
910
911 return annotate_record_type(std::move(result));
912}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
void deprotect_and_hydrate_content_type(Epoch &epoch, std::span< const uint8_t > header, Record_Content &protected_record, size_t incoming_record_size_limit) const
size_t decrypt_output_length(size_t input_length) const
Record annotate_record_type(Record_Content &&record)

References Botan::TLS::Alert, Botan::TLS::annotate_record_type(), Botan::TLS::ApplicationData, BOTAN_ARG_CHECK, BOTAN_ASSERT_NOMSG, Botan::TLS::Cipher_State::decrypt_output_length(), Botan::TLS::Cipher_State::deprotect_and_hydrate_content_type(), Botan::TLS::Handshake, Botan::TLS::Record_TLS::header(), Botan::TLS::Invalid, Botan::TLS::Record_TLS::payload(), Botan::TLS::Record_TLS::take_payload(), and Botan::TLS::Record_TLS::type().

Referenced by operator=().

◆ encrypt_output_length()

size_t Botan::TLS::Cipher_State::encrypt_output_length ( size_t input_length) const
inherited
Returns
number of bytes needed to encrypt input_length bytes

Definition at line 261 of file tls_cipher_state.cpp.

261 {
262 // This assumes that the AEAD cipher's output length does not change
263 // between epochs.
264 return latest_write_epoch().cipher->output_length(input_length);
265}
virtual Epoch & latest_write_epoch()=0

References Botan::TLS::Cipher_State::Epoch::cipher, and latest_write_epoch().

Referenced by operator=().

◆ export_key()

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

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
labela disambiguating label string
contexta per-association context value
lengththe length of the desired key in bytes
Returns
key of length bytes

Definition at line 443 of file tls_cipher_state.cpp.

443 {
445 BOTAN_ASSERT_NONNULL(m_hash);
446
447 m_hash->update(context);
448 const auto context_hash = m_hash->final_stdvec();
449 return hkdf_expand_label(
450 derive_secret(m_exporter_master_secret, label, empty_hash()), "exporter", context_hash, length);
451}

References BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, can_export_keys(), and hkdf_expand_label().

Referenced by operator=().

◆ finished_mac()

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

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

Definition at line 391 of file tls_cipher_state.cpp.

391 {
392 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Server || m_state == State::HandshakeTraffic);
393 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Client || m_state == State::ServerApplicationTraffic);
394 BOTAN_ASSERT_NONNULL(m_hash);
395
396 const auto& epoch = latest_write_epoch();
397 BOTAN_ASSERT_NOMSG(epoch.finished_key.has_value());
398
399 auto hmac = HMAC(m_hash->new_object());
400 hmac.set_key(*epoch.finished_key);
401 hmac.update(transcript_hash);
402 return hmac.final_stdvec();
403}

References BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::TLS::Client, latest_write_epoch(), 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
inherited

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

Definition at line 336 of file tls_cipher_state.cpp.

336 {
337 BOTAN_ASSERT_NONNULL(m_hash);
338 return m_hash->name();
339}

References BOTAN_ASSERT_NONNULL.

Referenced by is_compatible_with().

◆ hkdf_expand_label()

secure_vector< uint8_t > Botan::TLS::Cipher_State::hkdf_expand_label ( const secure_vector< uint8_t > & secret,
std::string_view label,
const std::vector< uint8_t > & context,
size_t length ) const
protectedinherited

HKDF-Expand-Label from RFC 8446 7.1

Definition at line 727 of file tls_cipher_state.cpp.

730 {
731 BOTAN_ASSERT_NONNULL(m_expand);
732 BOTAN_ARG_CHECK(length <= std::numeric_limits<uint16_t>::max(), "invalid length");
733 BOTAN_ARG_CHECK(context.size() <= 255, "context too large");
734 BOTAN_ARG_CHECK(m_expansion_label_prefix.size() + label.size() <= 255, "label too large");
735
736 const auto hkdf_label =
737 concat<secure_vector<uint8_t>>(store_be(static_cast<uint16_t>(length)),
738 store_be(static_cast<uint8_t>(m_expansion_label_prefix.size() + label.size())),
739 m_expansion_label_prefix,
740 as_span_of_bytes(label),
741 store_be(static_cast<uint8_t>(context.size())),
742 context);
743
744 // HKDF-Expand
745 return m_expand->derive_key(
746 length, secret, hkdf_label, std::vector<uint8_t>() /* just pleasing botan's interface */);
747}
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:59
constexpr auto concat(Rs &&... ranges)
Definition concat_util.h:95
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

References Botan::as_span_of_bytes(), BOTAN_ARG_CHECK, BOTAN_ASSERT_NONNULL, Botan::concat(), and Botan::store_be().

Referenced by create_epoch(), export_key(), update_read_keys(), and update_write_keys().

◆ init_with_psk()

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

Construct a Cipher_State from a Pre-Shared-Key.

Definition at line 160 of file tls_cipher_state.cpp.

164 {
165 auto cs = Cipher_State::create(side, flavor, prf_algo);
166 cs->advance_with_psk(type, std::move(psk));
167 return cs;
168}
secure_vector< uint8_t > psk(const Ticket_Nonce &nonce) const

References psk().

Referenced by operator=().

◆ init_with_server_hello()

std::unique_ptr< Cipher_State > Botan::TLS::Cipher_State::init_with_server_hello ( Connection_Side side,
TLS_Flavor flavor,
secure_vector< uint8_t > && shared_secret,
const Ciphersuite & cipher,
const Transcript_Hash & transcript_hash,
SecretLoggerFn secret_logger )
staticinherited

Construct a Cipher_State after receiving a server hello message.

Definition at line 147 of file tls_cipher_state.cpp.

152 {
153 auto cs = Cipher_State::create(side, flavor, cipher.prf_algo());
154 cs->set_secret_logger(std::move(secret_logger));
155 cs->advance_without_psk();
156 cs->advance_with_server_hello(cipher, std::move(shared_secret), transcript_hash);
157 return cs;
158}

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

Referenced by operator=().

◆ is_compatible_with()

bool Botan::TLS::Cipher_State::is_compatible_with ( const Ciphersuite & cipher) const
inherited
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 341 of file tls_cipher_state.cpp.

341 {
342 if(!cipher.usable_in_version(Protocol_Version::TLS_V13)) {
343 return false;
344 }
345
346 if(hash_algorithm() != cipher.prf_algo()) {
347 return false;
348 }
349
350 // Determine the canonical AEAD name utilized by the current cipher state.
351 // If the connection is half-closed in either direction, we use the AEAD from
352 // the still-active epoch. We assume that the AEAD of both directions is
353 // equal and does not change between epochs.
354 const auto our_aead_name = [&]() -> std::optional<std::string> {
355 if(has_write_epoch()) {
356 return latest_write_epoch().cipher->name();
357 } else if(has_read_epoch()) {
358 return latest_read_epoch().cipher->name();
359 } else {
360 return std::nullopt;
361 }
362 }();
363
364 // Compare canonical AEAD names rather than substring-matching cipher_algo
365 // against the AEAD's name(). starts_with() is both too permissive (an
366 // AES-128/CCM-8 instance starts with "AES-128/CCM" so it would accept the
367 // CCM-16 suite) and too restrictive (cipher_algo "AES-128/CCM(8)" does not
368 // prefix the canonical "AES-128/CCM(8,3)"). Re-instantiating the AEAD from
369 // cipher_algo yields the same canonical name() the suite would produce.
370 if(our_aead_name.has_value()) {
371 const auto ciphersuite_aead = AEAD_Mode::create(cipher.cipher_algo(), Cipher_Dir::Encryption);
372 if(!ciphersuite_aead || ciphersuite_aead->name() != *our_aead_name) {
373 return false;
374 }
375 }
376
377 return true;
378}
static std::unique_ptr< AEAD_Mode > create(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
Definition aead.cpp:61
std::string hash_algorithm() const

References Botan::TLS::Cipher_State::Epoch::cipher, Botan::TLS::Ciphersuite::cipher_algo(), Botan::AEAD_Mode::create(), Botan::Encryption, has_read_epoch(), has_write_epoch(), hash_algorithm(), latest_read_epoch(), latest_write_epoch(), Botan::TLS::Ciphersuite::prf_algo(), and Botan::TLS::Ciphersuite::usable_in_version().

Referenced by advance_with_server_hello().

◆ is_handshake_complete()

bool Botan::TLS::Cipher_State::is_handshake_complete ( ) const
inlineinherited

Indicates whether both peers' Finished messages were processed, i.e. the key schedule reached its final state.

Definition at line 227 of file tls_cipher_state.h.

227{ return m_state == State::Completed; }

◆ marshall_and_protect()

void Botan::TLS::Cipher_State::marshall_and_protect ( Epoch & epoch,
std::span< const uint8_t > header,
std::span< const uint8_t > payload,
Record_Type type,
size_t padding_bytes,
secure_vector< uint8_t > & out )
staticprotectedinherited

Marshalls the record (header || TLSInnerPlaintext), protects it in place and appends the result to out. The plaintext is copied into out exactly once; no intermediate buffers are allocated.

Definition at line 493 of file tls_cipher_state.cpp.

498 {
499 BOTAN_ASSERT_NONNULL(epoch.cipher);
500
501 const size_t record_offset = out.size();
502 const size_t content_offset = record_offset + header.size();
503 const size_t record_length = header.size() + protected_record_length(epoch, payload.size(), padding_bytes);
504 out.reserve(record_offset + record_length);
505
506 // RFC 9846 5.2
507 // struct {
508 // opaque content[TLSPlaintext.length];
509 // ContentType type;
510 // uint8 zeros[length_of_padding];
511 // } TLSInnerPlaintext;
512 //
513 // RFC 9846 5.4
514 // Implementations MUST set the padding octets to all zeros before
515 // encrypting.
516 //
517 // resize() value-initializes the new bytes, so the padding is already
518 // zeroed. The header and content are then copied with copy_mem(): for a
519 // vector with a non-standard allocator, insert() falls back to an
520 // element-wise copy loop in libstdc++ that is several times slower than
521 // a memcpy() for a full-sized record.
522 out.resize(content_offset + payload.size() + 1 /* type */ + padding_bytes);
523 copy_mem(std::span{out}.subspan(record_offset, header.size()), header);
524 copy_mem(std::span{out}.subspan(content_offset, payload.size()), payload);
525 out[content_offset + payload.size()] = to_underlying(type);
526
527 // Protect the TLSInnerPlaintext in place (everything after the header,
528 // which is the tail of the buffer) and append the AEAD tag.
529 epoch.cipher->set_associated_data(header);
530 epoch.cipher->start(current_nonce(epoch.sequence_number, epoch.iv));
531 epoch.cipher->finish(out, content_offset);
532 BOTAN_DEBUG_ASSERT(out.size() == record_offset + record_length);
533}
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:136
static size_t protected_record_length(Epoch &epoch, size_t payload_length, size_t padding_bytes)
auto to_underlying(T e) noexcept
Definition stl_util.h:158
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144

References BOTAN_ASSERT_NONNULL, BOTAN_DEBUG_ASSERT, Botan::TLS::Cipher_State::Epoch::cipher, Botan::copy_mem(), Botan::TLS::Cipher_State::Epoch::iv, protected_record_length(), Botan::TLS::Cipher_State::Epoch::sequence_number, and Botan::to_underlying().

Referenced by Botan::TLS::TLS_Cipher_State::protect_record().

◆ minimum_decryption_input_length()

size_t Botan::TLS::Cipher_State::minimum_decryption_input_length ( ) const
inherited
Returns
the minimum ciphertext length for decryption

Definition at line 273 of file tls_cipher_state.cpp.

273 {
274 // This assumes that the AEAD cipher's minimal final size does not change
275 // between epochs.
276 return latest_read_epoch().cipher->minimum_final_size();
277}

References Botan::TLS::Cipher_State::Epoch::cipher, and latest_read_epoch().

Referenced by operator=().

◆ must_expect_unprotected_alert_traffic()

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

Indicates whether unprotected Alert records are to be expected

Definition at line 279 of file tls_cipher_state.cpp.

279 {
280 // Client side:
281 // After successfully receiving a Server Hello we expect servers to send
282 // alerts as protected records only, just like they start protecting their
283 // handshake data at this point.
284 if(m_connection_side == Connection_Side::Client && m_state == State::EarlyTraffic) {
285 return true;
286 }
287
288 // Server side:
289 // Servers must expect clients to send unprotected alerts during the hand-
290 // shake. In particular, in the response to the server's first protected
291 // flight. We don't expect the client to send alerts protected under the
292 // early traffic secret.
293 //
294 // TODO: when implementing PSK and/or early data for the server, we might
295 // need to reconsider this decision.
296 if(m_connection_side == Connection_Side::Server &&
297 (m_state == State::HandshakeTraffic || m_state == State::ServerApplicationTraffic)) {
298 return true;
299 }
300
301 return false;
302}

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

◆ next_ticket_nonce()

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

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

426 {
427 BOTAN_STATE_CHECK(m_state == State::Completed);
428 if(m_ticket_nonce_exhausted) {
429 throw Botan::Invalid_State("ticket nonce pool exhausted");
430 }
431
432 auto retval = store_be<Ticket_Nonce>(m_ticket_nonce);
433
434 if(m_ticket_nonce == std::numeric_limits<decltype(m_ticket_nonce)>::max()) {
435 m_ticket_nonce_exhausted = true;
436 } else {
437 ++m_ticket_nonce;
438 }
439
440 return retval;
441}

References BOTAN_STATE_CHECK, and Botan::store_be().

Referenced by operator=().

◆ operator=() [1/2]

TLS_Cipher_State & Botan::TLS::TLS_Cipher_State::operator= ( const TLS_Cipher_State & )
delete

References TLS_Cipher_State().

◆ operator=() [2/2]

TLS_Cipher_State & Botan::TLS::TLS_Cipher_State::operator= ( TLS_Cipher_State && )
delete

◆ protect_record()

void Botan::TLS::TLS_Cipher_State::protect_record ( Record_Type type,
std::span< const uint8_t > payload,
size_t padding_bytes,
secure_vector< uint8_t > & out )

Protect a TLS record (RFC 9846 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.

Parameters
typethe record type to be protected
payloadthe record plaintext to be protected
padding_bytesthe number of padding zero-bytes to be added
outthe marshalled and protected record (to be sent on the wire) is appended to this buffer

Definition at line 811 of file tls_cipher_state.cpp.

814 {
815 BOTAN_ASSERT_NOMSG(m_write_epoch.has_value());
817 "Application data must not be encrypted before handshake completion");
818
819 // RFC 8446 5.3
820 // Sequence numbers MUST NOT wrap.
821 if(m_write_epoch->sequence_number == std::numeric_limits<uint64_t>::max()) {
822 throw Invalid_State("TLS write sequence number overflow");
823 }
824
825 // RFC 9846 5.2
826 // opaque_type: The outer opaque_type field of a TLSCiphertext record is
827 // always set to the value 23 (application_data) [...]
828 // legacy_record_version: [...] is always 0x0303. TLS 1.3 TLSCiphertexts
829 // are not generated until after TLS 1.3 has been
830 // negotiated, so there are no historical
831 // compatibility concerns [...].
832 // length: [...] of the following TLSCiphertext.encrypted_record, which is
833 // the sum of the lengths of the content and the padding, plus one
834 // for the inner content type, plus any expansion added by the
835 // AEAD algorithm.
836 const auto header = Record_TLS::serialize_header(
838 Protocol_Version::TLS_V12 /* = 0x0303 */,
839 checked_cast_to<uint16_t>(protected_record_length(*m_write_epoch, plaintext.size(), padding_bytes)));
840
841 marshall_and_protect(*m_write_epoch, header, plaintext, type, padding_bytes, out);
842 ++m_write_epoch->sequence_number;
843}
#define BOTAN_STATE_CHECK_MSG(expr, msg)
Definition assert.h:59
bool can_encrypt_application_traffic() const
static void marshall_and_protect(Epoch &epoch, std::span< const uint8_t > header, std::span< const uint8_t > payload, Record_Type type, size_t padding_bytes, secure_vector< uint8_t > &out)
static std::array< uint8_t, TLS_HEADER_SIZE > serialize_header(Record_Type type, Protocol_Version legacy_version, uint16_t payload_length)
constexpr RT checked_cast_to(AT i)
Definition int_utils.h:104

References Botan::TLS::ApplicationData, BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK_MSG, Botan::TLS::Cipher_State::can_encrypt_application_traffic(), Botan::checked_cast_to(), Botan::TLS::Cipher_State::marshall_and_protect(), Botan::TLS::Cipher_State::protected_record_length(), and Botan::TLS::Record_TLS::serialize_header().

Referenced by operator=().

◆ protected_record_length()

size_t Botan::TLS::Cipher_State::protected_record_length ( Epoch & epoch,
size_t payload_length,
size_t padding_bytes )
staticprotectedinherited

Definition at line 482 of file tls_cipher_state.cpp.

482 {
483 BOTAN_ASSERT_NONNULL(epoch.cipher);
484
485 // RFC 8446 5.2
486 // type: The TLSPlaintext.type value containing the content type of the record.
487 constexpr size_t content_type_tag_length = 1;
488
489 const size_t plaintext_length = payload_length + content_type_tag_length + padding_bytes;
490 return epoch.cipher->output_length(plaintext_length);
491}

References BOTAN_ASSERT_NONNULL, and Botan::TLS::Cipher_State::Epoch::cipher.

Referenced by marshall_and_protect(), and Botan::TLS::TLS_Cipher_State::protect_record().

◆ psk()

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

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

Definition at line 420 of file tls_cipher_state.cpp.

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

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
inherited

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

381 {
382 BOTAN_ASSERT_NOMSG(m_state == State::PskBinder);
383 BOTAN_ASSERT_NONNULL(m_hash);
384
385 auto hmac = HMAC(m_hash->new_object());
386 hmac.set_key(m_binder_key);
387 hmac.update(transcript_hash_with_truncated_client_hello);
388 return hmac.final_stdvec();
389}

References BOTAN_ASSERT_NOMSG, and BOTAN_ASSERT_NONNULL.

Referenced by operator=().

◆ records_decrypted_with_current_key()

uint64_t Botan::TLS::Cipher_State::records_decrypted_with_current_key ( ) const
inherited
Returns
the number of records decrypted with the current read key

Definition at line 802 of file tls_cipher_state.cpp.

References latest_read_epoch(), and Botan::TLS::Cipher_State::Epoch::sequence_number.

◆ records_encrypted_with_current_key()

uint64_t Botan::TLS::Cipher_State::records_encrypted_with_current_key ( ) const
inherited
Returns
the number of records encrypted with the current write key

Definition at line 798 of file tls_cipher_state.cpp.

798 {
800}

References latest_write_epoch(), and Botan::TLS::Cipher_State::Epoch::sequence_number.

◆ set_secret_logger()

void Botan::TLS::Cipher_State::set_secret_logger ( SecretLoggerFn secret_logger)
inlineinherited

Register an optional callback function to extract secrets bound for a SSLKEYLOGFILE. See SSLKEYLOGFILE RFC 9850 for details.

Definition at line 300 of file tls_cipher_state.h.

300{ m_secret_logger = std::move(secret_logger); }

◆ update_read_keys()

void Botan::TLS::Cipher_State::update_read_keys ( )
inherited

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

762 {
763 BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic || m_state == State::Completed);
764 BOTAN_ASSERT_NONNULL(m_hash);
765
766 const auto& epoch = latest_read_epoch();
767
768 const auto new_read_application_traffic_secret =
769 hkdf_expand_label(epoch.traffic_secret, "traffic upd", {}, m_hash->output_length());
770
771 const auto secret_label = fmt("{}_TRAFFIC_SECRET_{}",
772 m_connection_side == Connection_Side::Server ? "CLIENT" : "SERVER",
773 ++m_read_key_update_count);
774
775 advance_read_epoch(new_read_application_traffic_secret);
776 maybe_log_secret(secret_label, new_read_application_traffic_secret);
777}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References advance_read_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::fmt(), hkdf_expand_label(), latest_read_epoch(), and Botan::TLS::Server.

◆ update_write_keys()

void Botan::TLS::Cipher_State::update_write_keys ( )
inherited

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

779 {
780 BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic || m_state == State::Completed);
781 BOTAN_ASSERT_NONNULL(m_hash);
782
783 const auto& epoch = latest_write_epoch();
784
785 const auto new_write_application_traffic_secret =
786 hkdf_expand_label(epoch.traffic_secret, "traffic upd", {}, m_hash->output_length());
787
788 const auto secret_label = fmt("{}_TRAFFIC_SECRET_{}",
789 m_connection_side == Connection_Side::Server ? "SERVER" : "CLIENT",
790 ++m_write_key_update_count);
791
792 // Our KeyUpdate was already sent, so install the new keys before a key log
793 // callback can throw; the application may continue using the channel
794 advance_write_epoch(new_write_application_traffic_secret);
795 maybe_log_secret(secret_label, new_write_application_traffic_secret);
796}

References advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::fmt(), hkdf_expand_label(), latest_write_epoch(), 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
inherited

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

Definition at line 405 of file tls_cipher_state.cpp.

406 {
407 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Server || m_state == State::ServerApplicationTraffic);
408 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Client || m_state == State::HandshakeTraffic);
409 BOTAN_ASSERT_NONNULL(m_hash);
410
411 const auto& epoch = latest_read_epoch();
412 BOTAN_ASSERT_NOMSG(epoch.finished_key.has_value());
413
414 auto hmac = HMAC(m_hash->new_object());
415 hmac.set_key(*epoch.finished_key);
416 hmac.update(transcript_hash);
417 return hmac.verify_mac(peer_mac);
418}

References BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::TLS::Client, latest_read_epoch(), and Botan::TLS::Server.

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


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