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

#include <tls_messages_13.h>

Inheritance diagram for Botan::TLS::Certificate_13:
Botan::TLS::Handshake_Message

Classes

class  Certificate_Entry

Public Member Functions

std::vector< X509_Certificate > cert_chain () const
 Certificate_13 (const Certificate_Request_13 &cert_request, std::string_view hostname, Credentials_Manager &credentials_manager, Callbacks &callbacks, Certificate_Type cert_type)
 Certificate_13 (const Client_Hello_13 &client_hello, Credentials_Manager &credentials_manager, Callbacks &callbacks, Certificate_Type cert_type)
 Certificate_13 (std::span< const uint8_t > buf, const Policy &policy, Connection_Side side, Certificate_Type cert_type)
size_t count () const
bool empty () const
bool has_certificate_chain () const
bool is_raw_public_key () const
const X509_Certificate & leaf () const
std::shared_ptr< const Public_Key > public_key () const
const std::vector< uint8_t > & request_context () const
std::vector< uint8_t > serialize () const override
Handshake_Type type () const override
std::string type_string () const
void validate_extensions (const std::set< Extension_Code > &requested_extensions, Callbacks &cb) const
void verify (Callbacks &callbacks, const Policy &policy, Credentials_Manager &creds, std::string_view hostname, bool use_ocsp) const
virtual Handshake_Type wire_type () const

Detailed Description

Certificate Message of TLS 1.3

Definition at line 184 of file tls_messages_13.h.

Constructor & Destructor Documentation

◆ Certificate_13() [1/3]

Botan::TLS::Certificate_13::Certificate_13 ( const Certificate_Request_13 & cert_request,
std::string_view hostname,
Credentials_Manager & credentials_manager,
Callbacks & callbacks,
Certificate_Type cert_type )

Create a Client Certificate message ... in response to a Certificate Request message.

Create a Client Certificate message

Definition at line 208 of file msg_certificate_13.cpp.

212 :
213 m_request_context(cert_request.context()), m_side(Connection_Side::Client) {
214 // RFC 8446 4.4.2
215 // If the server requests client authentication but no suitable
216 // certificate is available, the client MUST send a Certificate message
217 // containing no certificates [...].
218 const auto key_types = filter_signature_schemes(cert_request.signature_schemes(), Protocol_Version::TLS_V13);
219 if(key_types.empty()) {
220 return;
221 }
222 const std::string op_type = "tls-client";
223
224 if(cert_type == Certificate_Type::X509) {
225 setup_entries(
226 credentials_manager.find_cert_chain(key_types,
227 to_algorithm_identifiers(cert_request.certificate_signature_schemes()),
228 cert_request.acceptable_CAs(),
229 op_type,
230 std::string(hostname)),
231 cert_request.extensions().get<Certificate_Status_Request>(),
232 callbacks);
233 } else if(cert_type == Certificate_Type::RawPublicKey) {
234 auto raw_public_key = credentials_manager.find_raw_public_key(key_types, op_type, std::string(hostname));
235
236 // RFC 8446 4.4.2
237 // If the RawPublicKey certificate type was negotiated, then the
238 // certificate_list MUST contain no more than one CertificateEntry
239 // [...].
240 // A client will send an empty certificate_list if it does not have
241 // an appropriate certificate to send in response to the server's
242 // authentication request.
243 if(raw_public_key) {
244 setup_entry(std::move(raw_public_key), callbacks);
245 }
246 }
247}
std::vector< AlgorithmIdentifier > to_algorithm_identifiers(const std::vector< Signature_Scheme > &schemes)
std::vector< std::string > filter_signature_schemes(const std::vector< Signature_Scheme > &schemes, const Protocol_Version &version)

References Botan::TLS::Certificate_Request_13::acceptable_CAs(), Botan::TLS::Certificate_Request_13::certificate_signature_schemes(), Botan::TLS::Certificate_Request_13::extensions(), Botan::TLS::filter_signature_schemes(), Botan::Credentials_Manager::find_cert_chain(), Botan::Credentials_Manager::find_raw_public_key(), Botan::TLS::Extensions::get(), Botan::TLS::RawPublicKey, Botan::TLS::Certificate_Request_13::signature_schemes(), Botan::TLS::to_algorithm_identifiers(), and Botan::TLS::X509.

