Botan::TLS::Certificate_13 Class Reference

#include <tls_messages_13.h>

Inheritance diagram for Botan::TLS::Certificate_13:

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 177 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 188 of file msg_certificate_13.cpp.

                                                           :
      m_request_context(cert_request.context()), m_side(Connection_Side::Client) {
   const auto key_types = filter_signature_schemes(cert_request.signature_schemes());
   const std::string op_type = "tls-client";
 
   if(cert_type == Certificate_Type::X509) {
      setup_entries(
         credentials_manager.find_cert_chain(key_types,
                                             to_algorithm_identifiers(cert_request.certificate_signature_schemes()),
                                             cert_request.acceptable_CAs(),
                                             op_type,
                                             std::string(hostname)),
         cert_request.extensions().get<Certificate_Status_Request>(),
         callbacks);
   } else if(cert_type == Certificate_Type::RawPublicKey) {
      auto raw_public_key = credentials_manager.find_raw_public_key(key_types, op_type, std::string(hostname));
 
      // RFC 8446 4.4.2
      //     If the RawPublicKey certificate type was negotiated, then the
      //     certificate_list MUST contain no more than one CertificateEntry
      //     [...].
      //     A client will send an empty certificate_list if it does not have
      //     an appropriate certificate to send in response to the server's
      //     authentication request.
      if(raw_public_key) {
         setup_entry(std::move(raw_public_key), callbacks);
      }
   }
}

References Botan::TLS::Certificate_Request_13::acceptable_CAs(), Botan::TLS::Certificate_Request_13::certificate_signature_schemes(), Botan::TLS::Certificate_Request_13::extensions(), 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 225 of file msg_certificate_13.cpp.

                                                           :
      // RFC 8446 4.4.2:
      //    [In the case of server authentication], the request context
      //    SHALL be zero length
      m_request_context(/* NOLINT(*-redundant-member-init) */), m_side(Connection_Side::Server) {
   /*
   RFC 8446 4.2.3:
       Clients which desire the server to authenticate itself via a
       certificate MUST send the "signature_algorithms" extension.  If a
       server is authenticating via a certificate and the client has not sent
       a "signature_algorithms" extension, then the server MUST abort the
       handshake with a "missing_extension" alert.
   */
   if(!client_hello.extensions().has<Signature_Algorithms>()) {
      throw TLS_Exception(Alert::MissingExtension, "Client Hello is missing required signature_algorithms extension");
   }
 
   const auto key_types = filter_signature_schemes(client_hello.signature_schemes());
   const std::string op_type = "tls-server";
   const std::string context = client_hello.sni_hostname();
 
   if(cert_type == Certificate_Type::X509) {
      auto cert_chain = credentials_manager.find_cert_chain(
         key_types, to_algorithm_identifiers(client_hello.certificate_signature_schemes()), {}, op_type, context);
 
      // RFC 8446 4.4.2
      //    The server's certificate_list MUST always be non-empty.
      if(cert_chain.empty()) {
         throw TLS_Exception(Alert::HandshakeFailure, "No sufficient server certificate available");
      }
 
      setup_entries(std::move(cert_chain), client_hello.extensions().get<Certificate_Status_Request>(), callbacks);
   } else if(cert_type == Certificate_Type::RawPublicKey) {
      auto raw_public_key = credentials_manager.find_raw_public_key(key_types, op_type, context);
 
      // RFC 8446 4.4.2
      //     If the RawPublicKey certificate type was negotiated, then the
      //     certificate_list MUST contain no more than one CertificateEntry
      //     [...].
      //     The server's certificate_list MUST always be non-empty
      if(!raw_public_key) {
         throw TLS_Exception(Alert::HandshakeFailure, "No sufficient server raw public key available");
      }
 
      setup_entry(std::move(raw_public_key), callbacks);
   }
}

References cert_chain(), Botan::TLS::Client_Hello::extensions(), Botan::TLS::Extensions::get(), Botan::TLS::Extensions::has(), Botan::TLS::Client_Hello::signature_schemes(), Botan::TLS::Client_Hello::sni_hostname(), 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

buf	the serialized message
policy	the TLS policy
side	is this a Connection_Side::Server or Connection_Side::Client certificate message
cert_type	is the certificate type that was negotiated during the handshake

Deserialize a Certificate message

