Botan 3.14.1
Crypto and TLS for C&
tls_messages_13.h
Go to the documentation of this file.
1/*
2* TLS Messages
3* (C) 2021-2022 Jack Lloyd
4* 2021 Elektrobit Automotive GmbH
5* 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#ifndef BOTAN_TLS_MESSAGES_13_H_
11#define BOTAN_TLS_MESSAGES_13_H_
12
13#include <botan/tls_extensions.h>
14#include <botan/tls_external_psk.h>
15#include <botan/tls_messages.h>
16#include <chrono>
17
18namespace Botan {
19
20enum class Usage_Type : uint8_t;
22
23} // namespace Botan
24
25namespace Botan::TLS {
26
28class Client_Hello_12;
29
31 public:
32 /**
33 * Creates a client hello which might optionally use the passed-in
34 * @p session for resumption. In that case, this will "extract" the
35 * master secret from the passed-in @p session.
36 */
37 Client_Hello_13(const Policy& policy,
38 Callbacks& cb,
40 std::string_view hostname,
41 std::vector<std::string> next_protocols,
42 std::optional<Session_with_Handle>& session,
43 std::vector<ExternalPSK> psks,
44 TLS_Flavor flavor);
45
46 static std::variant<Client_Hello_13, Client_Hello_12_Shim> parse(std::span<const uint8_t> buf);
47
48 void retry(const Hello_Retry_Request& hrr,
49 const Transcript_Hash_State& transcript_hash_state,
50 Callbacks& cb,
52
53 /**
54 * Select the highest protocol version from the list of versions
55 * supported by the client. If no such version can be determined this
56 * returns std::nullopt.
57 */
58 std::optional<Protocol_Version> highest_supported_version(const Policy& policy) const;
59
60 /**
61 * This validates that a Client Hello received after sending a Hello
62 * Retry Request was updated in accordance with RFC 8446 4.1.2. If issues
63 * are found, this method throws accordingly.
64 */
65 void validate_updates(const Client_Hello_13& new_ch);
66
67 private:
68 explicit Client_Hello_13(std::unique_ptr<Client_Hello_Internal> data);
69
70#if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT)
71 // This lets the TLS 1.2 implementation extract the internal data
72 // from this Client Hello object for downgrade purposes.
73 friend class Client_Hello_12;
74#endif
75
76 /**
77 * If the Client Hello contains a PSK extensions with identities this will
78 * generate the PSK binders as described in RFC 8446 4.2.11.2.
79 * Note that the passed in \p transcript_hash_state might be virgin for
80 * the initial Client Hello and should be primed with ClientHello1 and
81 * HelloRetryRequest for an updated Client Hello.
82 */
83 void calculate_psk_binders(Transcript_Hash_State transcript_hash_state);
84};
85
87
89 protected:
90 static const struct Server_Hello_Tag {
92
93 static const struct Hello_Retry_Request_Tag {
95
96 static const struct Hello_Retry_Request_Creation_Tag {
98
99 // These constructors are meant for instantiating Server Hellos
100 // after parsing a peer's message. They perform basic validation
101 // and are therefore not suitable for constructing a message to
102 // be sent to a client.
103 explicit Server_Hello_13(std::unique_ptr<Server_Hello_Internal> data, Server_Hello_Tag tag = as_server_hello);
104 explicit Server_Hello_13(std::unique_ptr<Server_Hello_Internal> data, Hello_Retry_Request_Tag tag);
105 void basic_validation() const;
106
107 // Instantiate a Server Hello as response to a client's Client Hello
108 // (called from Server_Hello_13::create())
110 std::optional<Named_Group> key_exchange_group,
111 Session_Manager& session_mgr,
112 Credentials_Manager& credentials_mgr,
114 Callbacks& cb,
115 const Policy& policy);
116
117 explicit Server_Hello_13(std::unique_ptr<Server_Hello_Internal> data, Hello_Retry_Request_Creation_Tag tag);
118
119 public:
120 static std::variant<Hello_Retry_Request, Server_Hello_13> create(const Client_Hello_13& ch,
121 bool hello_retry_request_allowed,
122 Session_Manager& session_mgr,
123 Credentials_Manager& credentials_mgr,
125 const Policy& policy,
126 Callbacks& cb);
127
128 static std::variant<Hello_Retry_Request, Server_Hello_13, Server_Hello_12_Shim> parse(
129 std::span<const uint8_t> buf);
130
131 /**
132 * Decline the PSK selected in this (not yet sent) Server Hello, so that
133 * the handshake continues as a full handshake.
134 */
135 void decline_psk();
136
137 /**
138 * Return desired downgrade version indicated by hello random, if any.
139 */
140 std::optional<Protocol_Version> random_signals_downgrade() const;
141
142 /**
143 * @returns the selected version as indicated by the supported_versions extension
144 */
146};
147
149 protected:
150 friend class Server_Hello_13; // to allow construction by Server_Hello_13::parse() and ::create()
151 explicit Hello_Retry_Request(std::unique_ptr<Server_Hello_Internal> data);
152 Hello_Retry_Request(const Client_Hello_13& ch, Named_Group selected_group, const Policy& policy, Callbacks& cb);
153
154 public:
156
158};
159
161 public:
162 explicit Encrypted_Extensions(std::span<const uint8_t> buf);
163 Encrypted_Extensions(const Client_Hello_13& client_hello,
164 const Policy& policy,
165 Callbacks& cb,
166 bool is_resumption,
167 bool requesting_client_auth);
168
170
171 const Extensions& extensions() const { return m_extensions; }
172
173 std::vector<uint8_t> serialize() const override;
174
175 private:
176 Extensions m_extensions;
177};
178
179class Certificate_Request_13;
180
181/**
182* Certificate Message of TLS 1.3
183*/
185 public:
187 public:
188 Certificate_Entry(TLS_Data_Reader& reader, Connection_Side side, Certificate_Type cert_type, bool is_leaf);
189 explicit Certificate_Entry(const X509_Certificate& cert);
190 explicit Certificate_Entry(std::shared_ptr<Public_Key> raw_public_key);
191
192 bool has_certificate() const { return m_certificate != nullptr; }
193
194 const X509_Certificate& certificate() const;
195 std::shared_ptr<const Public_Key> public_key() const;
196
197 std::vector<uint8_t> serialize() const;
198
199 Extensions& extensions() { return m_extensions; }
200
201 const Extensions& extensions() const { return m_extensions; }
202
203 Certificate_Entry(const Certificate_Entry& other) = delete;
205
208
210
211 private:
212 std::unique_ptr<X509_Certificate> m_certificate; // possibly null if raw public key in use
213 std::shared_ptr<Public_Key> m_raw_public_key; // null for a non-leaf certificate sent by the peer
214 Extensions m_extensions;
215 };
216
217 public:
219
220 std::vector<X509_Certificate> cert_chain() const;
221
222 bool has_certificate_chain() const;
223 bool is_raw_public_key() const;
224
225 size_t count() const { return m_entries.size(); }
226
227 bool empty() const { return m_entries.empty(); }
228
229 std::shared_ptr<const Public_Key> public_key() const;
230 const X509_Certificate& leaf() const;
231
232 const std::vector<uint8_t>& request_context() const { return m_request_context; }
233
234 /**
235 * Create a Client Certificate message
236 * ... in response to a Certificate Request message.
237 */
238 Certificate_13(const Certificate_Request_13& cert_request,
239 std::string_view hostname,
240 Credentials_Manager& credentials_manager,
241 Callbacks& callbacks,
242 Certificate_Type cert_type);
243
244 /**
245 * Create a Server Certificate message
246 * ... in response to a Client Hello indicating the need to authenticate
247 * with a server certificate.
248 */
249 Certificate_13(const Client_Hello_13& client_hello,
250 Credentials_Manager& credentials_manager,
251 Callbacks& callbacks,
252 Certificate_Type cert_type);
253
254 /**
255 * Deserialize a Certificate message
256 * @param buf the serialized message
257 * @param policy the TLS policy
258 * @param side is this a Connection_Side::Server or Connection_Side::Client certificate message
259 * @param cert_type is the certificate type that was negotiated during the handshake
260 */
261 Certificate_13(std::span<const uint8_t> buf,
262 const Policy& policy,
263 Connection_Side side,
264 Certificate_Type cert_type);
265
266 /**
267 * Validate a Certificate message regarding what extensions are expected based on
268 * previous handshake messages. Also call the tls_examine_extensions() callback
269 * for each entry.
270 *
271 * @param requested_extensions Extensions of Client_Hello or Certificate_Request messages
272 * @param cb Callback that will be called for each extension.
273 */
274 void validate_extensions(const std::set<Extension_Code>& requested_extensions, Callbacks& cb) const;
275
276 /**
277 * Verify the certificate chain
278 *
279 * @throws if verification fails.
280 */
281 void verify(Callbacks& callbacks,
282 const Policy& policy,
283 Credentials_Manager& creds,
284 std::string_view hostname,
285 bool use_ocsp) const;
286
287 std::vector<uint8_t> serialize() const override;
288
289 private:
290 void setup_entries(std::vector<X509_Certificate> cert_chain,
292 Callbacks& callbacks);
293 void setup_entry(std::shared_ptr<Public_Key> raw_public_key, Callbacks& callbacks);
294
295 void verify_certificate_chain(Callbacks& callbacks,
296 const Policy& policy,
297 Credentials_Manager& creds,
298 std::string_view hostname,
299 bool use_ocsp,
300 Usage_Type usage_type) const;
301
302 private:
303 std::vector<uint8_t> m_request_context;
304 std::vector<Certificate_Entry> m_entries;
305 Connection_Side m_side;
306};
307
309 public:
310 Handshake_Type type() const override;
311
312 Certificate_Request_13(std::span<const uint8_t> buf, Connection_Side side);
313
314 //! Creates a Certificate_Request message if it is required by the configuration
315 //! @return std::nullopt if configuration does not require client authentication
316 static std::optional<Certificate_Request_13> maybe_create(const Client_Hello_13& sni_hostname,
317 Credentials_Manager& cred_mgr,
318 Callbacks& callbacks,
319 const Policy& policy);
320
321 std::vector<X509_DN> acceptable_CAs() const;
322 const std::vector<Signature_Scheme>& signature_schemes() const;
323 const std::vector<Signature_Scheme>& certificate_signature_schemes() const;
324
325 const Extensions& extensions() const { return m_extensions; }
326
327 std::vector<uint8_t> serialize() const override;
328
329 const std::vector<uint8_t>& context() const { return m_context; }
330
331 private:
332 Certificate_Request_13(std::vector<X509_DN> acceptable_CAs, const Policy& policy, Callbacks& callbacks);
333
334 private:
335 std::vector<uint8_t> m_context;
336 Extensions m_extensions;
337};
338
339/**
340* Certificate Verify Message
341*/
343 public:
344 /**
345 * Deserialize a Certificate message
346 * @param buf the serialized message
347 * @param side is this a Connection_Side::Server or Connection_Side::Client certificate message
348 */
349 Certificate_Verify_13(std::span<const uint8_t> buf, Connection_Side side);
350
351 Certificate_Verify_13(const Certificate_13& certificate_message,
352 const std::vector<Signature_Scheme>& peer_allowed_schemes,
353 std::string_view hostname,
354 const Transcript_Hash& hash,
355 Connection_Side whoami,
356 Credentials_Manager& creds_mgr,
357 const Policy& policy,
358 Callbacks& callbacks,
360
361 bool verify(const Public_Key& public_key, Callbacks& callbacks, const Transcript_Hash& transcript_hash) const;
362
363 private:
364 Connection_Side m_side;
365};
366
368 public:
369 using Finished::Finished;
370 Finished_13(Cipher_State* cipher_state, const Transcript_Hash& transcript_hash);
371
372 bool verify(Cipher_State* cipher_state, const Transcript_Hash& transcript_hash) const;
373};
374
376 public:
378
380 const Session& session,
381 const Session_Handle& handle,
382 Callbacks& callbacks);
383
384 New_Session_Ticket_13(std::span<const uint8_t> buf, Connection_Side from);
385
386 std::vector<uint8_t> serialize() const override;
387
388 const Extensions& extensions() const { return m_extensions; }
389
390 const Opaque_Session_Handle& handle() const { return m_handle; }
391
392 const Ticket_Nonce& nonce() const { return m_ticket_nonce; }
393
394 uint32_t ticket_age_add() const { return m_ticket_age_add; }
395
396 std::chrono::seconds lifetime_hint() const { return m_ticket_lifetime_hint; }
397
398 /**
399 * @return the number of bytes allowed for early data or std::nullopt
400 * when early data is not allowed at all
401 */
402 std::optional<uint32_t> early_data_byte_limit() const;
403
404 private:
405 // RFC 8446 4.6.1
406 // Clients MUST NOT cache tickets for longer than 7 days, regardless of
407 // the ticket_lifetime, and MAY delete tickets earlier based on local
408 // policy. A server MAY treat a ticket as valid for a shorter period
409 // of time than what is stated in the ticket_lifetime.
410 //
411 // ... hence we call it 'lifetime hint'.
412 std::chrono::seconds m_ticket_lifetime_hint{};
413 uint32_t m_ticket_age_add;
414 Ticket_Nonce m_ticket_nonce;
415 Opaque_Session_Handle m_handle;
416 Extensions m_extensions;
417};
418
420 public:
421 Handshake_Type type() const override { return Handshake_Type::KeyUpdate; }
422
423 explicit Key_Update(bool request_peer_update);
424 explicit Key_Update(std::span<const uint8_t> buf);
425
426 std::vector<uint8_t> serialize() const override;
427
428 bool expects_reciprocation() const { return m_update_requested; }
429
430 private:
431 bool m_update_requested;
432};
433
434namespace detail {
435template <typename T>
437
438template <typename... AlternativeTs>
439struct as_wrapped_references<std::variant<AlternativeTs...>> {
440 using type = std::variant<std::reference_wrapper<AlternativeTs>...>;
441};
442
443template <typename T>
445} // namespace detail
446
447// Handshake message types from RFC 8446 4.
453 // End_Of_Early_Data,
460
461using Post_Handshake_Message_13 = std::variant<New_Session_Ticket_13, Key_Update>;
462
463// Key_Update is handled generically by the Channel. The messages assigned
464// to those variants are the ones that need to be handled by the specific
465// client and/or server implementations.
466using Server_Post_Handshake_13_Message = std::variant<New_Session_Ticket_13, Key_Update>;
467using Client_Post_Handshake_13_Message = std::variant<Key_Update>;
468
470 Server_Hello_12_Shim, // indicates a TLS version downgrade
478
480 std::variant<Client_Hello_13,
481 Client_Hello_12_Shim, // indicates a TLS peer that does not offer TLS 1.3
486
487} // namespace Botan::TLS
488
489#endif
#define BOTAN_UNSTABLE_API
Definition api.h:34
Certificate_Entry & operator=(const Certificate_Entry &other)=delete
const Extensions & extensions() const
Extensions & extensions()
Certificate_Entry & operator=(Certificate_Entry &&other) noexcept
Certificate_Entry(const Certificate_Entry &other)=delete
~Certificate_Entry()
bool has_certificate() const
Certificate_Entry(TLS_Data_Reader &reader, Connection_Side side, Certificate_Type cert_type, bool is_leaf)
Certificate_Entry(Certificate_Entry &&other) noexcept
std::shared_ptr< const Public_Key > public_key() const
Handshake_Type type() const override
const std::vector< uint8_t > & request_context() const
std::vector< uint8_t > serialize() const override
Certificate_13(const Certificate_Request_13 &cert_request, std::string_view hostname, Credentials_Manager &credentials_manager, Callbacks &callbacks, Certificate_Type cert_type)
const std::vector< Signature_Scheme > & signature_schemes() const
const Extensions & extensions() const
const std::vector< uint8_t > & context() const
Handshake_Type type() const override
const std::vector< Signature_Scheme > & certificate_signature_schemes() const
Certificate_Request_13(std::span< const uint8_t > buf, Connection_Side side)
static std::optional< Certificate_Request_13 > maybe_create(const Client_Hello_13 &sni_hostname, Credentials_Manager &cred_mgr, Callbacks &callbacks, const Policy &policy)
std::vector< X509_DN > acceptable_CAs() const
bool verify(const Public_Key &public_key, Callbacks &callbacks, const Transcript_Hash &transcript_hash) const
Certificate_Verify_13(std::span< const uint8_t > buf, Connection_Side side)
Certificate_Verify(std::span< const uint8_t > buf)
void validate_updates(const Client_Hello_13 &new_ch)
Client_Hello_13(const Policy &policy, Callbacks &cb, RandomNumberGenerator &rng, std::string_view hostname, std::vector< std::string > next_protocols, std::optional< Session_with_Handle > &session, std::vector< ExternalPSK > psks, TLS_Flavor flavor)
std::optional< Protocol_Version > highest_supported_version(const Policy &policy) const
static std::variant< Client_Hello_13, Client_Hello_12_Shim > parse(std::span< const uint8_t > buf)
void retry(const Hello_Retry_Request &hrr, const Transcript_Hash_State &transcript_hash_state, Callbacks &cb, RandomNumberGenerator &rng)
std::vector< std::string > next_protocols() const
Client_Hello(const Client_Hello &)=delete
const Extensions & extensions() const
Encrypted_Extensions(std::span< const uint8_t > buf)
Handshake_Type type() const override
bool verify(Cipher_State *cipher_state, const Transcript_Hash &transcript_hash) const
Finished_13(Cipher_State *cipher_state, const Transcript_Hash &transcript_hash)
Finished(std::vector< uint8_t > buf)
Finished(std::vector< uint8_t > buf)
Hello_Retry_Request(std::unique_ptr< Server_Hello_Internal > data)
Handshake_Type wire_type() const override
Handshake_Type type() const override
bool expects_reciprocation() const
Key_Update(bool request_peer_update)
Handshake_Type type() const override
Handshake_Type type() const override
std::chrono::seconds lifetime_hint() const
const Ticket_Nonce & nonce() const
New_Session_Ticket_13(Ticket_Nonce nonce, const Session &session, const Session_Handle &handle, Callbacks &callbacks)
const Opaque_Session_Handle & handle() const
const Extensions & extensions() 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
Helper class to embody a session handle in all protocol versions.
typename as_wrapped_references< T >::type as_wrapped_references_t
detail::as_wrapped_references_t< Server_Handshake_13_Message > Server_Handshake_13_Message_Ref
std::variant< Server_Hello_13, Server_Hello_12_Shim, Hello_Retry_Request, Encrypted_Extensions, Certificate_13, Certificate_Request_13, Certificate_Verify_13, Finished_13 > Server_Handshake_13_Message
std::vector< uint8_t > Transcript_Hash
Definition tls_magic.h:105
detail::as_wrapped_references_t< Handshake_Message_13 > Handshake_Message_13_Ref
std::variant< Key_Update > Client_Post_Handshake_13_Message
std::variant< Client_Hello_13, Client_Hello_12_Shim, Certificate_13, Certificate_Verify_13, Finished_13 > Client_Handshake_13_Message
std::variant< Client_Hello_13, Client_Hello_12_Shim, Server_Hello_13, Server_Hello_12_Shim, Hello_Retry_Request, Encrypted_Extensions, Certificate_13, Certificate_Request_13, Certificate_Verify_13, Finished_13 > Handshake_Message_13
Strong< std::vector< uint8_t >, struct Ticket_Nonce_ > Ticket_Nonce
Used to derive the ticket's PSK from the resumption_master_secret.
Definition tls_magic.h:108
Group_Params Named_Group
detail::as_wrapped_references_t< Client_Handshake_13_Message > Client_Handshake_13_Message_Ref
std::variant< New_Session_Ticket_13, Key_Update > Post_Handshake_Message_13
std::variant< New_Session_Ticket_13, Key_Update > Server_Post_Handshake_13_Message
Strong< std::vector< uint8_t >, struct Opaque_Session_Handle_ > Opaque_Session_Handle
holds an opaque session handle as used in TLS 1.3 that could be either a ticket for stateless resumpt...
std::variant< std::reference_wrapper< AlternativeTs >... > type