Add an SSL_CREDENTIAL API for ECDSA/RSA and delegated credentials
This adds a notion of "credentials" to BoringSSL's API, to support
certificate selection by key type (typically ECDSA vs RSA), though the
aim is for it to be generalizable to other certificate types and other
kinds of selection criteria, such as Trust Expressions, or Merkle Tree
Certificates. Since we already had some nascent delegated credentials
I've reworked that feature with SSL_CREDENTIALs as well.
The model is that you create an SSL_CREDENTIAL object containing all the
configuration for what you are authenticating as. An X.509
SSL_CREDENTIAL has a certificate chain, private key, optionally an OCSP
response and SCT list. Delegated credentials are similar. In the future,
we might use this for raw public keys, other certificate types, etc.
Once you set those up, you configure those on the SSL or SSL_CTX in
preference order, and BoringSSL will internally pick the first one that
is usable.
The current implementation ends up redundantly selecting the signature
algorithm a couple of times. This works but is a little goofy. A
follow-up change will remove this redundancy. The protocol between the
runner and shim for tests is also a little weird, but it was the easiest
way I could think of for injecting that. Long-term, I think we should
just replace that protocol with a JSON structure. (See
https://crbug.com/boringssl/704.)
As split handshakes are in the process of being replaced with handshake
hints, this won't work with split handshakes. It works with handshake
hints without any extra work.
Update-Note: The delegated credentials API has been revamped.
Previously, it worked by configuring an optional delegated credential
and key with your normal certificate chain. This has the side effect of
forcing your DC issuer and your fallback certificate to be the same. The
SSL_CREDENTIAL API lifts this restriction.
A delegated credential is now just a different kind of credential. It
may use the same certificate chain as an X.509 credential or be
completely separate. All the SSL_CREDENTIAL APIs take CRYPTO_BUFFERs,
so, if common, the buffers may be shared to reduce memory.
The SSL_delegated_credential_used API is also removed, in favor of the
more general SSL_get0_selected_credential API. Callers can use ex_data
or pointer equality to identify the credential.
Bug: 249
Change-Id: Ibc290df3b7b95f148df12625e41cf55c50566602
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/66690
Reviewed-by: Bob Beck <bbe@google.com>
Commit-Queue: David Benjamin <davidben@google.com>
diff --git a/ssl/internal.h b/ssl/internal.h
index 9f61536..cc98538 100644
--- a/ssl/internal.h
+++ b/ssl/internal.h
@@ -1079,9 +1079,6 @@
// Private key operations.
-// ssl_has_private_key returns whether |hs| has a private key configured.
-bool ssl_has_private_key(const SSL_HANDSHAKE *hs);
-
// ssl_private_key_* perform the corresponding operation on
// |SSL_PRIVATE_KEY_METHOD|. If there is a custom private key configured, they
// call the corresponding function or |complete| depending on whether there is a
@@ -1098,10 +1095,10 @@
size_t max_out,
Span<const uint8_t> in);
-// ssl_private_key_supports_signature_algorithm returns whether |hs|'s private
-// key supports |sigalg|.
-bool ssl_private_key_supports_signature_algorithm(SSL_HANDSHAKE *hs,
- uint16_t sigalg);
+// ssl_pkey_supports_algorithm returns whether |pkey| may be used to sign
+// |sigalg|.
+bool ssl_pkey_supports_algorithm(const SSL *ssl, EVP_PKEY *pkey,
+ uint16_t sigalg);
// ssl_public_key_verify verifies that the |signature| is valid for the public
// key |pkey| and input |in|, using the signature algorithm |sigalg|.
@@ -1339,10 +1336,6 @@
// Certificate functions.
-// ssl_has_certificate returns whether a certificate and private key are
-// configured.
-bool ssl_has_certificate(const SSL_HANDSHAKE *hs);
-
// ssl_parse_cert_chain parses a certificate list from |cbs| in the format used
// by a TLS Certificate message. On success, it advances |cbs| and returns
// true. Otherwise, it returns false and sets |*out_alert| to an alert to send
@@ -1398,11 +1391,6 @@
bool ssl_check_leaf_certificate(SSL_HANDSHAKE *hs, EVP_PKEY *pkey,
const CRYPTO_BUFFER *leaf);
-// ssl_on_certificate_selected is called once the certificate has been selected.
-// It finalizes the certificate and initializes |hs->local_pubkey|. It returns
-// true on success and false on error.
-bool ssl_on_certificate_selected(SSL_HANDSHAKE *hs);
-
// TLS 1.3 key derivation.
@@ -1611,45 +1599,113 @@
bool ssl_encrypt_client_hello(SSL_HANDSHAKE *hs, Span<const uint8_t> enc);
-// Delegated credentials.
+// Credentials.
-// This structure stores a delegated credential (DC) as defined by RFC 9345.
-struct DC {
- static constexpr bool kAllowUniquePtr = true;
- ~DC();
-
- // Dup returns a copy of this DC and takes references to |raw| and |pkey|.
- UniquePtr<DC> Dup();
-
- // Parse parses the delegated credential stored in |in|. If successful it
- // returns the parsed structure, otherwise it returns |nullptr| and sets
- // |*out_alert|.
- static UniquePtr<DC> Parse(CRYPTO_BUFFER *in, uint8_t *out_alert);
-
- // raw is the delegated credential encoded as specified in RFC 9345.
- UniquePtr<CRYPTO_BUFFER> raw;
-
- // dc_cert_verify_algorithm is the signature scheme of the DC public key. This
- // is used for the CertificateVerify message.
- uint16_t dc_cert_verify_algorithm = 0;
-
- // algorithm is the signature scheme of the signature over the delegated
- // credential itself, made by the end-entity certificate's public key.
- uint16_t algorithm = 0;
-
- // pkey is the public key parsed from |public_key|.
- UniquePtr<EVP_PKEY> pkey;
-
- private:
- friend DC* New<DC>();
- DC();
+enum class SSLCredentialType {
+ kX509,
+ kDelegated,
};
-// ssl_signing_with_dc returns true if the peer has indicated support for
-// delegated credentials and this host has sent a delegated credential in
-// response. If this is true then we've committed to using the DC in the
-// handshake.
-bool ssl_signing_with_dc(const SSL_HANDSHAKE *hs);
+BSSL_NAMESPACE_END
+
+// SSL_CREDENTIAL is exported to C, so it must be defined outside the namespace.
+struct ssl_credential_st : public bssl::RefCounted<ssl_credential_st> {
+ explicit ssl_credential_st(bssl::SSLCredentialType type);
+ ssl_credential_st(const ssl_credential_st &) = delete;
+ ssl_credential_st &operator=(const ssl_credential_st &) = delete;
+
+ // Dup returns a copy of the credential, or nullptr on error. The |ex_data|
+ // values are not copied. This is only used on the default credential, whose
+ // |ex_data| is inaccessible.
+ bssl::UniquePtr<SSL_CREDENTIAL> Dup() const;
+
+ // ClearCertAndKey erases any certificate and private key on the credential.
+ void ClearCertAndKey();
+
+ // UsesX509 returns true if the credential type uses an X.509 certificate.
+ bool UsesX509() const;
+
+ // UsesPrivateKey returns true if the credential type uses an asymmetric
+ // private key.
+ bool UsesPrivateKey() const;
+
+ // IsComplete returns whether all required fields in the credential have been
+ // filled in.
+ bool IsComplete() const;
+
+ // SetLeafCert sets the leaf certificate to |leaf|, leaving the remaining
+ // certificates unmodified. It returns true on success and false on error. If
+ // |discard_key_on_mismatch| is true and the private key is inconsistent with
+ // the new leaf certificate, it is silently discarded.
+ bool SetLeafCert(bssl::UniquePtr<CRYPTO_BUFFER> leaf,
+ bool discard_key_on_mismatch);
+
+ // AppendIntermediateCert appends |cert| to the certificate chain. If there is
+ // no leaf certificate configured, it leaves a placeholder null in |chain|. It
+ // returns one on success and zero on error.
+ bool AppendIntermediateCert(bssl::UniquePtr<CRYPTO_BUFFER> cert);
+
+ // type is the credential type and determines which other fields apply.
+ bssl::SSLCredentialType type;
+
+ // pubkey is the cached public key of the credential. Unlike |privkey|, it is
+ // always present and is extracted from the certificate, delegated credential,
+ // etc.
+ bssl::UniquePtr<EVP_PKEY> pubkey;
+
+ // privkey is the private key of the credential. It may be omitted in favor of
+ // |key_method|.
+ bssl::UniquePtr<EVP_PKEY> privkey;
+
+ // key_method, if non-null, is a set of callbacks to call for private key
+ // operations.
+ const SSL_PRIVATE_KEY_METHOD *key_method = nullptr;
+
+ // sigalgs, if non-empty, is the set of signature algorithms supported by the
+ // private key in decreasing order of preference. If empty, the default list
+ // is used.
+ //
+ // In delegated credentials, this field is not configurable and is instead
+ // computed from the dc_cert_verify_algorithm field.
+ bssl::Array<uint16_t> sigalgs;
+
+ // chain contains the certificate chain, with the leaf at the beginning. The
+ // first element of |chain| may be nullptr to indicate that the leaf
+ // certificate has not yet been set.
+ // If |chain| != nullptr -> len(chain) >= 1
+ // If |chain[0]| == nullptr -> len(chain) >= 2.
+ // |chain[1..]| != nullptr
+ bssl::UniquePtr<STACK_OF(CRYPTO_BUFFER)> chain;
+
+ // dc is the DelegatedCredential structure, if this is a delegated credential.
+ bssl::UniquePtr<CRYPTO_BUFFER> dc;
+
+ // dc_algorithm is the signature scheme of the signature over the delegated
+ // credential itself, made by the end-entity certificate's public key.
+ uint16_t dc_algorithm = 0;
+
+ // Signed certificate timestamp list to be sent to the client, if requested
+ bssl::UniquePtr<CRYPTO_BUFFER> signed_cert_timestamp_list;
+
+ // OCSP response to be sent to the client, if requested.
+ bssl::UniquePtr<CRYPTO_BUFFER> ocsp_response;
+
+ CRYPTO_EX_DATA ex_data;
+
+ private:
+ friend RefCounted;
+ ~ssl_credential_st();
+};
+
+BSSL_NAMESPACE_BEGIN
+
+// ssl_get_credential_list computes |hs|'s credential list. On success, it
+// writes it to |*out| and returns true. Otherwise, it returns false. The
+// credential list may be empty, in which case this function will successfully
+// return an empty array.
+//
+// The pointers in the result are only valid until |hs| is next mutated.
+bool ssl_get_credential_list(SSL_HANDSHAKE *hs, Array<SSL_CREDENTIAL *> *out);
// Handshake functions.
@@ -1690,7 +1746,7 @@
state12_start_accept = 0,
state12_read_client_hello,
state12_read_client_hello_after_ech,
- state12_select_certificate,
+ state12_cert_callback,
state12_tls13,
state12_select_parameters,
state12_send_server_hello,
@@ -1969,8 +2025,8 @@
// received in a CertificateRequest message.
Array<uint8_t> certificate_types;
- // local_pubkey is the public key we are authenticating as.
- UniquePtr<EVP_PKEY> local_pubkey;
+ // credential is the credential we are using for the handshake.
+ UniquePtr<SSL_CREDENTIAL> credential;
// peer_pubkey is the public key parsed from the peer's leaf certificate.
UniquePtr<EVP_PKEY> peer_pubkey;
@@ -2380,18 +2436,10 @@
bool tls1_get_legacy_signature_algorithm(uint16_t *out, const EVP_PKEY *pkey);
// tls1_choose_signature_algorithm sets |*out| to a signature algorithm for use
-// with |hs|'s private key based on the peer's preferences and the algorithms
-// supported. It returns true on success and false on error.
-bool tls1_choose_signature_algorithm(SSL_HANDSHAKE *hs, uint16_t *out);
-
-// tls1_get_peer_verify_algorithms returns the signature schemes for which the
-// peer indicated support.
-//
-// NOTE: The related function |SSL_get0_peer_verify_algorithms| only has
-// well-defined behavior during the callbacks set by |SSL_CTX_set_cert_cb| and
-// |SSL_CTX_set_client_cert_cb|, or when the handshake is paused because of
-// them.
-Span<const uint16_t> tls1_get_peer_verify_algorithms(const SSL_HANDSHAKE *hs);
+// with |cred| based on the peer's preferences and the algorithms supported. It
+// returns true on success and false on error.
+bool tls1_choose_signature_algorithm(SSL_HANDSHAKE *hs,
+ const SSL_CREDENTIAL *cred, uint16_t *out);
// tls12_add_verify_sigalgs adds the signature algorithms acceptable for the
// peer signature to |out|. It returns true on success and false on error.
@@ -2419,42 +2467,36 @@
explicit CERT(const SSL_X509_METHOD *x509_method);
~CERT();
- UniquePtr<EVP_PKEY> privatekey;
+ bool is_valid() const { return default_credential != nullptr; }
- // chain contains the certificate chain, with the leaf at the beginning. The
- // first element of |chain| may be NULL to indicate that the leaf certificate
- // has not yet been set.
- // If |chain| != NULL -> len(chain) >= 1
- // If |chain[0]| == NULL -> len(chain) >= 2.
- // |chain[1..]| != NULL
- UniquePtr<STACK_OF(CRYPTO_BUFFER)> chain;
+ // credentials is the list of credentials to select between. Elements of this
+ // array immutable.
+ GrowableArray<UniquePtr<SSL_CREDENTIAL>> credentials;
- // x509_chain may contain a parsed copy of |chain[1..]|. This is only used as
- // a cache in order to implement “get0” functions that return a non-owning
- // pointer to the certificate chain.
- STACK_OF(X509) *x509_chain = nullptr;
-
- // x509_leaf may contain a parsed copy of the first element of |chain|. This
- // is only used as a cache in order to implement “get0” functions that return
- // a non-owning pointer to the certificate chain.
- X509 *x509_leaf = nullptr;
-
- // x509_stash contains the last |X509| object append to the chain. This is a
- // workaround for some third-party code that continue to use an |X509| object
- // even after passing ownership with an “add0” function.
- X509 *x509_stash = nullptr;
-
- // key_method, if non-NULL, is a set of callbacks to call for private key
- // operations.
- const SSL_PRIVATE_KEY_METHOD *key_method = nullptr;
+ // default_credential is the credential configured by the legacy,
+ // non-credential-based APIs. If IsComplete() returns true, it is appended to
+ // the list of credentials.
+ UniquePtr<SSL_CREDENTIAL> default_credential;
// x509_method contains pointers to functions that might deal with |X509|
// compatibility, or might be a no-op, depending on the application.
const SSL_X509_METHOD *x509_method = nullptr;
- // sigalgs, if non-empty, is the set of signature algorithms supported by
- // |privatekey| in decreasing order of preference.
- Array<uint16_t> sigalgs;
+ // x509_chain may contain a parsed copy of |chain[1..]| from the default
+ // credential. This is only used as a cache in order to implement “get0”
+ // functions that return a non-owning pointer to the certificate chain.
+ STACK_OF(X509) *x509_chain = nullptr;
+
+ // x509_leaf may contain a parsed copy of the first element of |chain| from
+ // the default credential. This is only used as a cache in order to implement
+ // “get0” functions that return a non-owning pointer to the certificate chain.
+ X509 *x509_leaf = nullptr;
+
+ // x509_stash contains the last |X509| object append to the default
+ // credential's chain. This is a workaround for some third-party code that
+ // continue to use an |X509| object even after passing ownership with an
+ // “add0” function.
+ X509 *x509_stash = nullptr;
// Certificate setup callback: if set is called whenever a
// certificate may be required (client or server). the callback
@@ -2469,29 +2511,10 @@
// store is used instead.
X509_STORE *verify_store = nullptr;
- // Signed certificate timestamp list to be sent to the client, if requested
- UniquePtr<CRYPTO_BUFFER> signed_cert_timestamp_list;
-
- // OCSP response to be sent to the client, if requested.
- UniquePtr<CRYPTO_BUFFER> ocsp_response;
-
// sid_ctx partitions the session space within a shared session cache or
// ticket key. Only sessions with a matching value will be accepted.
uint8_t sid_ctx_length = 0;
uint8_t sid_ctx[SSL_MAX_SID_CTX_LENGTH] = {0};
-
- // Delegated credentials.
-
- // dc is the delegated credential to send to the peer (if requested).
- UniquePtr<DC> dc = nullptr;
-
- // dc_privatekey is used instead of |privatekey| or |key_method| to
- // authenticate the host if a delegated credential is used in the handshake.
- UniquePtr<EVP_PKEY> dc_privatekey = nullptr;
-
- // dc_key_method, if not NULL, is used instead of |dc_privatekey| to
- // authenticate the host.
- const SSL_PRIVATE_KEY_METHOD *dc_key_method = nullptr;
};
// |SSL_PROTOCOL_METHOD| abstracts between TLS and DTLS.
@@ -2795,10 +2818,6 @@
// session_reused indicates whether a session was resumed.
bool session_reused : 1;
- // delegated_credential_used is whether we presented a delegated credential to
- // the peer.
- bool delegated_credential_used : 1;
-
bool send_connection_binding : 1;
// channel_id_valid is true if, on the server, the client has negotiated a
