|
Botan 3.14.1
Crypto and TLS for C&
|
#include <tls_cipher_state.h>
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) |
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.
| using Botan::TLS::Cipher_State::ExpansionLabelPrefix = std::array<uint8_t, 6> |
Definition at line 97 of file tls_cipher_state.h.
|
strong |
| Enumerator | |
|---|---|
| Resumption | |
| External | |
| Imported | |
Definition at line 73 of file tls_cipher_state.h.
|
virtualdefault |
|
delete |
References Cipher_State().
Referenced by Cipher_State(), Cipher_State(), operator=(), operator=(), and Botan::TLS::TLS_Cipher_State::TLS_Cipher_State().
|
delete |
References Cipher_State().
|
protected |
| whoami | whether we play the Server or Client |
| hash_function | the negotiated hash function to be used |
| expand_prefix | the prefix to be used for HKDF-Expand-Label |
Definition at line 133 of file tls_cipher_state.cpp.
|
protectedpure virtual |
| 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.
References advance_read_epoch(), advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::TLS::Server, and Botan::zap().
Referenced by operator=().
| 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.
References BOTAN_ASSERT_NOMSG, and Botan::zap().
Referenced by operator=().
| 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.
References advance_read_epoch(), advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, and Botan::TLS::Server.
Referenced by operator=().
| 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.
References advance_read_epoch(), advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, is_compatible_with(), and Botan::TLS::Server.
Referenced by operator=().
|
protectedpure virtual |
| 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.
References Botan::TLS::Client, has_read_epoch(), and Botan::TLS::Server.
Referenced by deprotect_and_hydrate_content_type().
| 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.
References Botan::TLS::Client, has_write_epoch(), and Botan::TLS::Server.
Referenced by Botan::TLS::TLS_Cipher_State::protect_record().
|
inline |
Indicates whether the appropriate secrets to export keys are available
Definition at line 217 of file tls_cipher_state.h.
Referenced by export_key().
|
protected |
Definition at line 716 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG.
|
pure virtual |
Remove handshake/traffic secrets for decrypting data from peer
Implemented in Botan::TLS::TLS_Cipher_State.
|
pure virtual |
Remove handshake/traffic secrets for encrypting data
Implemented in Botan::TLS::TLS_Cipher_State.
|
protected |
Definition at line 690 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::AEAD_Mode::create_or_throw(), and hkdf_expand_label().
| size_t Botan::TLS::Cipher_State::decrypt_output_length | ( | size_t | input_length | ) | const |
input_length bytes Definition at line 267 of file tls_cipher_state.cpp.
References Botan::TLS::Cipher_State::Epoch::cipher, and latest_read_epoch().
Referenced by Botan::TLS::TLS_Cipher_State::deprotect_record(), and operator=().
|
protected |
Definition at line 535 of file tls_cipher_state.cpp.
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().
| size_t Botan::TLS::Cipher_State::encrypt_output_length | ( | size_t | input_length | ) | const |
input_length bytes Definition at line 261 of file tls_cipher_state.cpp.
References Botan::TLS::Cipher_State::Epoch::cipher, and latest_write_epoch().
Referenced by operator=().
| 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 [...].
| label | a disambiguating label string |
| context | a per-association context value |
| length | the length of the desired key in bytes |
Definition at line 443 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, can_export_keys(), and hkdf_expand_label().
Referenced by operator=().
| 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.
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=().
|
protectedpure virtual |
Referenced by can_decrypt_application_traffic(), and is_compatible_with().
|
protectedpure virtual |
Referenced by can_encrypt_application_traffic(), and is_compatible_with().
| 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.
References BOTAN_ASSERT_NONNULL.
Referenced by is_compatible_with().
|
protected |
HKDF-Expand-Label from RFC 8446 7.1
Definition at line 727 of file tls_cipher_state.cpp.
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().
|
static |
Construct a Cipher_State from a Pre-Shared-Key.
Definition at line 160 of file tls_cipher_state.cpp.
References psk().
Referenced by operator=().
|
static |
Construct a Cipher_State after receiving a server hello message.
Definition at line 147 of file tls_cipher_state.cpp.
References Botan::TLS::Ciphersuite::prf_algo().
Referenced by operator=().
| bool Botan::TLS::Cipher_State::is_compatible_with | ( | const Ciphersuite & | cipher | ) | const |
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.
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().
|
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.
|
protectedpure virtual |
|
protectedpure virtual |
|
protectedpure virtual |
|
protectedpure virtual |
|
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.
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().
| size_t Botan::TLS::Cipher_State::minimum_decryption_input_length | ( | ) | const |
Definition at line 273 of file tls_cipher_state.cpp.
References Botan::TLS::Cipher_State::Epoch::cipher, and latest_read_epoch().
Referenced by operator=().
| 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.
References Botan::TLS::Client, and Botan::TLS::Server.
| 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.
References BOTAN_STATE_CHECK, and Botan::store_be().
Referenced by operator=().
|
delete |
References advance_with_client_finished(), advance_with_client_hello(), advance_with_server_finished(), advance_with_server_hello(), Cipher_State(), decrypt_output_length(), encrypt_output_length(), export_key(), finished_mac(), init_with_psk(), init_with_server_hello(), minimum_decryption_input_length(), next_ticket_nonce(), psk(), psk_binder_mac(), and verify_peer_finished_mac().
|
delete |
References Cipher_State().
|
staticprotected |
Definition at line 482 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NONNULL, and Botan::TLS::Cipher_State::Epoch::cipher.
Referenced by marshall_and_protect(), and Botan::TLS::TLS_Cipher_State::protect_record().
| 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.
References BOTAN_ASSERT_NOMSG, and Botan::detail::Strong_Base< T >::get().
Referenced by init_with_psk(), and operator=().
| 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.
References BOTAN_ASSERT_NOMSG, and BOTAN_ASSERT_NONNULL.
Referenced by operator=().
| uint64_t Botan::TLS::Cipher_State::records_decrypted_with_current_key | ( | ) | const |
Definition at line 802 of file tls_cipher_state.cpp.
References latest_read_epoch(), and Botan::TLS::Cipher_State::Epoch::sequence_number.
| uint64_t Botan::TLS::Cipher_State::records_encrypted_with_current_key | ( | ) | const |
Definition at line 798 of file tls_cipher_state.cpp.
References latest_write_epoch(), and Botan::TLS::Cipher_State::Epoch::sequence_number.
|
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.
| 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.
References advance_read_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::fmt(), hkdf_expand_label(), latest_read_epoch(), and Botan::TLS::Server.
| 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.
References advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::fmt(), hkdf_expand_label(), latest_write_epoch(), and Botan::TLS::Server.
| 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.
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().