Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::Hello_Retry_Request Class Referencefinal

#include <tls_messages_13.h>

Inheritance diagram for Botan::TLS::Hello_Retry_Request:
Botan::TLS::Server_Hello_13 Botan::TLS::Server_Hello Botan::TLS::Handshake_Message

Public Member Functions

uint16_t ciphersuite () const
void decline_psk ()
const Extensions & extensions () const
std::optional< Protocol_Version > random_signals_downgrade () const
Protocol_Version selected_version () const final
std::vector< uint8_t > serialize () const override
const Session_ID & session_id () const
Handshake_Type type () const override
std::string type_string () const
Handshake_Type wire_type () const override

Static Public Member Functions

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)
static std::variant< Hello_Retry_Request, Server_Hello_13, Server_Hello_12_Shim > parse (std::span< const uint8_t > buf)

Protected Member Functions

void basic_validation () const
uint8_t compression_method () const
std::set< Extension_Code > extension_types () const
 Hello_Retry_Request (const Client_Hello_13 &ch, Named_Group selected_group, const Policy &policy, Callbacks &cb)
 Hello_Retry_Request (std::unique_ptr< Server_Hello_Internal > data)
Protocol_Version legacy_version () const
const std::vector< uint8_t > & random () const

Protected Attributes

std::unique_ptr< Server_Hello_Internal > m_data

Static Protected Attributes

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
static const struct Botan::TLS::Server_Hello_13::Server_Hello_Tag as_server_hello

Friends

class Server_Hello_13

Detailed Description

Definition at line 148 of file tls_messages_13.h.

Constructor & Destructor Documentation

◆ Hello_Retry_Request() [1/2]

Botan::TLS::Hello_Retry_Request::Hello_Retry_Request ( std::unique_ptr< Server_Hello_Internal > data)
explicitprotected

Definition at line 384 of file msg_server_hello_13.cpp.

384 :
static const struct Botan::TLS::Server_Hello_13::Hello_Retry_Request_Tag as_hello_retry_request

References Botan::TLS::Server_Hello_13::as_hello_retry_request, Hello_Retry_Request(), and Server_Hello_13.

Referenced by Hello_Retry_Request(), and Server_Hello_13.

◆ Hello_Retry_Request() [2/2]

Botan::TLS::Hello_Retry_Request::Hello_Retry_Request ( const Client_Hello_13 & ch,
Named_Group selected_group,
const Policy & policy,
Callbacks & cb )
protected

Definition at line 387 of file msg_server_hello_13.cpp.

390 :
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.
405 BOTAN_STATE_CHECK(ch.extensions().has<Supported_Groups>());
406 BOTAN_STATE_CHECK(ch.extensions().has<Key_Share>());
407
408 BOTAN_STATE_CHECK(!value_exists(ch.extensions().get<Key_Share>()->offered_groups(), selected_group));
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
427 cb.tls_modify_extensions(m_data->extensions(), Connection_Side::Server, type());
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}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
Handshake_Type type() const override
static const struct Botan::TLS::Server_Hello_13::Hello_Retry_Request_Creation_Tag as_new_hello_retry_request
std::unique_ptr< Server_Hello_Internal > m_data
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

References Botan::TLS::Server_Hello_13::as_new_hello_retry_request, BOTAN_STATE_CHECK, Botan::TLS::Client_Hello::extensions(), Botan::TLS::Extensions::get(), Botan::TLS::Extensions::has(), Botan::TLS::HELLO_RETRY_REQUEST_MARKER, Botan::TLS::Server_Hello::m_data, Botan::TLS::Key_Share::offered_groups(), Botan::TLS::Server, Server_Hello_13, Botan::TLS::Server_Hello::session_id(), Botan::TLS::Callbacks::tls_modify_extensions(), type(), and Botan::value_exists().

Member Function Documentation

◆ basic_validation()

void Botan::TLS::Server_Hello_13::basic_validation ( ) const
protectedinherited

Validation that applies to both Server Hello and Hello Retry Request

Definition at line 129 of file msg_server_hello_13.cpp.

129 {
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}
Protocol_Version selected_version() const final
const Extensions & extensions() const
Protocol_Version legacy_version() const
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition exceptn.cpp:13

