Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::Transcript_Hash_State Class Reference

#include <tls_transcript_hash_13.h>

Public Member Functions

Transcript_Hash_State clone () const
const Transcript_Hash & current () const
Transcript_Hash_State & operator= (const Transcript_Hash_State &)=delete
Transcript_Hash_State & operator= (Transcript_Hash_State &&other) noexcept
const Transcript_Hash & previous () const
void set_algorithm (std::string_view algo_spec)
 Transcript_Hash_State (TLS_Flavor flavor)
 Transcript_Hash_State (TLS_Flavor flavor, std::string_view algo_spec)
 Transcript_Hash_State (Transcript_Hash_State &&other) noexcept
const Transcript_Hash & truncated () const
void update (HandshakeProtocolHeader tls_message_header, StrongSpan< const SerializedHandshakeMessage > serialized_message)
 ~Transcript_Hash_State ()

Static Public Member Functions

static Transcript_Hash_State recreate_after_hello_retry_request (std::string_view algo_spec, const Transcript_Hash_State &prev_transcript_hash_state)

Detailed Description

Wraps the behaviour of the TLS 1.3 transcript hash as described in RFC 8446 4.4.1. Particularly, it hides the complexity that the utilized hash algorithm might become evident only after receiving a server hello message.

Definition at line 33 of file tls_transcript_hash_13.h.

Constructor & Destructor Documentation

◆ Transcript_Hash_State() [1/3]

Botan::TLS::Transcript_Hash_State::Transcript_Hash_State ( TLS_Flavor flavor)
explicit

◆ Transcript_Hash_State() [2/3]

Botan::TLS::Transcript_Hash_State::Transcript_Hash_State ( TLS_Flavor flavor,
std::string_view algo_spec )

Definition at line 23 of file tls_transcript_hash_13.cpp.

23 :
24 Transcript_Hash_State(flavor) {
25 set_algorithm(algo_spec);
26}
void set_algorithm(std::string_view algo_spec)

References set_algorithm(), and Transcript_Hash_State().

◆ ~Transcript_Hash_State()

Botan::TLS::Transcript_Hash_State::~Transcript_Hash_State ( )
default

◆ Transcript_Hash_State() [3/3]

Botan::TLS::Transcript_Hash_State::Transcript_Hash_State ( Transcript_Hash_State && other)
defaultnoexcept

Member Function Documentation

◆ clone()

Transcript_Hash_State Botan::TLS::Transcript_Hash_State::clone ( ) const

Definition at line 208 of file tls_transcript_hash_13.cpp.

208 {
209 return *this;
210}

References Transcript_Hash_State().

Referenced by Botan::TLS::PSK::calculate_binders(), operator=(), and Botan::TLS::Client_Hello_13::retry().

◆ current()

const Transcript_Hash & Botan::TLS::Transcript_Hash_State::current ( ) const

returns the latest transcript hash (given an algorithm was already specified and some data was provided to update)

Definition at line 180 of file tls_transcript_hash_13.cpp.

180 {
181 BOTAN_STATE_CHECK(!m_current.empty());
182 return m_current;
183}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49

References BOTAN_STATE_CHECK.

Referenced by operator=().

◆ operator=() [1/2]

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

◆ operator=() [2/2]

Transcript_Hash_State & Botan::TLS::Transcript_Hash_State::operator= ( Transcript_Hash_State && other)
defaultnoexcept

◆ previous()

const Transcript_Hash & Botan::TLS::Transcript_Hash_State::previous ( ) const

returns the second-latest transcript hash throws if no 'current' was ever replaced by a call to update

Definition at line 185 of file tls_transcript_hash_13.cpp.

185 {
186 BOTAN_STATE_CHECK(!m_previous.empty());
187 return m_previous;
188}

References BOTAN_STATE_CHECK.

Referenced by operator=().

◆ recreate_after_hello_retry_request()

Transcript_Hash_State Botan::TLS::Transcript_Hash_State::recreate_after_hello_retry_request ( std::string_view algo_spec,
const Transcript_Hash_State & prev_transcript_hash_state )
static

Recreates a Transcript_Hash_State after receiving a Hello Retry Request. Note that the prev_transcript_hash_state must not have an hash algorithm set, yet. Furthermore it must contain exactly TWO unprocessed messages:

  • Client Hello 1, and
  • Hello Retry Request The result of this function is an ordinary transcript hash that can replace the previously used object in client and server implementations.

Definition at line 41 of file tls_transcript_hash_13.cpp.

