Botan 3.0.0-alpha0
Crypto and TLS for C&
msg_client_hello.cpp
Go to the documentation of this file.
1/*
2* TLS Hello Request and 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*
9* Botan is released under the Simplified BSD License (see license.txt)
10*/
11
12
13#include <botan/tls_exceptn.h>
14#include <botan/tls_messages.h>
15#include <botan/tls_callbacks.h>
16#include <botan/rng.h>
17#include <botan/hash.h>
18#include <botan/tls_version.h>
19
20#include <botan/internal/stl_util.h>
21#include <botan/internal/tls_reader.h>
22#include <botan/internal/tls_session_key.h>
23#include <botan/internal/tls_handshake_io.h>
24#include <botan/internal/tls_handshake_hash.h>
25
26#ifdef BOTAN_HAS_TLS_13
27 #include <botan/internal/tls_transcript_hash_13.h>
28 #include <botan/internal/tls_handshake_layer_13.h>
29#endif
30
31#include <chrono>
32
33namespace Botan::TLS {
34
35enum
36 {
38 };
39
40std::vector<uint8_t> make_hello_random(RandomNumberGenerator& rng,
41 Callbacks& cb,
42 const Policy& policy)
43 {
44 std::vector<uint8_t> buf(32);
45 rng.randomize(buf.data(), buf.size());
46
47 if(policy.hash_hello_random())
48 {
49 auto sha256 = HashFunction::create_or_throw("SHA-256");
50 sha256->update(buf);
51 sha256->final(buf);
52 }
53
54 // TLS 1.3 does not require the insertion of a timestamp in the client hello
55 // random. When offering both TLS 1.2 and 1.3 we nevertheless comply with the
56 // legacy specification.
57 if(policy.include_time_in_hello_random() && (policy.allow_tls12() || policy.allow_dtls12()))
58 {
59 const uint32_t time32 = static_cast<uint32_t>(
60 std::chrono::system_clock::to_time_t(cb.tls_current_timestamp()));
61
62 store_be(time32, buf.data());
63 }
64
65 return buf;
66 }
67
68/*
69* Read a counterparty client hello
70*/
71Client_Hello::Client_Hello(const std::vector<uint8_t>& buf)
72 {
73 if(buf.size() < 41)
74 { throw Decoding_Error("Client_Hello: Packet corrupted"); }
75
76 TLS_Data_Reader reader("ClientHello", buf);
77
78 const uint8_t major_version = reader.get_byte();
79 const uint8_t minor_version = reader.get_byte();
80
81 m_legacy_version = Protocol_Version(major_version, minor_version);
82 m_random = reader.get_fixed<uint8_t>(32);
83 m_session_id = reader.get_range<uint8_t>(1, 0, 32);
84
86 {
87 auto sha256 = HashFunction::create_or_throw("SHA-256");
88 sha256->update(reader.get_data_read_so_far());
89
90 m_hello_cookie = reader.get_range<uint8_t>(1, 0, 255);
91
92 sha256->update(reader.get_remaining());
93 m_cookie_input_bits.resize(sha256->output_length());
94 sha256->final(m_cookie_input_bits.data());
95 }
96
97 m_suites = reader.get_range_vector<uint16_t>(2, 1, 32767);
98
99 m_comp_methods = reader.get_range_vector<uint8_t>(1, 1, 255);
100
102
103 // TODO: Reject oid_filters extension if found (which is the only known extension that
104 // must not occur in the TLS 1.3 client hello.
105 // RFC 8446 4.2.5
106 // [The oid_filters extension] MUST only be sent in the CertificateRequest message.
107 if(offered_suite(static_cast<uint16_t>(TLS_EMPTY_RENEGOTIATION_INFO_SCSV)))
108 {
110 {
111 if(!reneg->renegotiation_info().empty())
113 "Client sent renegotiation SCSV and non-empty extension");
114 }
115 else
116 {
117 // add fake extension
118 m_extensions.add(new Renegotiation_Extension());
119 }
120 }
121 }
122
124 {
125 return CLIENT_HELLO;
126 }
127
129 {
130 return m_legacy_version;
131 }
132
133const std::vector<uint8_t>& Client_Hello::random() const
134 {
135 return m_random;
137
138const std::vector<uint8_t>& Client_Hello::session_id() const
139 {
140 return m_session_id;
141 }
142
143const std::vector<uint8_t>& Client_Hello::compression_methods() const
144 {
145 return m_comp_methods;
146 }
147
148const std::vector<uint16_t>& Client_Hello::ciphersuites() const
149 {
150 return m_suites;
151 }
152
153std::set<Handshake_Extension_Type> Client_Hello::extension_types() const
154 {
156 }
157
159 {
160 return m_extensions;
161 }
162
164 {
166 { throw Invalid_State("Cannot use hello cookie with stream protocol"); }
167
168 m_hello_cookie = hello_verify.cookie();
169 }
170
171/*
172* Serialize a Client Hello message
173*/
174std::vector<uint8_t> Client_Hello::serialize() const
175 {
176 std::vector<uint8_t> buf;
177
178 buf.push_back(m_legacy_version.major_version());
179 buf.push_back(m_legacy_version.minor_version());
180 buf += m_random;
181
183
186
189
190 /*
191 * May not want to send extensions at all in some cases. If so,
192 * should include SCSV value (if reneg info is empty, if not we are
193 * renegotiating with a modern server)
194 */
195
197
198 return buf;
199 }
200
201std::vector<uint8_t> Client_Hello::cookie_input_data() const
202 {
203 if(m_cookie_input_bits.empty())
204 { throw Invalid_State("Client_Hello::cookie_input_data called but was not computed"); }
205
206 return m_cookie_input_bits;
207 }
208
209/*
210* Check if we offered this ciphersuite
211*/
212bool Client_Hello::offered_suite(uint16_t ciphersuite) const
213 {
214 return std::find(m_suites.cbegin(), m_suites.cend(), ciphersuite) != m_suites.cend();
215 }
216
217std::vector<Signature_Scheme> Client_Hello::signature_schemes() const
218 {
219 std::vector<Signature_Scheme> schemes;
220
222 {
223 schemes = sigs->supported_schemes();
224 }
225
226 return schemes;
227 }
228
229std::vector<Group_Params> Client_Hello::supported_ecc_curves() const
230 {
232 { return groups->ec_groups(); }
233 return std::vector<Group_Params>();
234 }
235
236std::vector<Group_Params> Client_Hello::supported_dh_groups() const
237 {
239 { return groups->dh_groups(); }
240 return std::vector<Group_Params>();
241 }
242
244 {
246 {
247 return ecc_formats->prefers_compressed();
248 }
249 return false;
250 }
251
252std::string Client_Hello::sni_hostname() const
253 {
255 { return sni->host_name(); }
256 return "";
257 }
258
260 {
262 }
263
264std::vector<uint8_t> Client_Hello_12::renegotiation_info() const
265 {
267 { return reneg->renegotiation_info(); }
268 return std::vector<uint8_t>();
269 }
270
271std::vector<Protocol_Version> Client_Hello::supported_versions() const
272 {
274 { return versions->versions(); }
275 return {};
276 }
277
279 {
281 }
282
283std::vector<uint8_t> Client_Hello_12::session_ticket() const
284 {
286 { return ticket->contents(); }
287 return std::vector<uint8_t>();
288 }
289
291 {
293 }
294
296 {
298 }
299
301 {
303 }
304
306 {
308 }
309
311 {
313 }
314
315std::vector<std::string> Client_Hello::next_protocols() const
316 {
318 { return alpn->protocols(); }
319 return std::vector<std::string>();
320 }
321
322std::vector<uint16_t> Client_Hello::srtp_profiles() const
323 {
325 { return srtp->profiles(); }
326 return std::vector<uint16_t>();
327 }
328
329const std::vector<uint8_t>& Client_Hello::cookie() const
330 {
331 return m_hello_cookie;
332 }
333/*
334* Create a new Hello Request message
335*/
337 {
338 io.send(*this);
339 }
340
341/*
342* Deserialize a Hello Request message
343*/
344Hello_Request::Hello_Request(const std::vector<uint8_t>& buf)
345 {
346 if(!buf.empty())
347 { throw Decoding_Error("Bad Hello_Request, has non-zero size"); }
348 }
349
350/*
351* Serialize a Hello Request message
352*/
353std::vector<uint8_t> Hello_Request::serialize() const
354 {
355 return std::vector<uint8_t>();
356 }
357
358/*
359* Create a new Client Hello message
360*/
363 const Policy& policy,
364 Callbacks& cb,
366 const std::vector<uint8_t>& reneg_info,
367 const Client_Hello_12::Settings& client_settings,
368 const std::vector<std::string>& next_protocols)
369 {
370 m_legacy_version = client_settings.protocol_version();
371 m_random = make_hello_random(rng, cb, policy);
372 m_suites = policy.ciphersuite_list(client_settings.protocol_version());
373
375 throw Internal_Error("Offering " + m_legacy_version.to_string() +
376 " but our own policy does not accept it");
377
378 /*
379 * Place all empty extensions in front to avoid a bug in some systems
380 * which reject hellos when the last extension in the list is empty.
381 */
382
383 // EMS must always be used with TLS 1.2, regardless of the policy used.
385
386 if(policy.negotiate_encrypt_then_mac())
388
390
392
394
395 if(!client_settings.hostname().empty())
396 { m_extensions.add(new Server_Name_Indicator(client_settings.hostname())); }
397
398 if(policy.support_cert_status_message())
400
401 auto supported_groups = std::make_unique<Supported_Groups>(policy.key_exchange_groups());
402 if(!supported_groups->ec_groups().empty())
403 {
405 }
406 m_extensions.add(supported_groups.release());
407
409
410 if(reneg_info.empty() && !next_protocols.empty())
412
415
417
418 hash.update(io.send(*this));
419 }
420
421/*
422* Create a new Client Hello message (session resumption case)
423*/
426 const Policy& policy,
427 Callbacks& cb,
429 const std::vector<uint8_t>& reneg_info,
430 const Session& session,
431 const std::vector<std::string>& next_protocols)
432 {
433 m_legacy_version = session.version();
434 m_random = make_hello_random(rng, cb, policy);
435 m_session_id = session.session_id();
437
438 if(!policy.acceptable_protocol_version(session.version()))
439 throw Internal_Error("Offering " + m_legacy_version.to_string() +
440 " but our own policy does not accept it");
441
442 if(!value_exists(m_suites, session.ciphersuite_code()))
443 { m_suites.push_back(session.ciphersuite_code()); }
444
445 /*
446 * As EMS must always be used with TLS 1.2, add it even if it wasn't used
447 * in the original session. If the server understands it and follows the
448 * RFC it should reject our resume attempt and upgrade us to a new session
449 * with the EMS protection.
450 */
452
453 if(session.supports_encrypt_then_mac())
455
457
459
461
462 if(policy.support_cert_status_message())
464
465 auto supported_groups = std::make_unique<Supported_Groups>(policy.key_exchange_groups());
466
467 if(!supported_groups->ec_groups().empty())
468 {
470 }
471
472 m_extensions.add(supported_groups.release());
473
475
476 if(reneg_info.empty() && !next_protocols.empty())
478
480
481 hash.update(io.send(*this));
482 }
483
484#if defined(BOTAN_HAS_TLS_13)
485
486/*
487* Create a new Client Hello message
488*/
489Client_Hello_13::Client_Hello_13(const Policy& policy,
490 Callbacks& cb,
492 const std::string& hostname,
493 const std::vector<std::string>& next_protocols,
494 const std::optional<Session>& session)
495 {
496 // RFC 8446 4.1.2
497 // In TLS 1.3, the client indicates its version preferences in the
498 // "supported_versions" extension (Section 4.2.1) and the
499 // legacy_version field MUST be set to 0x0303, which is the version
500 // number for TLS 1.2.
501 m_legacy_version = Protocol_Version::TLS_V12;
502 m_random = make_hello_random(rng, cb, policy);
504
505 if(policy.allow_tls12()) // Note: DTLS 1.3 is NYI, hence dtls_12 is not checked
506 {
507 const auto legacy_suites = policy.ciphersuite_list(Protocol_Version::TLS_V12);
508 m_suites.insert(m_suites.end(), legacy_suites.cbegin(), legacy_suites.cend());
509 }
510
512 {
513 // RFC 8446 4.1.2
514 // In compatibility mode (see Appendix D.4), this field MUST be non-empty,
515 // so a client not offering a pre-TLS 1.3 session MUST generate a new
516 // 32-byte value.
517 rng.random_vec(m_session_id, 32);
518 }
519
520 if(!hostname.empty())
521 m_extensions.add(new Server_Name_Indicator(hostname));
522
523 m_extensions.add(new Supported_Groups(policy.key_exchange_groups()));
524
525 m_extensions.add(new Key_Share(policy, cb, rng));
526
527 m_extensions.add(new Supported_Versions(Protocol_Version::TLS_V13, policy));
528
529 m_extensions.add(new Signature_Algorithms(policy.acceptable_signature_schemes()));
530
531 // TODO: Support for PSK-only mode without a key exchange.
532 // This should be configurable in TLS::Policy and should allow no PSK
533 // support at all (e.g. to disable support for session resumption).
534 m_extensions.add(new PSK_Key_Exchange_Modes({PSK_Key_Exchange_Mode::PSK_DHE_KE}));
535
536 // TODO: Add a signature_algorithms_cert extension negotiating the acceptable
537 // signature algorithms in a server certificate chain's certificates.
538
539 if(policy.support_cert_status_message())
540 m_extensions.add(new Certificate_Status_Request({}, {}));
541
542 // We currently support "record_size_limit" for TLS 1.3 exclusively. Hence,
543 // when TLS 1.2 is advertised as a supported protocol, we must not offer this
544 // extension.
545 if(policy.record_size_limit().has_value() && !policy.allow_tls12())
546 m_extensions.add(new Record_Size_Limit(policy.record_size_limit().value()));
547
548 if(!next_protocols.empty())
549 m_extensions.add(new Application_Layer_Protocol_Notification(next_protocols));
550
551 if(policy.allow_tls12())
552 {
553 m_extensions.add(new Renegotiation_Extension());
554 m_extensions.add(new Session_Ticket());
555
556 // EMS must always be used with TLS 1.2, regardless of the policy
557 m_extensions.add(new Extended_Master_Secret);
558
559 if(policy.negotiate_encrypt_then_mac())
560 m_extensions.add(new Encrypt_then_MAC);
561
562 if(m_extensions.has<Supported_Groups>() && !m_extensions.get<Supported_Groups>()->ec_groups().empty())
563 m_extensions.add(new Supported_Point_Formats(policy.use_ecc_point_compression()));
564 }
565
566 // TODO: Some extensions require a certain order or pose other assumptions.
567 // We should check those after the user was allowed to make changes to
568 // the extensions.
569 cb.tls_modify_extensions(m_extensions, CLIENT);
570
571 // RFC 8446 4.2.11
572 // The "pre_shared_key" extension MUST be the last extension in the
573 // ClientHello (this facilitates implementation [...]).
574 //
575 // The PSK extension takes the partial transcript hash into account. Passing
576 // into Callbacks::tls_modify_extensions() does not make sense therefore.
577 if(session.has_value())
578 {
579 m_extensions.add(new PSK(session.value(), cb));
580 calculate_psk_binders({});
581 }
582 }
583
584void Client_Hello_13::retry(const Hello_Retry_Request& hrr,
585 const Transcript_Hash_State& transcript_hash_state,
586 Callbacks& cb,
587 RandomNumberGenerator& rng)
588 {
589 BOTAN_STATE_CHECK(m_extensions.has<Supported_Groups>());
590 BOTAN_STATE_CHECK(m_extensions.has<Key_Share>());
591
592 auto hrr_ks = hrr.extensions().get<Key_Share>();
593 const auto& supported_groups = m_extensions.get<Supported_Groups>()->groups();
594
595 if(hrr.extensions().has<Key_Share>())
596 m_extensions.get<Key_Share>()->retry_offer(*hrr_ks, supported_groups, cb, rng);
597
598 // RFC 8446 4.2.2
599 // When sending the new ClientHello, the client MUST copy
600 // the contents of the extension received in the HelloRetryRequest into
601 // a "cookie" extension in the new ClientHello.
602 //
603 // RFC 8446 4.2.2
604 // Clients MUST NOT use cookies in their initial ClientHello in subsequent
605 // connections.
606 if(hrr.extensions().has<Cookie>())
607 {
608 BOTAN_STATE_CHECK(!m_extensions.has<Cookie>());
609 m_extensions.add(new Cookie(hrr.extensions().get<Cookie>()->get_cookie()));
610 }
611
612 // TODO: the consumer of the TLS implementation won't be able to distinguish
613 // invocations to this callback due to the first Client_Hello or the
614 // retried Client_Hello after receiving a Hello_Retry_Request.
615 cb.tls_modify_extensions(m_extensions, CLIENT);
616
617 auto psk = m_extensions.get<PSK>();
618 if(psk)
619 {
620 // Cipher suite should always be a known suite as this is checked upstream
621 const auto cipher = Ciphersuite::by_id(hrr.ciphersuite());
622 BOTAN_ASSERT_NOMSG(cipher.has_value());
623
624 // RFC 8446 4.1.4
625 // In [...] its updated ClientHello, the client SHOULD NOT offer
626 // any pre-shared keys associated with a hash other than that of the
627 // selected cipher suite.
628 psk->filter(cipher.value());
629
630 // RFC 8446 4.2.11.2
631 // If the server responds with a HelloRetryRequest and the client
632 // then sends ClientHello2, its binder will be computed over: [...].
633 calculate_psk_binders(transcript_hash_state.clone());
634 }
635 }
636
637void Client_Hello_13::calculate_psk_binders(Transcript_Hash_State ths)
638 {
639 auto psk = m_extensions.get<PSK>();
640 if(!psk || psk->empty())
641 return;
642
643 // RFC 8446 4.2.11.2
644 // Each entry in the binders list is computed as an HMAC over a
645 // transcript hash (see Section 4.4.1) containing a partial ClientHello
646 // [...].
647 //
648 // Therefore we marshal the entire message prematurely to obtain the
649 // (truncated) transcript hash, calculate the PSK binders with it, update
650 // the Client Hello thus finalizing the message. Down the road, it will be
651 // re-marshalled with the correct binders and sent over the wire.
653 psk->calculate_binders(ths);
654 }
655
656#endif // BOTAN_HAS_TLS_13
657
658}
#define BOTAN_ASSERT_NOMSG(expr)
Definition: assert.h:67
#define BOTAN_STATE_CHECK(expr)
Definition: assert.h:48
static std::unique_ptr< HashFunction > create_or_throw(const std::string &algo_spec, const std::string &provider="")
Definition: hash.cpp:312
virtual void randomize(uint8_t output[], size_t length)=0
secure_vector< uint8_t > random_vec(size_t bytes)
Definition: rng.h:167
virtual void tls_modify_extensions(Extensions &extn, Connection_Side which_side)
virtual std::chrono::system_clock::time_point tls_current_timestamp()
static std::optional< Ciphersuite > by_id(uint16_t suite)
const std::string & hostname() const
Definition: tls_messages.h:162
const Protocol_Version protocol_version() const
Definition: tls_messages.h:161
Client_Hello_12(const std::vector< uint8_t > &buf)
Definition: tls_messages.h:170
void update_hello_cookie(const Hello_Verify_Request &hello_verify)
std::vector< uint8_t > renegotiation_info() const
bool supports_extended_master_secret() const
std::vector< uint8_t > session_ticket() 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::vector< uint8_t > m_hello_cookie
Definition: tls_messages.h:146
bool sent_signature_algorithms() const
std::vector< uint8_t > m_cookie_input_bits
Definition: tls_messages.h:147
std::vector< Group_Params > supported_ecc_curves() const
std::vector< uint8_t > m_random
Definition: tls_messages.h:141
const std::vector< uint16_t > & ciphersuites() const
Protocol_Version m_legacy_version
Definition: tls_messages.h:139
std::vector< uint8_t > cookie_input_data() const
std::vector< uint8_t > m_comp_methods
Definition: tls_messages.h:143
std::vector< uint16_t > m_suites
Definition: tls_messages.h:142
std::vector< Group_Params > supported_dh_groups() const
std::vector< std::string > next_protocols() const
const std::vector< uint8_t > & session_id() const
Protocol_Version legacy_version() const
std::set< Handshake_Extension_Type > extension_types() const
const std::vector< uint8_t > & compression_methods() const
std::vector< uint16_t > srtp_profiles() const
Handshake_Type type() const override
std::vector< uint8_t > m_session_id
Definition: tls_messages.h:140
std::vector< Protocol_Version > supported_versions() const
std::vector< uint8_t > serialize(Connection_Side whoami) const
std::set< Handshake_Extension_Type > extension_types() const
void deserialize(TLS_Data_Reader &reader, const Connection_Side from, const Handshake_Type message_type)
void add(std::unique_ptr< Extension > extn)
virtual std::vector< uint8_t > send(const Handshake_Message &msg)=0
static std::vector< uint8_t > prepare_message(const Handshake_Message_13_Ref message, Transcript_Hash_State &transcript_hash)
Hello_Request(Handshake_IO &io)
const std::vector< uint8_t > & cookie() const
Definition: tls_messages.h:62
virtual bool include_time_in_hello_random() const
Definition: tls_policy.cpp:339
virtual bool allow_tls12() const
Definition: tls_policy.cpp:315
virtual std::vector< uint16_t > ciphersuite_list(Protocol_Version version) const
Definition: tls_policy.cpp:445
virtual std::vector< Group_Params > key_exchange_groups() const
Definition: tls_policy.cpp:157
virtual bool tls_13_middlebox_compatibility_mode() const
Definition: tls_policy.cpp:347
virtual bool negotiate_encrypt_then_mac() const
Definition: tls_policy.cpp:342
virtual bool acceptable_protocol_version(Protocol_Version version) const
Definition: tls_policy.cpp:268
virtual std::vector< uint16_t > srtp_profiles() const
Definition: tls_policy.cpp:367
virtual bool support_cert_status_message() const
Definition: tls_policy.cpp:345
virtual bool hash_hello_random() const
Definition: tls_policy.cpp:348
virtual std::vector< Signature_Scheme > acceptable_signature_schemes() const
Definition: tls_policy.cpp:40
virtual bool use_ecc_point_compression() const
Definition: tls_policy.cpp:122
virtual bool allow_dtls12() const
Definition: tls_policy.cpp:331
virtual std::optional< uint16_t > record_size_limit() const
Definition: tls_policy.cpp:344
std::string to_string() const
Definition: tls_version.cpp:15
uint8_t major_version() const
Definition: tls_version.h:83
uint8_t minor_version() const
Definition: tls_version.h:88
std::string hostname() const
const Server_Information & server_info() const
Definition: tls_session.h:195
bool supports_encrypt_then_mac() const
Definition: tls_session.h:163
Protocol_Version version() const
Definition: tls_session.h:125
const std::vector< uint8_t > & session_ticket() const
Definition: tls_session.h:190
uint16_t ciphersuite_code() const
Definition: tls_session.h:130
const std::vector< uint8_t > & session_id() const
std::vector< uint8_t > get_remaining()
Definition: tls_reader.h:42
std::vector< T > get_range(size_t len_bytes, size_t min_elems, size_t max_elems)
Definition: tls_reader.h:119
std::vector< T > get_fixed(size_t size)
Definition: tls_reader.h:151
std::vector< uint8_t > get_data_read_so_far()
Definition: tls_reader.h:47
std::vector< T > get_range_vector(size_t len_bytes, size_t min_elems, size_t max_elems)
Definition: tls_reader.h:130
@ CLIENT_HELLO
Definition: tls_magic.h:65
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:212
std::vector< uint8_t > make_hello_random(RandomNumberGenerator &rng, Callbacks &cb, const Policy &policy)
@ TLS_EMPTY_RENEGOTIATION_INFO_SCSV
constexpr void store_be(uint16_t in, uint8_t out[2])
Definition: loadstor.h:449
bool value_exists(const std::vector< T > &vec, const T &val)
Definition: stl_util.h:89
MechanismType hash