References Botan::TLS::Server_Hello::compression_method(), Botan::TLS::Server_Hello::extensions(), Botan::TLS::Server_Hello::legacy_version(), selected_version(), and Botan::to_string().

Referenced by Server_Hello_13(), and Server_Hello_13().

◆ ciphersuite()

uint16_t Botan::TLS::Server_Hello::ciphersuite ( ) const
inherited

◆ compression_method()

uint8_t Botan::TLS::Server_Hello::compression_method ( ) const
protectedinherited

Definition at line 139 of file msg_server_hello.cpp.

139 {
140 return m_data->comp_method();
141}

References m_data.

Referenced by Botan::TLS::Server_Hello_13::basic_validation(), and selected_version().

◆ create()

std::variant< Hello_Retry_Request, Server_Hello_13 > Botan::TLS::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 )
staticinherited

Definition at line 28 of file msg_server_hello_13.cpp.

34 {
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}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
Server_Hello_13(std::unique_ptr< Server_Hello_Internal > data, Server_Hello_Tag tag=as_server_hello)
std::vector< Group_Params > groups_usable_in_version(std::span< const Group_Params > groups, Protocol_Version version)

References BOTAN_ASSERT_NOMSG, BOTAN_STATE_CHECK, Botan::TLS::Policy::choose_key_exchange_group(), Botan::TLS::Client_Hello::extensions(), Botan::TLS::Supported_Groups::groups(), Botan::TLS::groups_usable_in_version(), Botan::TLS::Key_Share::offered_groups(), Server_Hello_13(), and Botan::value_exists().

◆ decline_psk()

void Botan::TLS::Server_Hello_13::decline_psk ( )
inherited

Decline the PSK selected in this (not yet sent) Server Hello, so that the handshake continues as a full handshake.

Definition at line 360 of file msg_server_hello_13.cpp.

360 {
361 m_data->extensions().remove_extension(Extension_Code::PresharedKey);
362}

References decline_psk(), Botan::TLS::Server_Hello::m_data, and Botan::TLS::PresharedKey.

Referenced by decline_psk().

◆ extension_types()

std::set< Extension_Code > Botan::TLS::Server_Hello::extension_types ( ) const
protectedinherited

Definition at line 151 of file msg_server_hello.cpp.

151 {
152 return m_data->extensions().extension_types();
153}

References m_data.

Referenced by selected_version().

◆ extensions()

const Extensions & Botan::TLS::Server_Hello::extensions ( ) const
inherited

◆ legacy_version()

Protocol_Version Botan::TLS::Server_Hello::legacy_version ( ) const
protectedinherited

Definition at line 131 of file msg_server_hello.cpp.

131 {
132 return m_data->legacy_version();
133}

References m_data.

Referenced by Botan::TLS::Server_Hello_13::basic_validation(), selected_version(), and Botan::TLS::Server_Hello_12_Shim::selected_version().

◆ parse()

std::variant< Hello_Retry_Request, Server_Hello_13, Server_Hello_12_Shim > Botan::TLS::Server_Hello_13::parse ( std::span< const uint8_t > buf)
staticinherited

Definition at line 86 of file msg_server_hello_13.cpp.

87 {
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}

References Server_Hello_13().

Referenced by Botan::TLS::Handshake_Layer::parse_handshake_message().

◆ random()

const std::vector< uint8_t > & Botan::TLS::Server_Hello::random ( ) const
protectedinherited

Definition at line 135 of file msg_server_hello.cpp.

135 {
136 return m_data->random();
137}

References m_data.

Referenced by selected_version().

◆ random_signals_downgrade()

std::optional< Protocol_Version > Botan::TLS::Server_Hello_13::random_signals_downgrade ( ) const
inherited

Return desired downgrade version indicated by hello random, if any.

Definition at line 364 of file msg_server_hello_13.cpp.

364 {
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}
constexpr uint64_t DOWNGRADE_TLS12
Definition tls_magic.h:130
constexpr uint64_t DOWNGRADE_TLS11
Definition tls_magic.h:119
constexpr auto load_be(ParamTs &&... params)
Definition loadstor.h:504