42 {
43 // make sure that we have seen exactly 'client_hello' and 'hello_retry_request'
44 // before re-creating the transcript hash state
45 BOTAN_STATE_CHECK(prev_transcript_hash_state.m_hash == nullptr);
46 BOTAN_STATE_CHECK(prev_transcript_hash_state.m_unprocessed_transcript.size() == 2);
47
48 Transcript_Hash_State transcript_hash(prev_transcript_hash_state.m_flavor, algo_spec);
49
50 const auto& client_hello_1 = prev_transcript_hash_state.m_unprocessed_transcript.front();
51 const auto& hello_retry_request = prev_transcript_hash_state.m_unprocessed_transcript.back();
52
53 const auto hash_length = transcript_hash.m_hash->output_length();
54 BOTAN_DEBUG_ASSERT(hash_length <= 0xFF);
55
56 // RFC 9846 4.1
57 // [...], when the server responds to a ClientHello with a HelloRetryRequest,
58 // the value of ClientHello1 is replaced with a special synthetic handshake
59 // message of handshake type "message_hash" [...]:
60 const auto message_hash_header =
61 HandshakeProtocolHeader({to_underlying(Handshake_Type::MessageHash), 0, 0, static_cast<uint8_t>(hash_length)});
62
63 transcript_hash.m_hash->update(client_hello_1.first);
64 transcript_hash.m_hash->update(client_hello_1.second);
65 const auto message_hash_msg = transcript_hash.m_hash->final<SerializedHandshakeMessage>();
66
67 transcript_hash.update(message_hash_header, message_hash_msg);
68 transcript_hash.update(hello_retry_request.first, hello_retry_request.second);
69
70 return transcript_hash;
71}
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:136
Strong< std::array< uint8_t, 4 >, struct HandshakeProtocolHeader_ > HandshakeProtocolHeader
Holds the serialization of a TLS 1.3 handshake protocol header.
Strong< std::vector< uint8_t >, struct SerializedHandshakeMessage_ > SerializedHandshakeMessage
auto to_underlying(T e) noexcept
Definition stl_util.h:158

References BOTAN_DEBUG_ASSERT, BOTAN_STATE_CHECK, Botan::TLS::MessageHash, Botan::to_underlying(), Transcript_Hash_State(), and update().

Referenced by ~Transcript_Hash_State().

◆ set_algorithm()

void Botan::TLS::Transcript_Hash_State::set_algorithm ( std::string_view algo_spec)

Definition at line 195 of file tls_transcript_hash_13.cpp.

195 {
196 BOTAN_STATE_CHECK(m_hash == nullptr || m_hash->name() == algo_spec);
197 if(m_hash != nullptr) {
198 return;
199 }
200
201 m_hash = HashFunction::create_or_throw(algo_spec);
202 for(const auto& [header, msg] : m_unprocessed_transcript) {
203 update(header, msg);
204 }
205 m_unprocessed_transcript.clear();
206}
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311
void update(HandshakeProtocolHeader tls_message_header, StrongSpan< const SerializedHandshakeMessage > serialized_message)

References BOTAN_STATE_CHECK, Botan::HashFunction::create_or_throw(), and update().

Referenced by Botan::TLS::PSK::calculate_binders(), operator=(), and Transcript_Hash_State().

◆ truncated()

const Transcript_Hash & Botan::TLS::Transcript_Hash_State::truncated ( ) const

returns a truncated transcript hash (see RFC 8446 4.2.11.2)

This is useful for implementing PSK binders in the PSK extension of client hello. It is a transcript over a partially marshalled client hello message. This hash is available only if the last processed message was a client hello with a PSK extension.

throws if no 'truncated' hash is available

Definition at line 190 of file tls_transcript_hash_13.cpp.

190 {
191 BOTAN_STATE_CHECK(!m_truncated.empty());
192 return m_truncated;
193}

References BOTAN_STATE_CHECK.

Referenced by operator=().

◆ update()

void Botan::TLS::Transcript_Hash_State::update ( HandshakeProtocolHeader tls_message_header,
StrongSpan< const SerializedHandshakeMessage > serialized_message )

Updates the transcript hash with a new handshake message where tls_message_header is the 4-byte handshake message header and serialized_message_s is the serialized handshake message.

Definition at line 151 of file tls_transcript_hash_13.cpp.

152 {
153 if(m_hash != nullptr) {
154 m_hash->update(tls_message_header);
155
156 // Check whether we should generate a truncated hash for supporting PSK
157 // binder calculation or verification. See RFC 9846 4.3.11.2.
158 const auto message_type = static_cast<Handshake_Type>(tls_message_header[0]);
159 if(message_type == Handshake_Type::ClientHello) {
160 const auto truncation_mark = find_client_hello_truncation_mark(serialized_message_s, m_flavor);
161 if(truncation_mark.has_value()) {
162 m_hash->update(serialized_message_s.get().first(*truncation_mark));
163 m_truncated = read_hash_state(m_hash);
164 m_hash->update(serialized_message_s.get().subspan(*truncation_mark));
165 } else {
166 m_truncated.clear();
167 m_hash->update(serialized_message_s);
168 }
169 } else {
170 m_truncated.clear();
171 m_hash->update(serialized_message_s);
172 }
173
174 m_previous = std::exchange(m_current, read_hash_state(m_hash));
175 } else {
176 m_unprocessed_transcript.emplace_back(tls_message_header, serialized_message_s);
177 }
178}

References Botan::TLS::ClientHello, and Botan::StrongSpan< T >::get().

Referenced by Botan::TLS::TLS_Handshake_Layer::next_message(), operator=(), recreate_after_hello_retry_request(), set_algorithm(), and Botan::TLS::Handshake_Layer::update_transcript_for_psk_binder_calc().


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