Botan 3.3.0
Crypto and TLS for C&
|
#include <tls_cipher_state.h>
Public Types | |
enum class | PSK_Type { Resumption , External } |
Public Member Functions | |
void | advance_with_client_finished (const Transcript_Hash &transcript_hash) |
void | advance_with_client_hello (const Transcript_Hash &transcript_hash) |
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 () |
void | clear_write_keys () |
size_t | decrypt_output_length (size_t input_length) const |
uint64_t | decrypt_record_fragment (const std::vector< uint8_t > &header, secure_vector< uint8_t > &encrypted_fragment) |
size_t | encrypt_output_length (size_t input_length) const |
uint64_t | encrypt_record_fragment (const std::vector< uint8_t > &header, secure_vector< uint8_t > &fragment) |
secure_vector< uint8_t > | export_key (std::string_view label, std::string_view context, size_t length) const |
std::vector< uint8_t > | finished_mac (const Transcript_Hash &transcript_hash) const |
std::string | hash_algorithm () const |
bool | is_compatible_with (const Ciphersuite &cipher) const |
size_t | minimum_decryption_input_length () const |
bool | must_expect_unprotected_alert_traffic () const |
Ticket_Nonce | next_ticket_nonce () |
secure_vector< uint8_t > | psk (const Ticket_Nonce &nonce) const |
std::vector< uint8_t > | psk_binder_mac (const Transcript_Hash &transcript_hash_with_truncated_client_hello) const |
void | update_read_keys () |
void | update_write_keys () |
bool | verify_peer_finished_mac (const Transcript_Hash &transcript_hash, const std::vector< uint8_t > &peer_mac) const |
~Cipher_State () | |
Static Public Member Functions | |
static std::unique_ptr< Cipher_State > | init_with_psk (Connection_Side side, PSK_Type type, secure_vector< uint8_t > &&psk, std::string_view prf_algo) |
static std::unique_ptr< Cipher_State > | init_with_server_hello (Connection_Side side, secure_vector< uint8_t > &&shared_secret, const Ciphersuite &cipher, const Transcript_Hash &transcript_hash) |
This class implements the key schedule for TLS 1.3 as described in RFC 8446 7.1.
Internally, it reflects the state machine pictured in the same RFC section. It provides the following entry points and state advancement methods that each facilitate certain cryptographic functionality:
While encrypting and decrypting records (RFC 8446 5.2) Cipher_State internally keeps track of the current sequence numbers (RFC 8446 5.3) to calculate the correct Per-Record Nonce. Sequence numbers are reset appropriately, whenever traffic secrets change.
Handshake finished MAC calculation and verification is described in RFC 8446 4.4.4.
PSKs calculation is described in RFC 8446 4.6.1.
Definition at line 61 of file tls_cipher_state.h.
|
strong |
Enumerator | |
---|---|
Resumption | |
External |
Definition at line 63 of file tls_cipher_state.h.
|
default |
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 183 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, Botan::TLS::Server, and Botan::zap().
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 138 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, and Botan::zap().
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 157 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, and Botan::TLS::Server.
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 461 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, Botan::TLS::Ciphersuite::cipher_algo(), Botan::AEAD_Mode::create_or_throw(), Botan::Decryption, Botan::Encryption, is_compatible_with(), and Botan::TLS::Server.
bool Botan::TLS::Cipher_State::can_decrypt_application_traffic | ( | ) | const |
Indicates whether the appropriate secrets to decrypt application traffic are available
Definition at line 307 of file tls_cipher_state.cpp.
References Botan::TLS::Client, and Botan::TLS::Server.
bool Botan::TLS::Cipher_State::can_encrypt_application_traffic | ( | ) | const |
Indicates whether the appropriate secrets to encrypt application traffic are available
Definition at line 291 of file tls_cipher_state.cpp.
References Botan::TLS::Client, and Botan::TLS::Server.
|
inline |
Indicates whether the appropriate secrets to export keys are available
Definition at line 195 of file tls_cipher_state.h.
Referenced by export_key().
void Botan::TLS::Cipher_State::clear_read_keys | ( | ) |
Remove handshake/traffic secrets for decrypting data from peer
Definition at line 584 of file tls_cipher_state.cpp.
References Botan::zap().
void Botan::TLS::Cipher_State::clear_write_keys | ( | ) |
Remove handshake/traffic secrets for encrypting data
Definition at line 590 of file tls_cipher_state.cpp.
References Botan::zap().
size_t Botan::TLS::Cipher_State::decrypt_output_length | ( | size_t | input_length | ) | const |
input_length
bytes Definition at line 256 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NONNULL.
Referenced by Botan::TLS::Record_Layer::next_record().
uint64_t Botan::TLS::Cipher_State::decrypt_record_fragment | ( | const std::vector< uint8_t > & | header, |
secure_vector< uint8_t > & | encrypted_fragment ) |
Decrypt a TLS record fragment (RFC 8446 5.2 – TLSCiphertext.encrypted_record) using the currently available traffic secret keys and the current sequence number. This will internally increment the sequence number. Hence, multiple calls with the same input will not produce the same result.
Definition at line 237 of file tls_cipher_state.cpp.
References BOTAN_ARG_CHECK, and BOTAN_ASSERT_NONNULL.
Referenced by Botan::TLS::Record_Layer::next_record().
size_t Botan::TLS::Cipher_State::encrypt_output_length | ( | size_t | input_length | ) | const |
input_length
bytes Definition at line 251 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NONNULL.
Referenced by Botan::TLS::Record_Layer::prepare_records().
uint64_t Botan::TLS::Cipher_State::encrypt_record_fragment | ( | const std::vector< uint8_t > & | header, |
secure_vector< uint8_t > & | fragment ) |
Encrypt a TLS record fragment (RFC 8446 5.2 – TLSInnerPlaintext) using the currently available traffic secret keys and the current sequence number. This will internally increment the sequence number. Hence, multiple calls with the same input will not produce the same result.
Definition at line 226 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NONNULL.
Referenced by Botan::TLS::Record_Layer::prepare_records().
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 400 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, and can_export_keys().
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 359 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, Botan::TLS::Client, and Botan::TLS::Server.
Referenced by Botan::TLS::Finished_13::Finished_13().
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 323 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NONNULL.
Referenced by is_compatible_with().
|
static |
Construct a Cipher_State from a Pre-Shared-Key.
Definition at line 129 of file tls_cipher_state.cpp.
References psk().
|
static |
Construct a Cipher_State after receiving a server hello message.
Definition at line 119 of file tls_cipher_state.cpp.
References Botan::TLS::Ciphersuite::prf_algo().
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 328 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, Botan::TLS::Ciphersuite::cipher_algo(), hash_algorithm(), Botan::TLS::Ciphersuite::prf_algo(), and Botan::TLS::Ciphersuite::usable_in_version().
Referenced by advance_with_server_hello().
size_t Botan::TLS::Cipher_State::minimum_decryption_input_length | ( | ) | const |
Definition at line 261 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NONNULL.
Referenced by Botan::TLS::Record_Layer::next_record().
bool Botan::TLS::Cipher_State::must_expect_unprotected_alert_traffic | ( | ) | const |
Indicates whether unprotected Alert records are to be expected
Definition at line 266 of file tls_cipher_state.cpp.
References Botan::TLS::Client, and Botan::TLS::Server.
Referenced by Botan::TLS::Record_Layer::next_record().
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 388 of file tls_cipher_state.cpp.
References BOTAN_STATE_CHECK, and Botan::store_be().
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 382 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, and Botan::detail::Strong_Base< T >::get().
Referenced by init_with_psk().
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 349 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG.
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 567 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG.
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 576 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG.
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 370 of file tls_cipher_state.cpp.
References BOTAN_ASSERT_NOMSG, Botan::TLS::Client, and Botan::TLS::Server.
Referenced by Botan::TLS::Finished_13::verify().