Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::Cipher_State Class Referenceabstract

#include <tls_cipher_state.h>

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

Classes

struct  Epoch

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
 Cipher_State (Cipher_State &&other)=delete
 Cipher_State (const Cipher_State &other)=delete
virtual void clear_read_keys ()=0
virtual void clear_write_keys ()=0
size_t decrypt_output_length (size_t input_length) const
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 ()
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
uint64_t records_decrypted_with_current_key () const
uint64_t records_encrypted_with_current_key () const
void set_secret_logger (SecretLoggerFn secret_logger)
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
virtual ~Cipher_State ()

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

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
 Cipher_State (Connection_Side whoami, std::string_view hash_function, ExpansionLabelPrefix expand_prefix)
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
virtual bool has_read_epoch () const =0
virtual bool has_write_epoch () const =0
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
virtual const Epoch & latest_read_epoch () const =0
virtual Epoch & latest_read_epoch ()=0
virtual const Epoch & latest_write_epoch () const =0
virtual Epoch & latest_write_epoch ()=0

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

This class implements the key schedule for (D)TLS 1.3 as described in RFC 9846 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:

This is an abstract base class that implements the key schedule and leaves the management of the resulting traffic epochs (as well as record protection) to concrete subclasses for TLS and DTLS.

While encrypting and decrypting records (RFC 9846 5.2) the concrete subclasses internally keep track of the current sequence numbers (RFC 9846 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 9846 4.5.3. PSKs calculation is described in RFC 9846 4.7.1

Definition at line 71 of file tls_cipher_state.h.

Member Typedef Documentation

◆ ExpansionLabelPrefix

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

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

◆ ~Cipher_State()

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

◆ Cipher_State() [1/3]

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

◆ Cipher_State() [2/3]

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

References Cipher_State().

◆ Cipher_State() [3/3]

Botan::TLS::Cipher_State::Cipher_State ( Connection_Side whoami,
std::string_view hash_function,
ExpansionLabelPrefix expand_prefix )
protected
Parameters
whoamiwhether we play the Server or Client
hash_functionthe negotiated hash function to be used
expand_prefixthe prefix to be used for HKDF-Expand-Label

Definition at line 133 of file tls_cipher_state.cpp.

135 :
136 m_state(State::Uninitialized),
137 m_connection_side(whoami),
138 m_extract(std::make_unique<HKDF_Extract>(create_hmac(hash_function))),
139 m_expand(std::make_unique<HKDF_Expand>(create_hmac(hash_function))),
140 m_hash(HashFunction::create_or_throw(hash_function)),
141 m_expansion_label_prefix(expansion_label_prefix),
142 m_salt(m_hash->output_length(), 0x00),
143 m_ticket_nonce(0) {}
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311

Member Function Documentation

◆ advance_read_epoch()

virtual void Botan::TLS::Cipher_State::advance_read_epoch ( const secure_vector< uint8_t > & traffic_secret,
bool handshake_epoch = false )
protectedpure virtual

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

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)

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 )

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

◆ advance_write_epoch()

virtual void Botan::TLS::Cipher_State::advance_write_epoch ( const secure_vector< uint8_t > & traffic_secret,
bool handshake_epoch = false )
protectedpure virtual

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

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
inline

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
protected

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

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

Remove handshake/traffic secrets for decrypting data from peer

Implemented in Botan::TLS::TLS_Cipher_State.

◆ clear_write_keys()

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

Remove handshake/traffic secrets for encrypting data

Implemented in Botan::TLS::TLS_Cipher_State.

◆ 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
protected

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

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

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

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

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

◆ has_read_epoch()

virtual bool Botan::TLS::Cipher_State::has_read_epoch ( ) const
protectedpure virtual

◆ has_write_epoch()

virtual bool Botan::TLS::Cipher_State::has_write_epoch ( ) const
protectedpure virtual

◆ 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 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
protected

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}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
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 )
static

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

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

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; }

◆ latest_read_epoch() [1/2]

virtual const Epoch & Botan::TLS::Cipher_State::latest_read_epoch ( ) const
protectedpure virtual

◆ latest_read_epoch() [2/2]

virtual Epoch & Botan::TLS::Cipher_State::latest_read_epoch ( )
protectedpure virtual

◆ latest_write_epoch() [1/2]

virtual const Epoch & Botan::TLS::Cipher_State::latest_write_epoch ( ) const
protectedpure virtual

◆ latest_write_epoch() [2/2]

virtual Epoch & Botan::TLS::Cipher_State::latest_write_epoch ( )
protectedpure virtual

◆ 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 )
staticprotected

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

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

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]

◆ operator=() [2/2]

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

References Cipher_State().

◆ protected_record_length()

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

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

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

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

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

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

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

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: