|
Botan 3.14.1
Crypto and TLS for C&
|
#include <tls_cipher_state.h>
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) |
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.
|
inherited |
Definition at line 97 of file tls_cipher_state.h.
|
stronginherited |
| Enumerator | |
|---|---|
| Resumption | |
| External | |
| Imported | |
Definition at line 73 of file tls_cipher_state.h.
| 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.
References Botan::TLS::Cipher_State::Cipher_State().
Referenced by operator=(), operator=(), TLS_Cipher_State(), and TLS_Cipher_State().
|
overridedefault |
|
delete |
References TLS_Cipher_State().
|
delete |
References TLS_Cipher_State().
|
inherited |
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=().
|
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.
References BOTAN_ASSERT_NOMSG, and Botan::zap().
Referenced by operator=().
|
inherited |
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=().
|
inherited |
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=().
|
inherited |
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().
|
inherited |
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().
|
inlineinherited |
Indicates whether the appropriate secrets to export keys are available
Definition at line 217 of file tls_cipher_state.h.
Referenced by export_key().
|
protectedinherited |
Definition at line 716 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG.
|
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.
Referenced by operator=().
|
overridevirtual |
Remove handshake/traffic secrets for encrypting data
Implements Botan::TLS::Cipher_State.
Definition at line 922 of file tls_cipher_state.cpp.
Referenced by operator=().
|
protectedinherited |
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().
|
inherited |
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=().
|
protectedinherited |
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().
|
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.
| record | the record to be deprotected in-place |
| incoming_record_size_limit | the maximum allowed size for the incoming record |
Definition at line 845 of file tls_cipher_state.cpp.
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=().
|
inherited |
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=().
|
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 [...].
| 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=().
|
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.
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=().
|
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.
References BOTAN_ASSERT_NONNULL.
Referenced by is_compatible_with().
|
protectedinherited |
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().
|
staticinherited |
Construct a Cipher_State from a Pre-Shared-Key.
Definition at line 160 of file tls_cipher_state.cpp.
References psk().
Referenced by operator=().
|
staticinherited |
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=().
|
inherited |
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().
|
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.
|
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.
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().
|
inherited |
Definition at line 273 of file tls_cipher_state.cpp.
References Botan::TLS::Cipher_State::Epoch::cipher, and latest_read_epoch().
Referenced by operator=().
|
inherited |
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.
|
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.
References BOTAN_STATE_CHECK, and Botan::store_be().
Referenced by operator=().
|
delete |
References TLS_Cipher_State().
|
delete |
References clear_read_keys(), clear_write_keys(), deprotect_record(), protect_record(), and TLS_Cipher_State().
| 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.
| type | the record type to be protected |
| payload | the record plaintext to be protected |
| padding_bytes | the number of padding zero-bytes to be added |
| out | the 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.
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=().
|
staticprotectedinherited |
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().
|
inherited |
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=().
|
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.
References BOTAN_ASSERT_NOMSG, and BOTAN_ASSERT_NONNULL.
Referenced by operator=().
|
inherited |
Definition at line 802 of file tls_cipher_state.cpp.
References latest_read_epoch(), and Botan::TLS::Cipher_State::Epoch::sequence_number.
|
inherited |
Definition at line 798 of file tls_cipher_state.cpp.
References latest_write_epoch(), and Botan::TLS::Cipher_State::Epoch::sequence_number.
|
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.
|
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.
References advance_read_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::fmt(), hkdf_expand_label(), latest_read_epoch(), and Botan::TLS::Server.
|
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.
References advance_write_epoch(), BOTAN_ASSERT_NOMSG, BOTAN_ASSERT_NONNULL, Botan::fmt(), hkdf_expand_label(), latest_write_epoch(), and Botan::TLS::Server.
|
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.
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().