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 ()
	Transcript_Hash_State (std::string_view algo_spec)
	Transcript_Hash_State (Transcript_Hash_State &&other) noexcept
const Transcript_Hash &	truncated () const
void	update (std::span< const uint8_t > serialized_message_s)
	~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 32 of file tls_transcript_hash_13.h.

Constructor & Destructor Documentation

Transcript_Hash_State() [1/3]

Botan::TLS::Transcript_Hash_State::Transcript_Hash_State ( )

default

References Transcript_Hash_State().

Referenced by clone(), operator=(), operator=(), recreate_after_hello_retry_request(), Transcript_Hash_State(), Transcript_Hash_State(), and ~Transcript_Hash_State().

Transcript_Hash_State() [2/3]

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

explicit

Definition at line 20 of file tls_transcript_hash_13.cpp.

                                                                     {
   set_algorithm(algo_spec);
}

References set_algorithm().

~Transcript_Hash_State()

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

default

References recreate_after_hello_retry_request(), and Transcript_Hash_State().

Transcript_Hash_State() [3/3]

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

defaultnoexcept

References Transcript_Hash_State().

Member Function Documentation

clone()

Transcript_Hash_State Botan::TLS::Transcript_Hash_State::clone

(

)

const

Definition at line 211 of file tls_transcript_hash_13.cpp.

                                                         {
   return *this;
}

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 183 of file tls_transcript_hash_13.cpp.

                                                            {
   BOTAN_STATE_CHECK(!m_current.empty());
   return m_current;
}

References BOTAN_STATE_CHECK.

Referenced by operator=().

operator=() [1/2]

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

delete

References Transcript_Hash_State().

operator=() [2/2]

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

defaultnoexcept

References clone(), current(), previous(), set_algorithm(), Transcript_Hash_State(), truncated(), and update().

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 188 of file tls_transcript_hash_13.cpp.

                                                             {
   BOTAN_STATE_CHECK(!m_previous.empty());
   return m_previous;
}

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 38 of file tls_transcript_hash_13.cpp.

                                                                                      {
   // make sure that we have seen exactly 'client_hello' and 'hello_retry_request'
   // before re-creating the transcript hash state
   BOTAN_STATE_CHECK(prev_transcript_hash_state.m_hash == nullptr);
   BOTAN_STATE_CHECK(prev_transcript_hash_state.m_unprocessed_transcript.size() == 2);
 
   Transcript_Hash_State transcript_hash(algo_spec);
 
   const auto& client_hello_1 = prev_transcript_hash_state.m_unprocessed_transcript.front();
   const auto& hello_retry_request = prev_transcript_hash_state.m_unprocessed_transcript.back();
 
   const size_t hash_length = transcript_hash.m_hash->output_length();
   BOTAN_ASSERT_NOMSG(hash_length < 256);
 
   // RFC 8446 4.4.1
   //    [...], when the server responds to a ClientHello with a HelloRetryRequest,
   //    the value of ClientHello1 is replaced with a special synthetic handshake
   //    message of handshake type "message_hash" [(0xFE)] containing:
   std::vector<uint8_t> message_hash;
   message_hash.reserve(4 + hash_length);
   message_hash.push_back(0xFE /* message type 'message_hash' RFC 8446 4. */);
   message_hash.push_back(0x00);
   message_hash.push_back(0x00);
   message_hash.push_back(static_cast<uint8_t>(hash_length));
   message_hash += transcript_hash.m_hash->process(client_hello_1);
 
   transcript_hash.update(message_hash);
   transcript_hash.update(hello_retry_request);
 
   return transcript_hash;
}

References BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, 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 198 of file tls_transcript_hash_13.cpp.

                                                                  {
   BOTAN_STATE_CHECK(m_hash == nullptr || m_hash->name() == algo_spec);
   if(m_hash != nullptr) {
      return;
   }
 
   m_hash = HashFunction::create_or_throw(algo_spec);
   for(const auto& msg : m_unprocessed_transcript) {
      update(msg);
   }
   m_unprocessed_transcript.clear();
}

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 193 of file tls_transcript_hash_13.cpp.

                                                              {
   BOTAN_STATE_CHECK(!m_truncated.empty());
   return m_truncated;
}

References BOTAN_STATE_CHECK.

Referenced by operator=().

update()

void Botan::TLS::Transcript_Hash_State::update

(

std::span< const uint8_t >

serialized_message_s

)

Definition at line 155 of file tls_transcript_hash_13.cpp.

                                                                              {
   const auto* serialized_message = serialized_message_s.data();
   auto serialized_message_length = serialized_message_s.size();
   if(m_hash != nullptr) {
      auto truncation_mark = serialized_message_length;
 
      // Check whether we should generate a truncated hash for supporting PSK
      // binder calculation or verification. See RFC 8446 4.2.11.2.
      if(serialized_message_length > 0 && *serialized_message == static_cast<uint8_t>(Handshake_Type::ClientHello)) {
         truncation_mark = find_client_hello_truncation_mark(serialized_message_s);
      }
 
      if(truncation_mark < serialized_message_length) {
         m_hash->update(serialized_message, truncation_mark);
         m_truncated = read_hash_state(m_hash);
         m_hash->update(serialized_message + truncation_mark, serialized_message_length - truncation_mark);
      } else {
         m_truncated.clear();
         m_hash->update(serialized_message, serialized_message_length);
      }
 
      m_previous = std::exchange(m_current, read_hash_state(m_hash));
   } else {
      m_unprocessed_transcript.push_back(
         std::vector(serialized_message, serialized_message + serialized_message_length));
   }
}

References Botan::TLS::ClientHello.

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

---

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

• src/lib/tls/tls13/tls_transcript_hash_13.h
• src/lib/tls/tls13/tls_transcript_hash_13.cpp