◆ Certificate_13() [2/3]

Botan::TLS::Certificate_13::Certificate_13 ( const Client_Hello_13 & client_hello,
Credentials_Manager & credentials_manager,
Callbacks & callbacks,
Certificate_Type cert_type )

Create a Server Certificate message ... in response to a Client Hello indicating the need to authenticate with a server certificate.

Create a Server Certificate message

Definition at line 252 of file msg_certificate_13.cpp.

255 :
256 // RFC 8446 4.4.2:
257 // [In the case of server authentication], the request context
258 // SHALL be zero length
259 m_request_context(/* NOLINT(*-redundant-member-init) */), m_side(Connection_Side::Server) {
260 /*
261 RFC 8446 4.2.3:
262 Clients which desire the server to authenticate itself via a
263 certificate MUST send the "signature_algorithms" extension. If a
264 server is authenticating via a certificate and the client has not sent
265 a "signature_algorithms" extension, then the server MUST abort the
266 handshake with a "missing_extension" alert.
267 */
268 if(!client_hello.extensions().has<Signature_Algorithms>()) {
269 throw TLS_Exception(Alert::MissingExtension, "Client Hello is missing required signature_algorithms extension");
270 }
271
272 const auto key_types = filter_signature_schemes(client_hello.signature_schemes(), Protocol_Version::TLS_V13);
273 if(key_types.empty()) {
274 throw TLS_Exception(Alert::HandshakeFailure, "Failed to agree on any signature algorithm");
275 }
276 const std::string op_type = "tls-server";
277 const std::string context = client_hello.sni_hostname();
278
279 if(cert_type == Certificate_Type::X509) {
280 // RFC 8446 4.2.4
281 // The "certificate_authorities" extension is used to indicate the
282 // certificate authorities (CAs) which an endpoint supports and which
283 // SHOULD be used by the receiving endpoint to guide certificate
284 // selection.
285 std::vector<X509_DN> acceptable_CAs;
286 if(const auto* cas = client_hello.extensions().get<Certificate_Authorities>()) {
287 acceptable_CAs = cas->distinguished_names();
288 }
289
290 auto cert_chain =
291 credentials_manager.find_cert_chain(key_types,
292 to_algorithm_identifiers(client_hello.certificate_signature_schemes()),
293 acceptable_CAs,
294 op_type,
295 context);
296
297 // RFC 8446 4.4.2
298 // The server's certificate_list MUST always be non-empty.
299 if(cert_chain.empty()) {
300 throw TLS_Exception(Alert::HandshakeFailure, "No sufficient server certificate available");
301 }
302
303 setup_entries(std::move(cert_chain), client_hello.extensions().get<Certificate_Status_Request>(), callbacks);
304 } else if(cert_type == Certificate_Type::RawPublicKey) {
305 auto raw_public_key = credentials_manager.find_raw_public_key(key_types, op_type, context);
306
307 // RFC 8446 4.4.2
308 // If the RawPublicKey certificate type was negotiated, then the
309 // certificate_list MUST contain no more than one CertificateEntry
310 // [...].
311 // The server's certificate_list MUST always be non-empty
312 if(!raw_public_key) {
313 throw TLS_Exception(Alert::HandshakeFailure, "No sufficient server raw public key available");
314 }
315
316 setup_entry(std::move(raw_public_key), callbacks);
317 }
318}
std::vector< X509_Certificate > cert_chain() const

References cert_chain(), Botan::TLS::Client_Hello::certificate_signature_schemes(), Botan::TLS::Client_Hello::extensions(), Botan::TLS::filter_signature_schemes(), Botan::Credentials_Manager::find_cert_chain(), Botan::TLS::Extensions::get(), Botan::TLS::Extensions::has(), Botan::TLS::Client_Hello::signature_schemes(), Botan::TLS::Client_Hello::sni_hostname(), Botan::TLS::to_algorithm_identifiers(), and Botan::TLS::X509.

