Botan 3.14.1
Crypto and TLS for C&
tls_transcript_hash_13.cpp
Go to the documentation of this file.
1/*
2* TLS transcript hash implementation for TLS 1.3
3* (C) 2022 Jack Lloyd
4* 2022 Hannes Rantzsch, René Meusel - neXenio GmbH
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#include <botan/internal/tls_transcript_hash_13.h>
10
11#include <botan/hash.h>
12#include <botan/tls_exceptn.h>
13#include <botan/tls_extensions.h>
14#include <botan/internal/stl_util.h>
15#include <botan/internal/tls_reader.h>
16
17#include <utility>
18
19namespace Botan::TLS {
20
22
23Transcript_Hash_State::Transcript_Hash_State(TLS_Flavor flavor, std::string_view algo_spec) :
24 Transcript_Hash_State(flavor) {
25 set_algorithm(algo_spec);
26}
27
29
32
34 m_flavor(other.m_flavor),
35 m_hash((other.m_hash != nullptr) ? other.m_hash->copy_state() : nullptr),
36 m_unprocessed_transcript(other.m_unprocessed_transcript),
37 m_current(other.m_current),
38 m_previous(other.m_previous),
39 m_truncated(other.m_truncated) {}
40
42 std::string_view algo_spec, const Transcript_Hash_State& prev_transcript_hash_state) {
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}
72
73namespace {
74
75// TODO: This is a massive code duplication of the client hello parsing code,
76// as well as basic parsing of extensions. We should resolve this.
77//
78// Ad-hoc idea: When parsing the production objects, we could keep markers into
79// the original buffer. E.g. the PSK extensions would keep its off-
80// set into the entire client hello buffer. Using that offset we
81// could quickly identify the offset of the binders list slice the
82// buffer without re-parsing it.
83//
84// Finds the truncation offset in a serialization of Client Hello as defined in
85// RFC 8446 4.2.11.2 used for the calculation of PSK binder MACs.
86// Returns std::nullopt if the Client Hello does not contain a PSK extension.
87std::optional<size_t> find_client_hello_truncation_mark(std::span<const uint8_t> client_hello, TLS_Flavor flavor) {
88 BOTAN_UNUSED(flavor);
89
90 TLS_Data_Reader reader("Client Hello Truncation", client_hello);
91
92 // legacy version
93 reader.discard_next(2);
94
95 // random
96 reader.discard_next(32);
97
98 // session ID
99 const auto session_id_length = reader.get_byte();
100 reader.discard_next(session_id_length);
101
102 // cipher suites
103 const auto ciphersuites_length = reader.get_uint16_t();
104 reader.discard_next(ciphersuites_length);
105
106 // compression methods
107 const auto compression_methods_length = reader.get_byte();
108 reader.discard_next(compression_methods_length);
109
110 // extensions
111 const auto extensions_length = reader.get_uint16_t();
112 const auto extensions_offset = reader.read_so_far();
113 while(reader.has_remaining() && reader.read_so_far() - extensions_offset < extensions_length) {
114 const auto ext_type = static_cast<Extension_Code>(reader.get_uint16_t());
115 const auto ext_length = reader.get_uint16_t();
116
117 // skip over all extensions, finding the PSK extension to be truncated
118 if(ext_type != Extension_Code::PresharedKey) {
119 reader.discard_next(ext_length);
120 continue;
121 }
122
123 // PSK identities list
124 const auto identities_length = reader.get_uint16_t();
125 reader.discard_next(identities_length);
126
127 // check that only the binders are left in the buffer...
128 const auto binders_length = reader.peek_uint16_t();
129 if(binders_length != reader.remaining_bytes() - 2 /* binders_length */) {
130 throw TLS_Exception(Alert::IllegalParameter,
131 "Failed to truncate Client Hello that doesn't end on the PSK binders list");
132 }
133
134 // the reader now points to the truncation point
135 return reader.read_so_far();
136 }
137
138 // if no PSK extension was found, no truncation is necessary
139 return std::nullopt;
140}
141
142std::vector<uint8_t> read_hash_state(std::unique_ptr<HashFunction>& hash) {
143 // Botan does not support finalizing a HashFunction without resetting
144 // the internal state of the hash. Hence we first copy the internal
145 // state and then finalize the transient HashFunction.
146 return hash->copy_state()->final_stdvec();
147}
148
149} // namespace
150
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}
179
181 BOTAN_STATE_CHECK(!m_current.empty());
182 return m_current;
183}
184
186 BOTAN_STATE_CHECK(!m_previous.empty());
187 return m_previous;
188}
189
191 BOTAN_STATE_CHECK(!m_truncated.empty());
192 return m_truncated;
193}
194
195void Transcript_Hash_State::set_algorithm(std::string_view algo_spec) {
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}
207
211
212} // namespace Botan::TLS
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:136
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311
underlying_span get() const
const Transcript_Hash & current() const
void update(HandshakeProtocolHeader tls_message_header, StrongSpan< const SerializedHandshakeMessage > serialized_message)
static Transcript_Hash_State recreate_after_hello_retry_request(std::string_view algo_spec, const Transcript_Hash_State &prev_transcript_hash_state)
void set_algorithm(std::string_view algo_spec)
const Transcript_Hash & previous() const
const Transcript_Hash & truncated() const
Transcript_Hash_State & operator=(const Transcript_Hash_State &)=delete
std::vector< uint8_t > Transcript_Hash
Definition tls_magic.h:105
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