References Botan::TLS::DOWNGRADE_TLS11, Botan::TLS::DOWNGRADE_TLS12, Botan::load_be(), Botan::TLS::Server_Hello::m_data, and random_signals_downgrade().

Referenced by random_signals_downgrade().

◆ selected_version()

Protocol_Version Botan::TLS::Server_Hello_13::selected_version ( ) const
finalvirtualinherited
Returns
the selected version as indicated by the supported_versions extension

Implements Botan::TLS::Server_Hello.

Definition at line 376 of file msg_server_hello_13.cpp.

376 {
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}

References BOTAN_ASSERT_NOMSG, Botan::TLS::Server_Hello::m_data, and selected_version().

Referenced by basic_validation(), and selected_version().

◆ serialize()

std::vector< uint8_t > Botan::TLS::Server_Hello::serialize ( ) const
overridevirtualinherited

Serialize this handshake message

Implements Botan::TLS::Handshake_Message.

Definition at line 107 of file msg_server_hello.cpp.

107 {
108 std::vector<uint8_t> buf;
109 buf.reserve(1024); // working around GCC warning
110
111 buf.push_back(m_data->legacy_version().major_version());
112 buf.push_back(m_data->legacy_version().minor_version());
113 buf += m_data->random();
114
115 append_tls_length_value(buf, m_data->session_id().get(), 1);
116
117 buf.push_back(get_byte<0>(m_data->ciphersuite()));
118 buf.push_back(get_byte<1>(m_data->ciphersuite()));
119
120 buf.push_back(m_data->comp_method());
121
122 buf += m_data->extensions().serialize(Connection_Side::Server);
123
124 return buf;
125}
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
constexpr uint8_t get_byte(T input)
Definition loadstor.h:79

References Botan::TLS::append_tls_length_value(), Botan::get_byte(), m_data, serialize(), Botan::TLS::Server, and Server_Hello().

Referenced by serialize(), and ~Server_Hello().

◆ session_id()

const Session_ID & Botan::TLS::Server_Hello::session_id ( ) const
inherited

◆ type()

Handshake_Type Botan::TLS::Hello_Retry_Request::type ( ) const
inlineoverridevirtual

Return the TLS handshake type code

Returns
the message type

Implements Botan::TLS::Handshake_Message.

Definition at line 155 of file tls_messages_13.h.

References Botan::TLS::HelloRetryRequest.

Referenced by Hello_Retry_Request().

◆ type_string()

std::string Botan::TLS::Handshake_Message::type_string ( ) const
inherited

Return a free-form string describing this message type

Returns
string representation of this message type

Definition at line 22 of file tls_handshake_state.cpp.

22 {
24}
virtual Handshake_Type type() const =0
const char * handshake_type_to_string(Handshake_Type type)
Definition tls_magic.cpp:15

References Botan::TLS::handshake_type_to_string(), and type().

◆ wire_type()

Handshake_Type Botan::TLS::Hello_Retry_Request::wire_type ( ) const
inlineoverridevirtual

Return the wire encoding of the message type code

Note
This is usually equal to type with the exception of a TLS 1.3 Helloy Retry Request.
Returns
the wire representation of the message's type

Reimplemented from Botan::TLS::Handshake_Message.

Definition at line 157 of file tls_messages_13.h.

References Botan::TLS::ServerHello.

◆ Server_Hello_13

friend class Server_Hello_13
friend

Member Data Documentation

◆ as_hello_retry_request

const Server_Hello_13::Hello_Retry_Request_Tag Botan::TLS::Server_Hello_13::as_hello_retry_request
staticprotectedinherited

◆ as_new_hello_retry_request

const Server_Hello_13::Hello_Retry_Request_Creation_Tag Botan::TLS::Server_Hello_13::as_new_hello_retry_request
staticprotectedinherited

◆ as_server_hello

const Server_Hello_13::Server_Hello_Tag Botan::TLS::Server_Hello_13::as_server_hello
staticprotectedinherited

Definition at line 24 of file msg_server_hello_13.cpp.

◆ m_data


The documentation for this class was generated from the following files: