Botan 3.14.1
Crypto and TLS for C&
msg_server_hello_13.cpp
Go to the documentation of this file.
1/*
2* TLS Server Hello and Server Hello Done
3* (C) 2004-2011,2015,2016,2019 Jack Lloyd
4* 2021 Elektrobit Automotive GmbH
5* 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
6* 2026 René Meusel - Rohde & Schwarz Cybersecurity GmbH
7*
8* Botan is released under the Simplified BSD License (see license.txt)
9*/
10
11#include <botan/tls_messages_13.h>
12
13#include <botan/tls_alert.h>
14#include <botan/tls_callbacks.h>
15#include <botan/tls_exceptn.h>
16#include <botan/tls_extensions_13.h>
17#include <botan/tls_policy.h>
18#include <botan/internal/loadstor.h>
19#include <botan/internal/stl_util.h>
20#include <botan/internal/tls_messages_internal.h>
21
22namespace Botan::TLS {
23
24const Server_Hello_13::Server_Hello_Tag Server_Hello_13::as_server_hello;
25const Server_Hello_13::Hello_Retry_Request_Tag Server_Hello_13::as_hello_retry_request;
26const Server_Hello_13::Hello_Retry_Request_Creation_Tag Server_Hello_13::as_new_hello_retry_request;
27
28std::variant<Hello_Retry_Request, Server_Hello_13> Server_Hello_13::create(const Client_Hello_13& ch,
29 bool hello_retry_request_allowed,
30 Session_Manager& session_mgr,
31 Credentials_Manager& credentials_mgr,
33 const Policy& policy,
34 Callbacks& cb) {
35 const auto& exts = ch.extensions();
36
37 // RFC 8446 4.2.9
38 // [With PSK with (EC)DHE key establishment], the client and server MUST
39 // supply "key_share" values [...].
40 //
41 // Note: We currently do not support PSK without (EC)DHE, hence, we can
42 // assume that those extensions are available.
43 BOTAN_ASSERT_NOMSG(exts.has<Supported_Groups>() && exts.has<Key_Share>());
44 const auto supported_by_client =
45 groups_usable_in_version(exts.get<Supported_Groups>()->groups(), Protocol_Version::TLS_V13);
46 const auto offered_by_client =
47 groups_usable_in_version(exts.get<Key_Share>()->offered_groups(), Protocol_Version::TLS_V13);
48 const auto selected_group = policy.choose_key_exchange_group(supported_by_client, offered_by_client);
49
50 // RFC 8446 4.1.1
51 // If there is no overlap between the received "supported_groups" and the
52 // groups supported by the server, then the server MUST abort the
53 // handshake with a "handshake_failure" or an "insufficient_security" alert.
54 if(selected_group == Named_Group::NONE) {
55 throw TLS_Exception(Alert::HandshakeFailure, "Client did not offer any acceptable group");
56 }
57
58 // RFC 8446 4.2.8:
59 // Servers MUST NOT send a KeyShareEntry for any group not indicated in the
60 // client's "supported_groups" extension [...]
61 if(!value_exists(supported_by_client, selected_group)) {
62 throw TLS_Exception(Alert::InternalError, "Application selected a group that is not supported by the client");
63 }
64
65 // RFC 8446 4.1.4
66 // The server will send this message in response to a ClientHello
67 // message if it is able to find an acceptable set of parameters but the
68 // ClientHello does not contain sufficient information to proceed with
69 // the handshake.
70 //
71 // In this case, the Client Hello did not contain a key share offer for
72 // the group selected by the application.
73 if(!value_exists(offered_by_client, selected_group)) {
74 // RFC 8446 4.1.4
75 // If a client receives a second HelloRetryRequest in the same
76 // connection (i.e., where the ClientHello was itself in response to a
77 // HelloRetryRequest), it MUST abort the handshake with an
78 // "unexpected_message" alert.
79 BOTAN_STATE_CHECK(hello_retry_request_allowed);
80 return Hello_Retry_Request(ch, selected_group, policy, cb);
81 } else {
82 return Server_Hello_13(ch, selected_group, session_mgr, credentials_mgr, rng, cb, policy);
83 }
84}
85
86std::variant<Hello_Retry_Request, Server_Hello_13, Server_Hello_12_Shim> Server_Hello_13::parse(
87 std::span<const uint8_t> buf) {
88 auto data = std::make_unique<Server_Hello_Internal>(buf);
89
90 // RFC 8446 4.1.3
91 // Upon receiving a message with type server_hello, implementations MUST
92 // first examine the Random value and, if it matches this value, process
93 // it as described in Section 4.1.4.
94 //
95 // Hello_Retry_Request validates that it selects TLS 1.3
96 if(data->is_hello_retry_request()) {
97 return Hello_Retry_Request(std::move(data));
98 }
99
100 const auto version = data->version();
101
102 if(version.is_pre_tls_13()) {
103 return Server_Hello_12_Shim(std::move(data));
104 }
105
106 if(version == Protocol_Version::TLS_V13) {
107 return Server_Hello_13(std::move(data));
108 }
109
110 throw TLS_Exception(Alert::ProtocolVersion, "unexpected server hello version: " + version.to_string());
111}
112
113namespace {
114
115// RFC 8446 4.2
116// If an implementation receives an extension which it recognizes and which
117// is not specified for the message in which it appears, it MUST abort the
118// handshake with an "illegal_parameter" alert.
119Alert::Type disallowed_extension_alert(const Extensions& exts, const std::set<Extension_Code>& allowed) {
120 return exts.contains_implemented_extensions_other_than(allowed) ? Alert::IllegalParameter
121 : Alert::UnsupportedExtension;
122}
123
124} // namespace
125
126/**
127 * Validation that applies to both Server Hello and Hello Retry Request
128 */
130 // Note: checks that cannot be performed without contextual information
131 // are done in the specific TLS client implementation.
132 // Note: The Supported_Version extension makes sure internally that
133 // exactly one entry is provided.
134
135 // Note: Hello Retry Request basic validation is equivalent with the
136 // basic validations required for Server Hello
137 //
138 // RFC 8446 4.1.4
139 // Upon receipt of a HelloRetryRequest, the client MUST check the
140 // legacy_version, [...], and legacy_compression_method as specified in
141 // Section 4.1.3 and then process the extensions, starting with determining
142 // the version using "supported_versions".
143
144 // RFC 8446 4.1.3
145 // In TLS 1.3, [...] the legacy_version field MUST be set to 0x0303
146 if(legacy_version() != Protocol_Version::TLS_V12) {
147 throw TLS_Exception(Alert::ProtocolVersion,
148 "legacy_version '" + legacy_version().to_string() + "' is not allowed");
149 }
150
151 // RFC 8446 4.1.3
152 // legacy_compression_method: A single byte which MUST have the value 0.
153 if(compression_method() != 0x00) {
154 throw TLS_Exception(Alert::DecodeError, "compression is not supported in TLS 1.3");
155 }
156
157 // RFC 8446 4.1.3
158 // All TLS 1.3 ServerHello messages MUST contain the "supported_versions" extension.
159 if(!extensions().has<Supported_Versions>()) {
160 throw TLS_Exception(Alert::MissingExtension, "server hello did not contain 'supported version' extension");
161 }
162
163 // RFC 8446 4.2.1
164 // A server which negotiates TLS 1.3 MUST respond by sending
165 // a "supported_versions" extension containing the selected version
166 // value (0x0304).
167 if(selected_version() != Protocol_Version::TLS_V13) {
168 throw TLS_Exception(Alert::IllegalParameter, "TLS 1.3 Server Hello selected a different version");
169 }
170}
171
172Server_Hello_13::Server_Hello_13(std::unique_ptr<Server_Hello_Internal> data,
173 Server_Hello_13::Server_Hello_Tag /*tag*/) :
174 Server_Hello(std::move(data)) {
175 BOTAN_ASSERT_NOMSG(!m_data->is_hello_retry_request());
177
178 const auto& exts = extensions();
179
180 // RFC 8446 4.1.3
181 // The ServerHello MUST only include extensions which are required to
182 // establish the cryptographic context and negotiate the protocol version.
183 // [...]
184 // Other extensions (see Section 4.2) are sent separately in the
185 // EncryptedExtensions message.
186 //
187 // Note that further validation dependent on the client hello is done in the
188 // TLS client implementation.
189 const std::set<Extension_Code> allowed = {
193 };
194
195 // As the ServerHello shall only contain essential extensions, we don't give
196 // any slack for extensions not implemented by Botan here.
197 if(exts.contains_other_than(allowed)) {
198 throw TLS_Exception(disallowed_extension_alert(exts, allowed),
199 "Server Hello contained an extension that is not allowed");
200 }
201
202 // RFC 8446 4.1.3
203 // Current ServerHello messages additionally contain
204 // either the "pre_shared_key" extension or the "key_share"
205 // extension, or both [...].
206 if(!exts.has<Key_Share>() && !exts.has<PSK>()) {
207 throw TLS_Exception(Alert::MissingExtension, "server hello must contain key exchange information");
208 }
209}
210
211Server_Hello_13::Server_Hello_13(std::unique_ptr<Server_Hello_Internal> data,
212 Server_Hello_13::Hello_Retry_Request_Tag /*tag*/) :
213 Server_Hello(std::move(data)) {
214 BOTAN_ASSERT_NOMSG(m_data->is_hello_retry_request());
216
217 const auto& exts = extensions();
218
219 // RFC 8446 4.1.4
220 // The HelloRetryRequest extensions defined in this specification are:
221 // - supported_versions (see Section 4.2.1)
222 // - cookie (see Section 4.2.2)
223 // - key_share (see Section 4.2.8)
224 const std::set<Extension_Code> allowed = {
228 };
229
230 // As the Hello Retry Request shall only contain essential extensions, we
231 // don't give any slack for extensions not implemented by Botan here.
232 if(exts.contains_other_than(allowed)) {
233 throw TLS_Exception(disallowed_extension_alert(exts, allowed),
234 "Hello Retry Request contained an extension that is not allowed");
235 }
236
237 // RFC 8446 4.1.4
238 // Clients MUST abort the handshake with an "illegal_parameter" alert if
239 // the HelloRetryRequest would not result in any change in the ClientHello.
240 if(!exts.has<Key_Share>() && !exts.has<Cookie>()) {
241 throw TLS_Exception(Alert::IllegalParameter, "Hello Retry Request does not request any changes to Client Hello");
242 }
243}
244
245Server_Hello_13::Server_Hello_13(std::unique_ptr<Server_Hello_Internal> data,
246 Hello_Retry_Request_Creation_Tag /*tag*/) :
247 Server_Hello(std::move(data)) {}
248
249namespace {
250
251uint16_t choose_ciphersuite(const Client_Hello_13& ch, const Policy& policy) {
252 auto pref_list = ch.ciphersuites();
253 // TODO: DTLS might need to make this version dynamic
254 auto other_list = policy.ciphersuite_list(Protocol_Version::TLS_V13);
255
257 std::swap(pref_list, other_list);
258 }
259
260 for(const auto suite_id : pref_list) {
261 // TODO: take potentially available PSKs into account to select a
262 // compatible ciphersuite.
263 //
264 // Assuming the client sent one or more PSKs, we would first need to find
265 // the hash functions they are associated to. For session tickets, that
266 // would mean decrypting the ticket and comparing the cipher suite used in
267 // those tickets. For (currently not yet supported) pre-assigned PSKs, the
268 // hash function needs to be specified along with them.
269 //
270 // Then we could refine the ciphersuite selection using the required hash
271 // function for the PSK(s) we are wishing to use down the road.
272 //
273 // For now, we just negotiate the cipher suite blindly and hope for the
274 // best. As long as PSKs are used for session resumption only, this has a
275 // high chance of success. Previous handshakes with this client have very
276 // likely selected the same ciphersuite anyway.
277 //
278 // See also RFC 8446 4.2.11
279 // When session resumption is the primary use case of PSKs, the most
280 // straightforward way to implement the PSK/cipher suite matching
281 // requirements is to negotiate the cipher suite first [...].
282 if(value_exists(other_list, suite_id)) {
283 return suite_id;
284 }
285 }
286
287 // RFC 8446 4.1.1
288 // If the server is unable to negotiate a supported set of parameters
289 // [...], it MUST abort the handshake with either a "handshake_failure"
290 // or "insufficient_security" fatal alert [...].
291 throw TLS_Exception(Alert::HandshakeFailure, "Can't agree on a ciphersuite with client");
292}
293} // namespace
294
296 std::optional<Named_Group> key_exchange_group,
297 Session_Manager& session_mgr,
298 Credentials_Manager& credentials_mgr,
300 Callbacks& cb,
301 const Policy& policy) :
302 Server_Hello(std::make_unique<Server_Hello_Internal>(
304 ch.session_id(),
306 choose_ciphersuite(ch, policy),
307 uint8_t(0) /* compression method */
308 )) {
309 // RFC 8446 4.2.1
310 // A server which negotiates TLS 1.3 MUST respond by sending a
311 // "supported_versions" extension containing the selected version
312 // value (0x0304). It MUST set the ServerHello.legacy_version field to
313 // 0x0303 (TLS 1.2).
314 //
315 // Note that the legacy version (TLS 1.2) is set in this constructor's
316 // initializer list, accordingly.
317 m_data->extensions().add(new Supported_Versions(Protocol_Version::TLS_V13)); // NOLINT(*-owning-memory)
318
319 if(key_exchange_group.has_value()) {
320 BOTAN_ASSERT_NOMSG(ch.extensions().has<Key_Share>());
321 m_data->extensions().add(Key_Share::create_as_encapsulation(
322 key_exchange_group.value(), *ch.extensions().get<Key_Share>(), policy, cb, rng));
323 }
324
325 const auto& ch_exts = ch.extensions();
326
327 if(ch_exts.has<PSK>()) {
328 const auto cs = Ciphersuite::by_id(m_data->ciphersuite());
329 BOTAN_ASSERT_NOMSG(cs);
330
331 // RFC 8446 4.2.9
332 // A client MUST provide a "psk_key_exchange_modes" extension if it
333 // offers a "pre_shared_key" extension.
334 //
335 // Note: Client_Hello_13 constructor already performed a graceful check.
336 const auto* const psk_modes = ch_exts.get<PSK_Key_Exchange_Modes>();
337 BOTAN_ASSERT_NONNULL(psk_modes);
338
339 // TODO: also support PSK_Key_Exchange_Mode::PSK_KE
340 // (PSK-based handshake without an additional ephemeral key exchange)
341 if(value_exists(psk_modes->modes(), PSK_Key_Exchange_Mode::PSK_DHE_KE)) {
342 if(auto server_psk = ch_exts.get<PSK>()->select_offered_psk(
343 ch.sni_hostname(), cs.value(), session_mgr, credentials_mgr, cb, policy)) {
344 // RFC 8446 4.2.11
345 // In order to accept PSK key establishment, the server sends a
346 // "pre_shared_key" extension indicating the selected identity.
347 m_data->extensions().add(std::move(server_psk));
348 }
349 }
350 }
351
352 cb.tls_modify_extensions(m_data->extensions(), Connection_Side::Server, type());
353
354 if(!m_data->extensions().has<Key_Share>()) {
355 throw TLS_Exception(Alert::InternalError,
356 "Application tls_modify_extensions callback removed Key_Share from the ServerHello");
357 }
358}
359
361 m_data->extensions().remove_extension(Extension_Code::PresharedKey);
362}
363
364std::optional<Protocol_Version> Server_Hello_13::random_signals_downgrade() const {
365 const uint64_t last8 = load_be<uint64_t>(m_data->random().data(), 3);
366 if(last8 == DOWNGRADE_TLS11) {
367 return Protocol_Version::TLS_V11;
368 }
369 if(last8 == DOWNGRADE_TLS12) {
370 return Protocol_Version::TLS_V12;
371 }
372
373 return std::nullopt;
374}
375
377 const auto* const versions_ext = m_data->extensions().get<Supported_Versions>();
378 BOTAN_ASSERT_NOMSG(versions_ext);
379 const auto& versions = versions_ext->versions();
380 BOTAN_ASSERT_NOMSG(versions.size() == 1);
381 return versions.front();
382}
383
384Hello_Retry_Request::Hello_Retry_Request(std::unique_ptr<Server_Hello_Internal> data) :
386
388 Named_Group selected_group,
389 const Policy& policy,
390 Callbacks& cb) :
391 Server_Hello_13(std::make_unique<Server_Hello_Internal>(
392 Protocol_Version::TLS_V12 /* legacy_version */,
393 ch.session_id(),
394 std::vector<uint8_t>(HELLO_RETRY_REQUEST_MARKER.begin(), HELLO_RETRY_REQUEST_MARKER.end()),
395 choose_ciphersuite(ch, policy),
396 uint8_t(0) /* compression method */,
397 true /* is Hello Retry Request */
398 ),
400 // RFC 8446 4.1.4
401 // As with the ServerHello, a HelloRetryRequest MUST NOT contain any
402 // extensions that were not first offered by the client in its
403 // ClientHello, with the exception of optionally the "cookie" [...]
404 // extension.
407
409
410 // RFC 8446 4.1.4
411 // The server's extensions MUST contain "supported_versions".
412 //
413 // RFC 8446 4.2.1
414 // A server which negotiates TLS 1.3 MUST respond by sending a
415 // "supported_versions" extension containing the selected version
416 // value (0x0304). It MUST set the ServerHello.legacy_version field to
417 // 0x0303 (TLS 1.2).
418 //
419 // Note that the legacy version (TLS 1.2) is set in this constructor's
420 // initializer list, accordingly.
421 // NOLINTBEGIN(*-owning-memory)
422 m_data->extensions().add(new Supported_Versions(Protocol_Version::TLS_V13));
423
424 m_data->extensions().add(new Key_Share(selected_group));
425 // NOLINTEND(*-owning-memory)
426
428
429 if(!m_data->extensions().has<Key_Share>()) {
430 throw TLS_Exception(Alert::InternalError,
431 "Application tls_modify_extensions callback removed Key_Share from the HelloRetryRequest");
432 }
433}
434
435} // namespace Botan::TLS
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
AlertType Type
Definition tls_alert.h:73
virtual void tls_modify_extensions(Extensions &extn, Connection_Side which_side, Handshake_Type which_message)
const Extensions & extensions() const
const std::vector< uint16_t > & ciphersuites() const
bool contains_implemented_extensions_other_than(const std::set< Extension_Code > &allowed_extensions) const
Hello_Retry_Request(std::unique_ptr< Server_Hello_Internal > data)
Handshake_Type type() const override
std::vector< Named_Group > offered_groups() const
virtual std::vector< uint16_t > ciphersuite_list(Protocol_Version version) const
virtual bool server_uses_own_ciphersuite_preferences() const
virtual Group_Params choose_key_exchange_group(const std::vector< Group_Params > &supported_by_peer, const std::vector< Group_Params > &offered_by_peer) const
static std::variant< Hello_Retry_Request, Server_Hello_13, Server_Hello_12_Shim > parse(std::span< const uint8_t > buf)
static const struct Botan::TLS::Server_Hello_13::Hello_Retry_Request_Tag as_hello_retry_request
static const struct Botan::TLS::Server_Hello_13::Hello_Retry_Request_Creation_Tag as_new_hello_retry_request
Server_Hello_13(std::unique_ptr< Server_Hello_Internal > data, Server_Hello_Tag tag=as_server_hello)
std::optional< Protocol_Version > random_signals_downgrade() const
static std::variant< Hello_Retry_Request, Server_Hello_13 > create(const Client_Hello_13 &ch, bool hello_retry_request_allowed, Session_Manager &session_mgr, Credentials_Manager &credentials_mgr, RandomNumberGenerator &rng, const Policy &policy, Callbacks &cb)
Protocol_Version selected_version() const final
static const struct Botan::TLS::Server_Hello_13::Server_Hello_Tag as_server_hello
Server_Hello(const Server_Hello &)=delete
const Session_ID & session_id() const
std::unique_ptr< Server_Hello_Internal > m_data
const Extensions & extensions() const
Protocol_Version legacy_version() const
const std::vector< Group_Params > & groups() const
std::vector< uint8_t > make_server_hello_random(RandomNumberGenerator &rng, Protocol_Version offered_version, Callbacks &cb, const Policy &policy, TLS_Flavor flavor)
constexpr uint64_t DOWNGRADE_TLS12
Definition tls_magic.h:130
std::vector< Group_Params > groups_usable_in_version(std::span< const Group_Params > groups, Protocol_Version version)
Group_Params Named_Group
constexpr uint64_t DOWNGRADE_TLS11
Definition tls_magic.h:119
constexpr std::array< uint8_t, 32 > HELLO_RETRY_REQUEST_MARKER
Definition tls_magic.h:138
bool value_exists(const std::vector< T > &vec, const V &val)
Definition stl_util.h:44
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition exceptn.cpp:13
constexpr auto load_be(ParamTs &&... params)
Definition loadstor.h:504