◆ Certificate_13() [3/3]

Botan::TLS::Certificate_13::Certificate_13 ( std::span< const uint8_t > buf,
const Policy & policy,
Connection_Side side,
Certificate_Type cert_type )

Deserialize a Certificate message

Parameters
bufthe serialized message
policythe TLS policy
sideis this a Connection_Side::Server or Connection_Side::Client certificate message
cert_typeis the certificate type that was negotiated during the handshake

Deserialize a Certificate message

Definition at line 417 of file msg_certificate_13.cpp.

420 :
421 m_side(side) {
422 TLS_Data_Reader reader("cert message reader", buf);
423
424 m_request_context = reader.get_range<uint8_t>(1, 0, 255);
425
426 // RFC 8446 4.4.2
427 // [...] in the case of server authentication, this field SHALL be zero length.
428 if(m_side == Connection_Side::Server && !m_request_context.empty()) {
429 throw TLS_Exception(Alert::IllegalParameter, "Server Certificate message must not contain a request context");
430 }
431
432 const auto cert_entries_len = reader.get_uint24_t();
433
434 if(reader.remaining_bytes() != cert_entries_len) {
435 throw TLS_Exception(Alert::DecodeError, "Certificate: Message malformed");
436 }
437
438 const size_t max_size = policy.maximum_certificate_chain_size();
439 if(max_size > 0 && cert_entries_len > max_size) {
440 throw Decoding_Error("Certificate chain exceeds policy specified maximum size");
441 }
442
443 while(reader.has_remaining()) {
444 const bool is_leaf = m_entries.empty();
445
446 // RFC 8446 4.4.2
447 // If the RawPublicKey certificate type was negotiated, then the
448 // certificate_list MUST contain no more than one CertificateEntry.
449 if(cert_type == Certificate_Type::RawPublicKey && !is_leaf) {
450 throw TLS_Exception(Alert::IllegalParameter, "Certificate message contained more than one RawPublicKey");
451 }
452
453 m_entries.emplace_back(reader, side, cert_type, is_leaf);
454 }
455
456 // RFC 8446 4.4.2
457 // The server's certificate_list MUST always be non-empty. A client
458 // will send an empty certificate_list if it does not have an
459 // appropriate certificate to send in response to the server's
460 // authentication request.
461 if(m_entries.empty()) {
462 // RFC 8446 4.4.2.4
463 // If the server supplies an empty Certificate message, the client MUST
464 // abort the handshake with a "decode_error" alert.
465 if(m_side == Connection_Side::Server) {
466 throw TLS_Exception(Alert::DecodeError, "No certificates sent by server");
467 }
468
469 return;
470 }
471
472 BOTAN_ASSERT_NOMSG(!m_entries.empty());
473
474 // RFC 8446 4.4.2.2
475 // The certificate type MUST be X.509v3 [RFC5280], unless explicitly
476 // negotiated otherwise (e.g., [RFC7250]).
477 //
478 // TLS 1.0 through 1.3 all seem to require that the certificate be
479 // precisely a v3 certificate. In fact the strict wording would seem
480 // to require that every certificate in the chain be v3. But often
481 // the intermediates are outside of the control of the server.
482 // But, require that the leaf certificate be v3.
483 if(cert_type == Certificate_Type::X509 && m_entries.front().certificate().x509_version() != 3) {
484 throw TLS_Exception(Alert::BadCertificate, "The leaf certificate must be v3");
485 }
486
487 // Validate the provided (certificate) public key against our policy
488 const auto pubkey = public_key();
489 policy.check_peer_key_acceptable(*pubkey);
490
491 if(!policy.allowed_signature_method(pubkey->algo_name())) {
492 throw TLS_Exception(Alert::HandshakeFailure, "Rejecting " + pubkey->algo_name() + " signature");
493 }
494}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
std::shared_ptr< const Public_Key > public_key() const