Definition at line 368 of file msg_certificate_13.cpp.

                                                           :
      m_side(side) {
   TLS_Data_Reader reader("cert message reader", buf);
 
   m_request_context = reader.get_range<uint8_t>(1, 0, 255);
 
   // RFC 8446 4.4.2
   //    [...] in the case of server authentication, this field SHALL be zero length.
   if(m_side == Connection_Side::Server && !m_request_context.empty()) {
      throw TLS_Exception(Alert::IllegalParameter, "Server Certificate message must not contain a request context");
   }
 
   const auto cert_entries_len = reader.get_uint24_t();
 
   if(reader.remaining_bytes() != cert_entries_len) {
      throw TLS_Exception(Alert::DecodeError, "Certificate: Message malformed");
   }
 
   const size_t max_size = policy.maximum_certificate_chain_size();
   if(max_size > 0 && cert_entries_len > max_size) {
      throw Decoding_Error("Certificate chain exceeds policy specified maximum size");
   }
 
   while(reader.has_remaining()) {
      m_entries.emplace_back(reader, side, cert_type);
   }
 
   // RFC 8446 4.4.2
   //    The server's certificate_list MUST always be non-empty.  A client
   //    will send an empty certificate_list if it does not have an
   //    appropriate certificate to send in response to the server's
   //    authentication request.
   if(m_entries.empty()) {
      // RFC 8446 4.4.2.4
      //    If the server supplies an empty Certificate message, the client MUST
      //    abort the handshake with a "decode_error" alert.
      if(m_side == Connection_Side::Server) {
         throw TLS_Exception(Alert::DecodeError, "No certificates sent by server");
      }
 
      return;
   }
 
   BOTAN_ASSERT_NOMSG(!m_entries.empty());
 
   // RFC 8446 4.4.2.2
   //    The certificate type MUST be X.509v3 [RFC5280], unless explicitly
   //    negotiated otherwise (e.g., [RFC7250]).
   //
   // TLS 1.0 through 1.3 all seem to require that the certificate be
   // precisely a v3 certificate. In fact the strict wording would seem
   // to require that every certificate in the chain be v3. But often
   // the intermediates are outside of the control of the server.
   // But, require that the leaf certificate be v3.
   if(cert_type == Certificate_Type::X509 && m_entries.front().certificate().x509_version() != 3) {
      throw TLS_Exception(Alert::BadCertificate, "The leaf certificate must be v3");
   }
 
   // RFC 8446 4.4.2
   //    If the RawPublicKey certificate type was negotiated, then the
   //    certificate_list MUST contain no more than one CertificateEntry.
   if(cert_type == Certificate_Type::RawPublicKey && m_entries.size() != 1) {
      throw TLS_Exception(Alert::IllegalParameter, "Certificate message contained more than one RawPublicKey");
   }
 
   // Validate the provided (certificate) public key against our policy
   auto pubkey = public_key();
   policy.check_peer_key_acceptable(*pubkey);
 
   if(!policy.allowed_signature_method(pubkey->algo_name())) {
      throw TLS_Exception(Alert::HandshakeFailure, "Rejecting " + pubkey->algo_name() + " signature");
   }
}

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 67 of file msg_certificate_13.cpp.

                                                             {
   BOTAN_STATE_CHECK(has_certificate_chain());
   std::vector<X509_Certificate> result;
   std::transform(m_entries.cbegin(), m_entries.cend(), std::back_inserter(result), [](const auto& cert_entry) {
      return cert_entry.certificate();
   });
   return result;
}

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 218 of file tls_messages_13.h.

{ return m_entries.size(); }

empty()

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

inline

Definition at line 220 of file tls_messages_13.h.

{ 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 59 of file msg_certificate_13.cpp.

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

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 63 of file msg_certificate_13.cpp.

                                             {
   return !empty() && !has_certificate_chain();
}

References empty(), and has_certificate_chain().

Referenced by verify().

leaf()

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

(

)

const

Definition at line 96 of file msg_certificate_13.cpp.

                                                   {
   BOTAN_STATE_CHECK(!empty());
   return m_entries.front().certificate();
}

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 91 of file msg_certificate_13.cpp.

                                                                 {
   BOTAN_STATE_CHECK(!empty());
   return m_entries.front().public_key();
}

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 225 of file tls_messages_13.h.

{ 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 448 of file msg_certificate_13.cpp.

                                                   {
   std::vector<uint8_t> buf;
 
   append_tls_length_value(buf, m_request_context, 1);
 
   std::vector<uint8_t> entries;
   for(const auto& entry : m_entries) {
      append_tls_length_value(entries, entry.serialize(), 3);
 
      // Extensions are tacked at the end of certificate entries. Note that
      // Extensions::serialize() usually emits the required length field,
      // except when no extensions are added at all, then it  returns an
      // empty buffer.
      //
      // TODO: look into this issue more generally when overhauling the
      //       message marshalling.
      auto extensions = entry.extensions().serialize(m_side);
      entries += (!extensions.empty()) ? extensions : std::vector<uint8_t>{0, 0};
   }
 
   append_tls_length_value(buf, entries, 3);
 
   return buf;
}

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 211 of file tls_messages_13.h.

{ return Handshake_Type::Certificate; }

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 21 of file tls_handshake_state.cpp.

                                               {
   return handshake_type_to_string(type());
}

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_extensions	Extensions of Client_Hello or Certificate_Request messages
cb	Callback that will be called for each extension.

Definition at line 76 of file msg_certificate_13.cpp.

                                                                                                                {
   // RFC 8446 4.4.2
   //    Extensions in the Certificate message from the server MUST
   //    correspond to ones from the ClientHello message.  Extensions in
   //    the Certificate message from the client MUST correspond to
   //    extensions in the CertificateRequest message from the server.
   for(const auto& entry : m_entries) {
      if(entry.extensions().contains_other_than(requested_extensions)) {
         throw TLS_Exception(Alert::IllegalParameter, "Certificate Entry contained an extension that was not offered");
      }
 
      cb.tls_examine_extensions(entry.extensions(), m_side, type());
   }
}

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

if	verification fails.

Definition at line 101 of file msg_certificate_13.cpp.

                                                 {
   const auto usage = (m_side == Connection_Side::Client) ? Usage_Type::TLS_CLIENT_AUTH : Usage_Type::TLS_SERVER_AUTH;
 
   if(is_raw_public_key()) {
      callbacks.tls_verify_raw_public_key(*public_key(), usage, hostname, policy);
   } else {
      verify_certificate_chain(callbacks, policy, creds, hostname, use_ocsp, usage);
   }
}

References Botan::TLS::Client, is_raw_public_key(), public_key(), Botan::TLS_CLIENT_AUTH, Botan::TLS_SERVER_AUTH, and Botan::TLS::Callbacks::tls_verify_raw_public_key().

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.

{ return type(); }

References type().

Referenced by Botan::TLS::Stream_Handshake_IO::send().

---

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

• src/lib/tls/tls13/tls_messages_13.h
• src/lib/tls/tls13/msg_certificate_13.cpp