Botan 3.14.1
Crypto and TLS for C&
tls_extensions.h
Go to the documentation of this file.
1/*
2* TLS Extensions
3* (C) 2011,2012,2016,2018,2019 Jack Lloyd
4* (C) 2016 Juraj Somorovsky
5* (C) 2016 Matthias Gierlings
6* (C) 2021 Elektrobit Automotive GmbH
7* (C) 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
8* (C) 2023 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
9*
10* Botan is released under the Simplified BSD License (see license.txt)
11*/
12
13#ifndef BOTAN_TLS_EXTENSIONS_H_
14#define BOTAN_TLS_EXTENSIONS_H_
15
16#include <botan/assert.h>
17#include <botan/tls_algos.h>
18#include <botan/tls_magic.h>
19#include <botan/tls_signature_scheme.h>
20#include <botan/tls_version.h>
21
22#include <map>
23#include <memory>
24#include <optional>
25#include <set>
26#include <span>
27
28namespace Botan {
29
32class X509_DN;
33
34namespace TLS {
35
36class Policy;
37class TLS_Data_Reader;
38
39enum class Extension_Code : uint16_t {
42
44 EcPointFormats = 11, // TLS 1.2 exclusive
47 UseSrtp = 14,
49
50 // SignedCertificateTimestamp = 18, // NYI
51
52 // RFC 7250 (Raw Public Keys in TLS)
55
56 Padding = 21, // RFC 7685; not implemented but recognized so it can be
57 // explicitly carved out of strict-mutation checks.
58
59 EncryptThenMac = 22, // TLS 1.2 exclusive
60 ExtendedMasterSecret = 23, // TLS 1.2 exclusive
61
63
64 SessionTicket = 35, // TLS 1.2 exclusive
65
67
68 PresharedKey = 41, // TLS 1.3 exclusive
69 EarlyData = 42, // TLS 1.3 exclusive
70 Cookie = 44, // TLS 1.3 exclusive
71 PskKeyExchangeModes = 45, // TLS 1.3 exclusive
72 CertificateAuthorities = 47, // TLS 1.3 exclusive
73 KeyShare = 51, // TLS 1.3 exclusive
74
75 SafeRenegotiation = 65281, // TLS 1.2 exclusive
76};
77
78/**
79* Base class representing a TLS extension of some kind
80*/
81class BOTAN_UNSTABLE_API Extension /* NOLINT(*-special-member-functions) */ {
82 public:
83 /**
84 * Return TLS extension code
85 *
86 * @return code number of the extension
87 */
88 virtual Extension_Code type() const = 0;
89
90 /**
91 * Serialize a TLS extension
92 *
93 * @param whoami which peer we are acting as in the protocol
94 * @return serialized binary for the extension
95 */
96 virtual std::vector<uint8_t> serialize(Connection_Side whoami) const = 0;
97
98 /**
99 * Predicate if a TLS extension should be included or not
100 *
101 * @return true if this extension should be encoded, otherwise false
102 */
103 virtual bool empty() const = 0;
104
105 /**
106 * Predicate if the extension is known/implemented
107 *
108 * @note this exists primarily to support unknown extension handling and
109 * doesn't need to be overridden even in the custom extension case.
110 *
111 * @return true if this extension is known
112 */
113 virtual bool is_implemented() const { return true; }
114
115 virtual ~Extension() = default;
116};
117
118/**
119* Server Name Indicator extension (RFC 3546)
120*/
122 public:
124
125 Extension_Code type() const override { return static_type(); }
126
127 explicit Server_Name_Indicator(std::string_view host_name) : m_sni_host_name(host_name) {}
128
129 /**
130 * Decode a server_name extension. On the server side the host_name
131 * must be a valid DNS name (RFC 6066 3) or the handshake is rejected
132 * with an illegal_parameter alert.
133 */
134 Server_Name_Indicator(TLS_Data_Reader& reader, uint16_t extension_size, Connection_Side from);
135
136 /**
137 * Return the host_name. When decoded from a ClientHello this is the
138 * canonical (lowercased) form of the name.
139 */
140 std::string host_name() const { return m_sni_host_name; }
141
142 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
143
144 bool empty() const override { return false; }
145
146 static bool hostname_acceptable_for_sni(std::string_view hostname);
147
148 private:
149 std::string m_sni_host_name;
150};
151
152/**
153* ALPN (RFC 7301)
154*/
156 public:
158
159 Extension_Code type() const override { return static_type(); }
160
161 const std::vector<std::string>& protocols() const { return m_protocols; }
162
163 std::string single_protocol() const;
164
165 /**
166 * Single protocol, used by server
167 */
168 explicit Application_Layer_Protocol_Notification(std::string_view protocol);
169
170 /**
171 * List of protocols, used by client
172 */
173 explicit Application_Layer_Protocol_Notification(std::vector<std::string> protocols);
174
175 Application_Layer_Protocol_Notification(TLS_Data_Reader& reader, uint16_t extension_size, Connection_Side from);
176
177 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
178
179 bool empty() const override { return m_protocols.empty(); }
180
181 private:
182 std::vector<std::string> m_protocols;
183};
184
185/**
186 * RFC 7250
187 * Base class for 'client_certificate_type' and 'server_certificate_type' extensions.
188 */
190 public:
191 /**
192 * Called by the client to advertise support for a number of cert types.
193 */
194 explicit Certificate_Type_Base(std::vector<Certificate_Type> supported_cert_types);
195
196 protected:
197 /**
198 * Called by the server to select a cert type to be used in the handshake.
199 */
200 Certificate_Type_Base(const Certificate_Type_Base& certificate_type_from_client,
201 std::span<const Certificate_Type> server_preference);
202
203 public:
204 Certificate_Type_Base(TLS_Data_Reader& reader, uint16_t extension_size, Connection_Side from);
205
206 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
207
208 void validate_selection(const Certificate_Type_Base& from_server) const;
210
211 bool empty() const override {
212 // RFC 7250 4.1
213 // If the client has no remaining certificate types to send in the
214 // client hello, other than the default X.509 type, it MUST omit the
215 // entire client[/server]_certificate_type extension [...].
216 return m_from == Connection_Side::Client && m_certificate_types.size() == 1 &&
217 m_certificate_types.front() == Certificate_Type::X509;
218 }
219
220 private:
221 std::vector<Certificate_Type> m_certificate_types;
222 Connection_Side m_from;
223};
224
226 public:
228
229 /**
230 * Creates the Server Hello extension from the received client preferences.
231 */
232 Client_Certificate_Type(const Client_Certificate_Type& cct, const Policy& policy);
233
235
236 Extension_Code type() const override { return static_type(); }
237};
238
240 public:
242
243 /**
244 * Creates the Server Hello extension from the received client preferences.
245 */
246 Server_Certificate_Type(const Server_Certificate_Type& sct, const Policy& policy);
247
249
250 Extension_Code type() const override { return static_type(); }
251};
252
253/**
254* Supported Groups Extension (RFC 7919)
255*/
257 public:
259
260 Extension_Code type() const override { return static_type(); }
261
262 const std::vector<Group_Params>& groups() const;
263
264 // Returns the list of groups we recognize as ECDH curves, along with
265 // any unknown groups outside the FFDHE range (see TLS::Callbacks)
266 std::vector<Group_Params> ec_groups() const;
267
268 // Returns the list of any groups in the FFDHE range
269 std::vector<Group_Params> dh_groups() const;
270
271 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
272
273 explicit Supported_Groups(std::vector<Group_Params> groups);
274
275 Supported_Groups(TLS_Data_Reader& reader, uint16_t extension_size);
276
277 bool empty() const override { return m_groups.empty(); }
278
279 private:
280 std::vector<Group_Params> m_groups;
281};
282
283/**
284* Signature Algorithms Extension for TLS 1.2 (RFC 5246)
285*/
287 public:
289
290 Extension_Code type() const override { return static_type(); }
291
292 const std::vector<Signature_Scheme>& supported_schemes() const { return m_schemes; }
293
294 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
295
296 bool empty() const override { return m_schemes.empty(); }
297
298 explicit Signature_Algorithms(std::vector<Signature_Scheme> schemes) : m_schemes(std::move(schemes)) {}
299
300 Signature_Algorithms(TLS_Data_Reader& reader, uint16_t extension_size);
301
302 private:
303 std::vector<Signature_Scheme> m_schemes;
304};
305
306/**
307* Signature_Algorithms_Cert for TLS 1.3 (RFC 8446)
308*
309* RFC 8446 4.2.3
310* TLS 1.3 provides two extensions for indicating which signature algorithms
311* may be used in digital signatures. The "signature_algorithms_cert"
312* extension applies to signatures in certificates, and the
313* "signature_algorithms" extension, which originally appeared in TLS 1.2,
314* applies to signatures in CertificateVerify messages.
315*
316* RFC 8446 4.2.3
317* TLS 1.2 implementations SHOULD also process this extension.
318*/
320 public:
322
323 Extension_Code type() const override { return static_type(); }
324
325 const std::vector<Signature_Scheme>& supported_schemes() const { return m_schemes; }
326
327 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
328
329 bool empty() const override { return m_schemes.empty(); }
330
331 explicit Signature_Algorithms_Cert(std::vector<Signature_Scheme> schemes) : m_schemes(std::move(schemes)) {}
332
333 Signature_Algorithms_Cert(TLS_Data_Reader& reader, uint16_t extension_size);
334
335 private:
336 std::vector<Signature_Scheme> m_schemes;
337};
338
339/**
340* Used to indicate SRTP algorithms for DTLS (RFC 5764)
341*/
343 public:
345
346 Extension_Code type() const override { return static_type(); }
347
348 const std::vector<uint16_t>& profiles() const { return m_pp; }
349
350 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
351
352 bool empty() const override { return m_pp.empty(); }
353
354 explicit SRTP_Protection_Profiles(std::vector<uint16_t> pp) : m_pp(std::move(pp)) {}
355
356 explicit SRTP_Protection_Profiles(uint16_t pp) : m_pp(1, pp) {}
357
358 SRTP_Protection_Profiles(TLS_Data_Reader& reader, uint16_t extension_size, Connection_Side from);
359
360 private:
361 std::vector<uint16_t> m_pp;
362};
363
364class Certificate_Status_Request_Internal;
365
366/**
367* Certificate Status Request (RFC 6066)
368*/
369class BOTAN_UNSTABLE_API Certificate_Status_Request final : public Extension /* NOLINT(*-special-member-functions) */ {
370 public:
372
373 Extension_Code type() const override { return static_type(); }
374
375 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
376
377 bool empty() const override { return false; }
378
379 const std::vector<uint8_t>& get_responder_id_list() const;
380 const std::vector<uint8_t>& get_request_extensions() const;
381 const std::vector<uint8_t>& get_ocsp_response() const;
382
383 // TLS 1.2 Server generated version: empty
385
386 // Client version: ocsp_responder_ids is the encoded responder_id_list
387 // (may be empty), ocsp_key_ids is not supported and must be empty
388 Certificate_Status_Request(std::vector<uint8_t> ocsp_responder_ids,
389 std::vector<std::vector<uint8_t>> ocsp_key_ids);
390
391 // TLS 1.3 version
392 explicit Certificate_Status_Request(std::vector<uint8_t> response);
393
395 uint16_t extension_size,
396 Handshake_Type message_type,
397 Connection_Side from);
398
400
401 private:
402 std::unique_ptr<Certificate_Status_Request_Internal> m_impl;
403};
404
405/**
406* Supported Versions from RFC 8446
407*/
409 public:
411
412 Extension_Code type() const override { return static_type(); }
413
414 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
415
416 bool empty() const override { return m_versions.empty(); }
417
418 Supported_Versions(Protocol_Version version, const Policy& policy);
419
420 explicit Supported_Versions(Protocol_Version version) { m_versions.push_back(version); }
421
422 Supported_Versions(TLS_Data_Reader& reader, uint16_t extension_size, Connection_Side from);
423
424 bool supports(Protocol_Version version) const;
425
426 const std::vector<Protocol_Version>& versions() const { return m_versions; }
427
428 private:
429 std::vector<Protocol_Version> m_versions;
430};
431
433
434/**
435* Record Size Limit (RFC 8449)
436*
437* TODO: the record size limit is currently not honored by the TLS 1.2 stack
438*/
440 public:
442
443 Extension_Code type() const override { return static_type(); }
444
445 explicit Record_Size_Limit(uint16_t limit);
446
447 Record_Size_Limit(TLS_Data_Reader& reader, uint16_t extension_size, Connection_Side from);
448
449 uint16_t limit() const { return m_limit; }
450
451 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
452
453 bool empty() const override { return m_limit == 0; }
454
455 private:
456 uint16_t m_limit;
457};
458
459/**
460* Unknown extensions are deserialized as this type
461*/
463 public:
464 Unknown_Extension(Extension_Code type, TLS_Data_Reader& reader, uint16_t extension_size);
465
466 std::vector<uint8_t> serialize(Connection_Side whoami) const override;
467
468 const std::vector<uint8_t>& value() { return m_value; }
469
470 bool empty() const override { return false; }
471
472 Extension_Code type() const override { return m_type; }
473
474 bool is_implemented() const override { return false; }
475
476 private:
477 Extension_Code m_type;
478 std::vector<uint8_t> m_value;
479};
480
481/**
482* Represents a block of extensions in a hello message
483*/
485 public:
486 std::set<Extension_Code> extension_types() const;
487
488 template <typename T>
489 T* get() const {
490 return dynamic_cast<T*>(get(T::static_type()));
491 }
492
493 template <typename T>
494 bool has() const {
495 return get<T>() != nullptr;
496 }
497
498 bool has(Extension_Code type) const;
499
500 size_t size() const { return m_extensions.size(); }
501
502 bool empty() const { return m_extensions.empty(); }
503
504 void add(std::unique_ptr<Extension> extn);
505
506 void add(Extension* extn) { add(std::unique_ptr<Extension>(extn)); }
507
508 Extension* get(Extension_Code type) const;
509
510 std::vector<uint8_t> serialize(Connection_Side whoami) const;
511
512 void deserialize(TLS_Data_Reader& reader, Connection_Side from, Handshake_Type message_type);
513
514 /**
515 * @param allowed_extensions extension types that are allowed
516 * @param allow_unknown_extensions if true, ignores unrecognized extensions
517 * @returns true if this contains any extensions that are not contained in @p allowed_extensions.
518 */
519 bool contains_other_than(const std::set<Extension_Code>& allowed_extensions,
520 bool allow_unknown_extensions = false) const;
521
522 /**
523 * @param allowed_extensions extension types that are allowed
524 * @returns true if this contains any extensions implemented by Botan that
525 * are not contained in @p allowed_extensions.
526 */
527 bool contains_implemented_extensions_other_than(const std::set<Extension_Code>& allowed_extensions) const {
528 return contains_other_than(allowed_extensions, true);
529 }
530
531 /**
532 * Remove an extension from this extensions object, if it exists.
533 * Returns true if the extension existed (and thus is now removed),
534 * otherwise false (the extension wasn't set in the first place).
535 *
536 * Note: not used internally, might be used in Callbacks::tls_modify_extensions()
537 */
538 bool remove_extension(Extension_Code type);
539
540 /**
541 * Reorder extensions for serialization. Extensions not mentioned in
542 * @p order retain their relative position at the front; extensions in
543 * @p order are appended in the given order.
544 */
545 void reorder(std::span<const Extension_Code> order);
546
547 /**
548 * Return the code of the extension that appears last in the encoding
549 * This is used for checking the position of PSK extension in TLS 1.3
550 */
551 std::optional<Extension_Code> last_added() const {
552 if(m_extension_codes.empty()) {
553 return {};
554 } else {
555 return m_extension_codes.back();
556 }
557 }
558
559 Extensions() = default;
560 Extensions(const Extensions&) = delete;
561 Extensions& operator=(const Extensions&) = delete;
562 Extensions(Extensions&&) = default;
565
567 deserialize(reader, side, message_type);
568 }
569
570 /**
571 * @returns the raw bytes of the extension with the given type as they
572 * appeared on the wire during deserialization, or std::nullopt
573 * if the extension was not present or was added programmatically.
574 */
575 std::optional<std::vector<uint8_t>> extension_raw_bytes(Extension_Code type) const {
576 const auto it = m_raw_extension_data.find(type);
577 if(it != m_raw_extension_data.end()) {
578 return it->second;
579 }
580 return std::nullopt;
581 }
582
583 private:
584 // Kept in the order they were added
585 std::vector<Extension_Code> m_extension_codes;
586 std::map<Extension_Code, std::unique_ptr<Extension>> m_extensions;
587 std::map<Extension_Code, std::vector<uint8_t>> m_raw_extension_data;
588};
589
590} // namespace TLS
591
592} // namespace Botan
593
594#endif
#define BOTAN_UNSTABLE_API
Definition api.h:34
Application_Layer_Protocol_Notification(std::string_view protocol)
const std::vector< std::string > & protocols() const
Extension_Code type() const override
Certificate_Type selected_certificate_type() const
Certificate_Type_Base(std::vector< Certificate_Type > supported_cert_types)
void validate_selection(const Certificate_Type_Base &from_server) const
std::vector< uint8_t > serialize(Connection_Side whoami) const override
Extension_Code type() const override
Client_Certificate_Type(const Client_Certificate_Type &cct, const Policy &policy)
Certificate_Type_Base(std::vector< Certificate_Type > supported_cert_types)
static Extension_Code static_type()
virtual std::vector< uint8_t > serialize(Connection_Side whoami) const =0
virtual bool is_implemented() const
virtual Extension_Code type() const =0
virtual bool empty() const =0
virtual ~Extension()=default
Extensions(Extensions &&)=default
void add(Extension *extn)
bool contains_implemented_extensions_other_than(const std::set< Extension_Code > &allowed_extensions) const
Extensions & operator=(const Extensions &)=delete
std::optional< std::vector< uint8_t > > extension_raw_bytes(Extension_Code type) const
Extensions(const Extensions &)=delete
void deserialize(TLS_Data_Reader &reader, Connection_Side from, Handshake_Type message_type)
std::optional< Extension_Code > last_added() const
Extensions(TLS_Data_Reader &reader, Connection_Side side, Handshake_Type message_type)
Extensions & operator=(Extensions &&)=default
std::set< Extension_Code > extension_types() const
bool contains_other_than(const std::set< Extension_Code > &allowed_extensions, bool allow_unknown_extensions=false) const
Extension_Code type() const override
static Extension_Code static_type()
bool empty() const override
Extension_Code type() const override
SRTP_Protection_Profiles(std::vector< uint16_t > pp)
const std::vector< uint16_t > & profiles() const
static Extension_Code static_type()
static Extension_Code static_type()
Server_Certificate_Type(const Server_Certificate_Type &sct, const Policy &policy)
Certificate_Type_Base(std::vector< Certificate_Type > supported_cert_types)
Extension_Code type() const override
static Extension_Code static_type()
Extension_Code type() const override
Server_Name_Indicator(std::string_view host_name)
Signature_Algorithms_Cert(std::vector< Signature_Scheme > schemes)
const std::vector< Signature_Scheme > & supported_schemes() const
Extension_Code type() const override
Signature_Algorithms(std::vector< Signature_Scheme > schemes)
const std::vector< Signature_Scheme > & supported_schemes() const
static Extension_Code static_type()
Extension_Code type() const override
bool empty() const override
Supported_Groups(std::vector< Group_Params > groups)
Extension_Code type() const override
static Extension_Code static_type()
static Extension_Code static_type()
Supported_Versions(Protocol_Version version, const Policy &policy)
const std::vector< Protocol_Version > & versions() const
bool empty() const override
Supported_Versions(Protocol_Version version)
Extension_Code type() const override
bool empty() const override
std::vector< uint8_t > serialize(Connection_Side whoami) const override
Unknown_Extension(Extension_Code type, TLS_Data_Reader &reader, uint16_t extension_size)
const std::vector< uint8_t > & value()
bool is_implemented() const override
Extension_Code type() const override
Group_Params Named_Group