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 &&)=default
const Transcript_Hash &	previous () const
void	set_algorithm (std::string_view algo_spec)
	Transcript_Hash_State ()=default
	Transcript_Hash_State (std::string_view algo_spec)
	Transcript_Hash_State (Transcript_Hash_State &&)=default
const Transcript_Hash &	truncated () const
void	update (std::span< const uint8_t > serialized_message_s)
	~Transcript_Hash_State ()=default

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 28 of file tls_transcript_hash_13.h.

Constructor & Destructor Documentation

Transcript_Hash_State() [1/3]

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

default

Transcript_Hash_State() [2/3]

Botan::TLS::Transcript_Hash_State::Transcript_Hash_State

(

std::string_view

algo_spec

)

Definition at line 19 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

Transcript_Hash_State() [3/3]

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

default

Member Function Documentation

clone()

Transcript_Hash_State Botan::TLS::Transcript_Hash_State::clone

(

)

const

Definition at line 203 of file tls_transcript_hash_13.cpp.

                                                         {
   return *this;
}

Referenced by Botan::TLS::PSK::calculate_binders(), 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 175 of file tls_transcript_hash_13.cpp.

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

References BOTAN_STATE_CHECK.

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 && )

default

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

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

References BOTAN_STATE_CHECK.

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 30 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 ths(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 = ths.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 += ths.m_hash->process(client_hello_1);
 
   ths.update(message_hash);
   ths.update(hello_retry_request);
 
   return ths;
}

References BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, and update().

set_algorithm()

void Botan::TLS::Transcript_Hash_State::set_algorithm

(

std::string_view

algo_spec

)

Definition at line 190 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(), 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 185 of file tls_transcript_hash_13.cpp.

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

References BOTAN_STATE_CHECK.

update()

void Botan::TLS::Transcript_Hash_State::update

(

std::span< const uint8_t >

serialized_message_s

)

Definition at line 147 of file tls_transcript_hash_13.cpp.

                                                                              {
   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(), Botan::TLS::Handshake_Layer::prepare_message(), and recreate_after_hello_retry_request().

---

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