Botan 3.14.1
Crypto and TLS for C&
msg_client_hello.cpp
Go to the documentation of this file.
1/*
2* TLS Client Hello Messages
3* (C) 2004-2011,2015,2016 Jack Lloyd
4* 2016 Matthias Gierlings
5* 2017 Harry Reimann, Rohde & Schwarz Cybersecurity
6* 2021 Elektrobit Automotive GmbH
7* 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
8* 2026 René Meusel - Rohde & Schwarz Cybersecurity GmbH
9*
10* Botan is released under the Simplified BSD License (see license.txt)
11*/
12
13#include <botan/tls_messages.h>
14#include <botan/internal/tls_messages_internal.h>
15
16#include <botan/hash.h>
17#include <botan/mac.h>
18#include <botan/rng.h>
19#include <botan/tls_callbacks.h>
20#include <botan/tls_policy.h>
21#include <botan/internal/tls_reader.h>
22#include <algorithm>
23
24namespace Botan::TLS {
25
26std::vector<uint8_t> make_hello_random(RandomNumberGenerator& rng, Callbacks& cb, const Policy& policy) {
27 auto buf = rng.random_vec<std::vector<uint8_t>>(32);
28
29 if(policy.hash_hello_random()) {
30 auto sha256 = HashFunction::create_or_throw("SHA-256");
31 sha256->update(buf);
32 sha256->final(buf);
33 }
34
35 // TLS 1.3 does not require the insertion of a timestamp in the client hello
36 // random. When offering both TLS 1.2 and 1.3 we nevertheless comply with the
37 // legacy specification.
38 if(policy.include_time_in_hello_random() && (policy.allow_tls12() || policy.allow_dtls12())) {
39 const uint32_t time32 = static_cast<uint32_t>(std::chrono::system_clock::to_time_t(cb.tls_current_timestamp()));
40
41 store_be(time32, buf.data());
42 }
43
44 return buf;
45}
46
47std::vector<uint8_t> calculate_cookie(std::span<const uint8_t> client_hello_bits,
48 std::string_view client_identity,
49 std::span<const uint8_t> cookie_secret) {
50 auto hmac = MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)");
51 hmac->set_key(cookie_secret);
52
53 hmac->update_be(static_cast<uint64_t>(client_hello_bits.size()));
54 hmac->update(client_hello_bits);
55 hmac->update_be(static_cast<uint64_t>(client_identity.size()));
56 hmac->update(client_identity);
57
58 return hmac->final_stdvec();
59}
60
61Client_Hello_Internal::Client_Hello_Internal(std::span<const uint8_t> buf) {
62 /*
63 Minimum possible client hello
64
65 version: 2 bytes
66 random: 32 bytes
67 session_id len: 1 byte
68 ciphersuite_len: 2
69 ciphersuite (single): 2
70 compression_len: 1
71 compression (single): 1
72 */
73
74 constexpr size_t MinimumClientHelloBytes = 2 + 32 + 1 + 2 + 2 + 1 + 1;
75 if(buf.size() < MinimumClientHelloBytes) {
76 throw Decoding_Error("Client_Hello: Packet corrupted");
77 }
78
79 TLS_Data_Reader reader("ClientHello", buf);
80
81 const uint8_t major_version = reader.get_byte();
82 const uint8_t minor_version = reader.get_byte();
83
84 m_legacy_version = Protocol_Version(major_version, minor_version);
85
86 // DTLS has an additional 1 byte cookie length field
87 if(m_legacy_version.is_datagram_protocol() && buf.size() < MinimumClientHelloBytes + 1) {
88 throw Decoding_Error("Client_Hello: DTLS packet corrupted");
89 }
90
91 m_random = reader.get_fixed<uint8_t>(32);
92 m_session_id = Session_ID(reader.get_range<uint8_t>(1, 0, 32));
93
94 if(m_legacy_version.is_datagram_protocol()) {
95 auto sha256 = HashFunction::create_or_throw("SHA-256");
96 sha256->update(reader.get_data_read_so_far());
97
98 m_hello_cookie = reader.get_range<uint8_t>(1, 0, 255);
99
100 sha256->update(reader.get_remaining());
101 m_cookie_input_bits = sha256->final_stdvec();
102 }
103
104 m_suites = reader.get_range_vector<uint16_t>(2, 1, 32767);
105 m_comp_methods = reader.get_range_vector<uint8_t>(1, 1, 255);
106
108}
109
111 // RFC 8446 4.2.1
112 // If [the "supported_versions"] extension is not present, servers
113 // which are compliant with this specification and which also support
114 // TLS 1.2 MUST negotiate TLS 1.2 or prior as specified in [RFC5246],
115 // even if ClientHello.legacy_version is 0x0304 or later.
116 //
117 // RFC 8446 4.2.1
118 // Servers MUST be prepared to receive ClientHellos that include
119 // [the supported_versions] extension but do not include 0x0304 in
120 // the list of versions.
121 //
122 // RFC 8446 4.1.2
123 // TLS 1.3 ClientHellos are identified as having a legacy_version of
124 // 0x0303 and a supported_versions extension present with 0x0304 as
125 // the highest version indicated therein.
126 if(!extensions().has<Supported_Versions>() ||
127 !extensions().get<Supported_Versions>()->supports(Protocol_Version::TLS_V13)) {
128 // The exact legacy_version is ignored we just inspect it to
129 // distinguish TLS and DTLS.
130 return (m_legacy_version.is_datagram_protocol()) ? Protocol_Version::DTLS_V12 : Protocol_Version::TLS_V12;
131 }
132
133 // Note: The Client_Hello_13 class will make sure that legacy_version
134 // is exactly 0x0303 (aka ossified TLS 1.2)
135 return Protocol_Version::TLS_V13;
136}
137
138Client_Hello::Client_Hello(Client_Hello&&) noexcept = default;
139Client_Hello& Client_Hello::operator=(Client_Hello&&) noexcept = default;
140
141Client_Hello::~Client_Hello() = default;
144
146* Read a counterparty client hello
147*/
148Client_Hello::Client_Hello(std::unique_ptr<Client_Hello_Internal> data) : m_data(std::move(data)) {
150}
151
155
157 return m_data->legacy_version();
158}
159
160const std::vector<uint8_t>& Client_Hello::random() const {
161 return m_data->random();
162}
163
165 return m_data->session_id();
166}
167
168const std::vector<uint8_t>& Client_Hello::compression_methods() const {
169 return m_data->comp_methods();
170}
171
172const std::vector<uint16_t>& Client_Hello::ciphersuites() const {
173 return m_data->ciphersuites();
174}
175
176std::set<Extension_Code> Client_Hello::extension_types() const {
177 return m_data->extensions().extension_types();
178}
179
181 return m_data->extensions();
182}
183
184/*
185* Serialize a Client Hello message
186*/
187std::vector<uint8_t> Client_Hello::serialize() const {
188 std::vector<uint8_t> buf;
189 buf.reserve(1024); // working around GCC warning
190
191 buf.push_back(m_data->legacy_version().major_version());
192 buf.push_back(m_data->legacy_version().minor_version());
193 buf += m_data->random();
194
195 append_tls_length_value(buf, m_data->session_id().get(), 1);
196
197 if(m_data->legacy_version().is_datagram_protocol()) {
198 append_tls_length_value(buf, m_data->hello_cookie(), 1);
199 }
200
201 append_tls_length_value(buf, m_data->ciphersuites(), 2);
202 append_tls_length_value(buf, m_data->comp_methods(), 1);
203
204 /*
205 * May not want to send extensions at all in some cases. If so,
206 * should include SCSV value (if reneg info is empty, if not we are
207 * renegotiating with a modern server)
208 */
209
210 buf += m_data->extensions().serialize(Connection_Side::Client);
211
212 return buf;
213}
214
215std::vector<uint8_t> Client_Hello::cookie_input_data() const {
216 BOTAN_STATE_CHECK(!m_data->hello_cookie_input_bits().empty());
217
218 return m_data->hello_cookie_input_bits();
219}
220
221/*
222* Check if we offered this ciphersuite
223*/
224bool Client_Hello::offered_suite(uint16_t ciphersuite) const {
225 return std::find(m_data->ciphersuites().cbegin(), m_data->ciphersuites().cend(), ciphersuite) !=
226 m_data->ciphersuites().cend();
227}
228
229std::vector<Signature_Scheme> Client_Hello::signature_schemes() const {
230 if(const Signature_Algorithms* sigs = m_data->extensions().get<Signature_Algorithms>()) {
231 return sigs->supported_schemes();
232 }
233 return {};
234}
235
236std::vector<Signature_Scheme> Client_Hello::certificate_signature_schemes() const {
237 // RFC 8446 4.2.3
238 // If no "signature_algorithms_cert" extension is present, then the
239 // "signature_algorithms" extension also applies to signatures appearing
240 // in certificates.
241 if(const Signature_Algorithms_Cert* sigs = m_data->extensions().get<Signature_Algorithms_Cert>()) {
242 return sigs->supported_schemes();
243 } else {
244 return signature_schemes();
245 }
246}
247
248std::vector<Group_Params> Client_Hello::supported_ecc_curves() const {
249 if(const Supported_Groups* groups = m_data->extensions().get<Supported_Groups>()) {
250 return groups->ec_groups();
251 }
252 return {};
253}
254
255std::vector<Group_Params> Client_Hello::supported_dh_groups() const {
256 if(const Supported_Groups* groups = m_data->extensions().get<Supported_Groups>()) {
257 return groups->dh_groups();
258 }
259 return std::vector<Group_Params>();
260}
261
262std::string Client_Hello::sni_hostname() const {
263 if(const Server_Name_Indicator* sni = m_data->extensions().get<Server_Name_Indicator>()) {
264 return sni->host_name();
265 }
266 return "";
267}
268
270 // RFC 9846 4.2.2
271 // TLS 1.3 ClientHellos are identified as having a legacy_version of
272 // 0x0303 and a "supported_versions" extension present with 0x0304 as the
273 // highest version indicated therein.
274 const auto* versions = m_data->extensions().get<Supported_Versions>();
275 if(versions == nullptr) {
276 return false;
277 }
278
279 return versions->supports(Protocol_Version::TLS_V13) || //
280 versions->supports(Protocol_Version::DTLS_V13);
281}
282
283std::vector<Protocol_Version> Client_Hello::supported_versions() const {
284 if(const Supported_Versions* versions = m_data->extensions().get<Supported_Versions>()) {
285 return versions->versions();
286 }
287 return {};
288}
289
291 return m_data->extensions().has<Application_Layer_Protocol_Notification>();
292}
293
295 return m_data->extensions().has<Signature_Algorithms>();
296}
297
298std::vector<std::string> Client_Hello::next_protocols() const {
299 if(const auto* alpn = m_data->extensions().get<Application_Layer_Protocol_Notification>()) {
300 return alpn->protocols();
301 }
302 return {};
303}
304
305std::vector<uint16_t> Client_Hello::srtp_profiles() const {
306 if(const SRTP_Protection_Profiles* srtp = m_data->extensions().get<SRTP_Protection_Profiles>()) {
307 return srtp->profiles();
308 }
309 return {};
310}
311
312const std::vector<uint8_t>& Client_Hello::cookie() const {
313 return m_data->hello_cookie();
314}
315
316Client_Hello_12_Shim::Client_Hello_12_Shim(std::unique_ptr<Client_Hello_Internal> data) :
317 Client_Hello(std::move(data)) {}
318
319Client_Hello_12_Shim::Client_Hello_12_Shim(std::span<const uint8_t> buf) :
320 Client_Hello_12_Shim(std::make_unique<Client_Hello_Internal>(buf)) {}
321
322} // namespace Botan::TLS
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:142
void random_vec(std::span< uint8_t > v)
Definition rng.h:254
virtual std::chrono::system_clock::time_point tls_current_timestamp()
Client_Hello_12_Shim(std::span< const uint8_t > buf)
Client_Hello(const Client_Hello &)=delete
const Extensions & extensions() const
const std::vector< uint8_t > & cookie() const
std::string sni_hostname() const
std::vector< uint8_t > serialize() const override
const std::vector< uint8_t > & random() const
std::vector< Signature_Scheme > signature_schemes() const
const Extensions & extensions() const
bool offered_suite(uint16_t ciphersuite) const
std::unique_ptr< Client_Hello_Internal > m_data
std::vector< Group_Params > supported_ecc_curves() const
std::vector< Signature_Scheme > certificate_signature_schemes() const
const std::vector< uint16_t > & ciphersuites() const
std::vector< uint8_t > cookie_input_data() const
std::set< Extension_Code > extension_types() const
std::vector< Group_Params > supported_dh_groups() const
std::vector< std::string > next_protocols() const
const Session_ID & session_id() const
Protocol_Version legacy_version() const
const std::vector< uint8_t > & compression_methods() const
std::vector< uint16_t > srtp_profiles() const
Handshake_Type type() const override
std::vector< Protocol_Version > supported_versions() const
Client_Hello(const Client_Hello &)=delete
void deserialize(TLS_Data_Reader &reader, Connection_Side from, Handshake_Type message_type)
virtual bool include_time_in_hello_random() const
virtual bool allow_tls12() const
virtual bool hash_hello_random() const
virtual bool allow_dtls12() const
bool supports(Protocol_Version version) const
std::vector< uint8_t > get_remaining()
Definition tls_reader.h:41
std::vector< T > get_range(size_t len_bytes, size_t min_elems, size_t max_elems)
Definition tls_reader.h:115
std::vector< T > get_fixed(size_t size)
Definition tls_reader.h:134
std::vector< uint8_t > get_data_read_so_far()
Definition tls_reader.h:46
std::vector< T > get_range_vector(size_t len_bytes, size_t min_elems, size_t max_elems)
Definition tls_reader.h:122
void append_tls_length_value(std::vector< uint8_t, Alloc > &buf, const T *vals, size_t vals_size, size_t tag_size)
Definition tls_reader.h:182
std::vector< uint8_t > make_hello_random(RandomNumberGenerator &rng, Callbacks &cb, const Policy &policy)
std::vector< uint8_t > calculate_cookie(std::span< const uint8_t > client_hello_bits, std::string_view client_identity, std::span< const uint8_t > cookie_secret)
Strong< std::vector< uint8_t >, struct Session_ID_ > Session_ID
holds a TLS 1.2 session ID for stateful resumption
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745