References Botan::TLS::Policy::allowed_signature_method(), BOTAN_ASSERT_NOMSG, Botan::TLS::Policy::check_peer_key_acceptable(), Botan::TLS::TLS_Data_Reader::get_range(), Botan::TLS::TLS_Data_Reader::get_uint24_t(), Botan::TLS::TLS_Data_Reader::has_remaining(), Botan::TLS::Policy::maximum_certificate_chain_size(), public_key(), Botan::TLS::RawPublicKey, Botan::TLS::TLS_Data_Reader::remaining_bytes(), Botan::TLS::Server, and Botan::TLS::X509.

Member Function Documentation

◆ cert_chain()

std::vector< X509_Certificate > Botan::TLS::Certificate_13::cert_chain ( ) const

Definition at line 77 of file msg_certificate_13.cpp.

77 {
79 std::vector<X509_Certificate> result;
80 std::transform(m_entries.cbegin(), m_entries.cend(), std::back_inserter(result), [](const auto& cert_entry) {
81 return cert_entry.certificate();
82 });
83 return result;
84}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49

References BOTAN_STATE_CHECK, and has_certificate_chain().

Referenced by Certificate_13().

◆ count()

size_t Botan::TLS::Certificate_13::count ( ) const
inline

Definition at line 225 of file tls_messages_13.h.

225{ return m_entries.size(); }

◆ empty()

bool Botan::TLS::Certificate_13::empty ( ) const
inline

Definition at line 227 of file tls_messages_13.h.

227{ return m_entries.empty(); }

Referenced by Botan::TLS::Certificate_Verify_13::Certificate_Verify_13(), has_certificate_chain(), is_raw_public_key(), leaf(), and public_key().

◆ has_certificate_chain()

bool Botan::TLS::Certificate_13::has_certificate_chain ( ) const

Definition at line 69 of file msg_certificate_13.cpp.

69 {
70 return !empty() && m_entries.front().has_certificate();
71}

References empty().

Referenced by cert_chain(), Botan::TLS::Certificate_Verify_13::Certificate_Verify_13(), and is_raw_public_key().

◆ is_raw_public_key()

bool Botan::TLS::Certificate_13::is_raw_public_key ( ) const

Definition at line 73 of file msg_certificate_13.cpp.

73 {
74 return !empty() && !has_certificate_chain();
75}

References empty(), and has_certificate_chain().

Referenced by verify().

◆ leaf()

const X509_Certificate & Botan::TLS::Certificate_13::leaf ( ) const

Definition at line 106 of file msg_certificate_13.cpp.

106 {
108 return m_entries.front().certificate();
109}

References BOTAN_STATE_CHECK, and empty().

Referenced by Botan::TLS::Certificate_Verify_13::Certificate_Verify_13().

◆ public_key()

std::shared_ptr< const Public_Key > Botan::TLS::Certificate_13::public_key ( ) const

Definition at line 101 of file msg_certificate_13.cpp.

101 {
103 return m_entries.front().public_key();
104}

References BOTAN_STATE_CHECK, and empty().

Referenced by Certificate_13(), Botan::TLS::Certificate_Verify_13::Certificate_Verify_13(), and verify().

◆ request_context()

const std::vector< uint8_t > & Botan::TLS::Certificate_13::request_context ( ) const
inline

Definition at line 232 of file tls_messages_13.h.

232{ return m_request_context; }

◆ serialize()

std::vector< uint8_t > Botan::TLS::Certificate_13::serialize ( ) const
overridevirtual

Serialize a Certificate message

Implements Botan::TLS::Handshake_Message.

Definition at line 499 of file msg_certificate_13.cpp.

499 {
500 std::vector<uint8_t> buf;
501
502 append_tls_length_value(buf, m_request_context, 1);
503
504 std::vector<uint8_t> entries;
505 for(const auto& entry : m_entries) {
506 append_tls_length_value(entries, entry.serialize(), 3);
507
508 // Extensions are tacked at the end of certificate entries. Note that
509 // Extensions::serialize() usually emits the required length field,
510 // except when no extensions are added at all, then it returns an
511 // empty buffer.
512 //
513 // TODO: look into this issue more generally when overhauling the
514 // message marshalling.
515 const auto extensions = entry.extensions().serialize(m_side);
516 entries += (!extensions.empty()) ? extensions : std::vector<uint8_t>{0, 0};
517 }
518
519 append_tls_length_value(buf, entries, 3);
520
521 return buf;
522}
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

References Botan::TLS::append_tls_length_value().

◆ type()

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

Return the TLS handshake type code

Returns
the message type

Implements Botan::TLS::Handshake_Message.

Definition at line 218 of file tls_messages_13.h.

References Botan::TLS::Certificate.

Referenced by validate_extensions().

◆ 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().

◆ validate_extensions()

void Botan::TLS::Certificate_13::validate_extensions ( const std::set< Extension_Code > & requested_extensions,
Callbacks & cb ) const

Validate a Certificate message regarding what extensions are expected based on previous handshake messages. Also call the tls_examine_extensions() callback for each entry.

Parameters
requested_extensionsExtensions of Client_Hello or Certificate_Request messages
cbCallback that will be called for each extension.

Definition at line 86 of file msg_certificate_13.cpp.

86 {
87 // RFC 8446 4.4.2
88 // Extensions in the Certificate message from the server MUST
89 // correspond to ones from the ClientHello message. Extensions in
90 // the Certificate message from the client MUST correspond to
91 // extensions in the CertificateRequest message from the server.
92 for(const auto& entry : m_entries) {
93 if(entry.extensions().contains_other_than(requested_extensions)) {
94 throw TLS_Exception(Alert::IllegalParameter, "Certificate Entry contained an extension that was not offered");
95 }
96
97 cb.tls_examine_extensions(entry.extensions(), m_side, type());
98 }
99}
Handshake_Type type() const override

References Botan::TLS::Callbacks::tls_examine_extensions(), and type().

◆ verify()

void Botan::TLS::Certificate_13::verify ( Callbacks & callbacks,
const Policy & policy,
Credentials_Manager & creds,
std::string_view hostname,
bool use_ocsp ) const

Verify the certificate chain

Exceptions
ifverification fails.

Definition at line 111 of file msg_certificate_13.cpp.

115 {
117
118 // Without a certificate type extension the peer sends an X.509 chain,
119 // which the policy may not accept
121 const auto accepted_types = (m_side == Connection_Side::Client) ? policy.accepted_client_certificate_types()
122 : policy.accepted_server_certificate_types();
123 if(!value_exists(accepted_types, cert_type)) {
124 throw TLS_Exception(Alert::UnsupportedCertificate,
125 "Peer sent a certificate of a type that is not accepted by the policy");
126 }
127
128 if(is_raw_public_key()) {
129 callbacks.tls_verify_raw_public_key(*public_key(), usage, hostname, policy);
130 } else {
131 verify_certificate_chain(callbacks, policy, creds, hostname, use_ocsp, usage);
132 }
133}
bool value_exists(const std::vector< T > &vec, const V &val)
Definition stl_util.h:44

References Botan::TLS::Policy::accepted_client_certificate_types(), Botan::TLS::Policy::accepted_server_certificate_types(), Botan::TLS::Client, is_raw_public_key(), public_key(), Botan::TLS::RawPublicKey, Botan::TLS_CLIENT_AUTH, Botan::TLS_SERVER_AUTH, Botan::TLS::Callbacks::tls_verify_raw_public_key(), Botan::value_exists(), and Botan::TLS::X509.

◆ wire_type()

virtual Handshake_Type Botan::TLS::Handshake_Message::wire_type ( ) const
inlinevirtualinherited

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 in Botan::TLS::Hello_Retry_Request.

Definition at line 47 of file tls_handshake_msg.h.

47{ return type(); }

References type().

Referenced by Botan::TLS::Stream_Handshake_IO::send(), and Botan::TLS::Handshake_Layer::update_transcript_for_psk_binder_calc().


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