grpc 1.62.0 → 1.68.1

data/third_party/boringssl-with-bazel/src/ssl/internal.h

@@ -146,6 +146,8 @@
 
 #include <stdlib.h>
 
+#include <algorithm>
+#include <bitset>
 #include <initializer_list>
 #include <limits>
 #include <new>
@@ -153,6 +155,7 @@
 #include <utility>
 
 #include <openssl/aead.h>
+#include <openssl/aes.h>
 #include <openssl/curve25519.h>
 #include <openssl/err.h>
 #include <openssl/hpke.h>
@@ -227,23 +230,6 @@ UniquePtr<T> MakeUnique(Args &&... args) {
   return UniquePtr<T>(New<T>(std::forward<Args>(args)...));
 }
 
-#if defined(BORINGSSL_ALLOW_CXX_RUNTIME)
-#define HAS_VIRTUAL_DESTRUCTOR
-#define PURE_VIRTUAL = 0
-#else
-// HAS_VIRTUAL_DESTRUCTOR should be declared in any base class which defines a
-// virtual destructor. This avoids a dependency on |_ZdlPv| and prevents the
-// class from being used with |delete|.
-#define HAS_VIRTUAL_DESTRUCTOR \
-  void operator delete(void *) { abort(); }
-
-// PURE_VIRTUAL should be used instead of = 0 when defining pure-virtual
-// functions. This avoids a dependency on |__cxa_pure_virtual| but loses
-// compile-time checking.
-#define PURE_VIRTUAL \
-  { abort(); }
-#endif
-
 // Array<T> is an owning array of elements of |T|.
 template <typename T>
 class Array {
@@ -329,7 +315,7 @@ class Array {
     if (!Init(in.size())) {
       return false;
     }
-    OPENSSL_memcpy(data_, in.data(), sizeof(T) * in.size());
+    std::copy(in.begin(), in.end(), data_);
     return true;
   }
 
@@ -472,6 +458,48 @@ inline size_t GetAllNames(const char **out, size_t max_out,
   return fixed_names.size() + objects.size();
 }
 
+// RefCounted is a common base for ref-counted types. This is an instance of the
+// C++ curiously-recurring template pattern, so a type Foo must subclass
+// RefCounted<Foo>. It additionally must friend RefCounted<Foo> to allow calling
+// the destructor.
+template <typename Derived>
+class RefCounted {
+ public:
+  RefCounted(const RefCounted &) = delete;
+  RefCounted &operator=(const RefCounted &) = delete;
+
+  // These methods are intentionally named differently from `bssl::UpRef` to
+  // avoid a collision. Only the implementations of `FOO_up_ref` and `FOO_free`
+  // should call these.
+  void UpRefInternal() { CRYPTO_refcount_inc(&references_); }
+  void DecRefInternal() {
+    if (CRYPTO_refcount_dec_and_test_zero(&references_)) {
+      Derived *d = static_cast<Derived *>(this);
+      d->~Derived();
+      OPENSSL_free(d);
+    }
+  }
+
+ protected:
+  // Ensure that only `Derived`, which must inherit from `RefCounted<Derived>`,
+  // can call the constructor. This catches bugs where someone inherited from
+  // the wrong base.
+  class CheckSubClass {
+   private:
+    friend Derived;
+    CheckSubClass() = default;
+  };
+  RefCounted(CheckSubClass) {
+    static_assert(std::is_base_of<RefCounted, Derived>::value,
+                  "Derived must subclass RefCounted<Derived>");
+  }
+
+  ~RefCounted() = default;
+
+ private:
+  CRYPTO_refcount_t references_ = 1;
+};
+
 
 // Protocol versions.
 //
@@ -554,13 +582,14 @@ BSSL_NAMESPACE_BEGIN
 #define SSL_kGENERIC 0x00000008u
 
 // Bits for |algorithm_auth| (server authentication).
-#define SSL_aRSA 0x00000001u
-#define SSL_aECDSA 0x00000002u
+#define SSL_aRSA_SIGN 0x00000001u
+#define SSL_aRSA_DECRYPT 0x00000002u
+#define SSL_aECDSA 0x00000004u
 // SSL_aPSK is set for both PSK and ECDHE_PSK.
-#define SSL_aPSK 0x00000004u
-#define SSL_aGENERIC 0x00000008u
+#define SSL_aPSK 0x00000008u
+#define SSL_aGENERIC 0x00000010u
 
-#define SSL_aCERT (SSL_aRSA | SSL_aECDSA)
+#define SSL_aCERT (SSL_aRSA_SIGN | SSL_aRSA_DECRYPT | SSL_aECDSA)
 
 // Bits for |algorithm_enc| (symmetric encryption).
 #define SSL_3DES 0x00000001u
@@ -661,8 +690,9 @@ bool ssl_create_cipher_list(UniquePtr<SSLCipherPreferenceList> *out_cipher_list,
                             bool strict);
 
 // ssl_cipher_auth_mask_for_key returns the mask of cipher |algorithm_auth|
-// values suitable for use with |key| in TLS 1.2 and below.
-uint32_t ssl_cipher_auth_mask_for_key(const EVP_PKEY *key);
+// values suitable for use with |key| in TLS 1.2 and below. |sign_ok| indicates
+// whether |key| may be used for signing.
+uint32_t ssl_cipher_auth_mask_for_key(const EVP_PKEY *key, bool sign_ok);
 
 // ssl_cipher_uses_certificate_auth returns whether |cipher| authenticates the
 // server and, optionally, the client with a certificate.
@@ -681,12 +711,11 @@ bool ssl_cipher_requires_server_key_exchange(const SSL_CIPHER *cipher);
 size_t ssl_cipher_get_record_split_len(const SSL_CIPHER *cipher);
 
 // ssl_choose_tls13_cipher returns an |SSL_CIPHER| corresponding with the best
-// available from |cipher_suites| compatible with |version|, |group_id|, and
-// |policy|. It returns NULL if there isn't a compatible cipher. |has_aes_hw|
-// indicates if the choice should be made as if support for AES in hardware
-// is available.
+// available from |cipher_suites| compatible with |version| and |policy|. It
+// returns NULL if there isn't a compatible cipher. |has_aes_hw| indicates if
+// the choice should be made as if support for AES in hardware is available.
 const SSL_CIPHER *ssl_choose_tls13_cipher(CBS cipher_suites, bool has_aes_hw,
-                                          uint16_t version, uint16_t group_id,
+                                          uint16_t version,
                                           enum ssl_compliance_policy_t policy);
 
 // ssl_tls13_cipher_meets_policy returns true if |cipher_id| is acceptable given
@@ -783,6 +812,16 @@ bool tls1_prf(const EVP_MD *digest, Span<uint8_t> out,
 
 // Encryption layer.
 
+class RecordNumberEncrypter {
+ public:
+  virtual ~RecordNumberEncrypter() = default;
+  static constexpr bool kAllowUniquePtr = true;
+
+  virtual size_t KeySize() = 0;
+  virtual bool SetKey(Span<const uint8_t> key) = 0;
+  virtual bool GenerateMask(Span<uint8_t> out, Span<const uint8_t> sample) = 0;
+};
+
 // SSLAEADContext contains information about an AEAD that is being used to
 // encrypt an SSL connection.
 class SSLAEADContext {
@@ -888,6 +927,17 @@ class SSLAEADContext {
 
   bool GetIV(const uint8_t **out_iv, size_t *out_iv_len) const;
 
+  RecordNumberEncrypter *GetRecordNumberEncrypter() {
+    return rn_encrypter_.get();
+  }
+
+  // GenerateRecordNumberMask computes the mask used for DTLS 1.3 record number
+  // encryption (RFC 9147 section 4.2.3), writing it to |out|. The |out| buffer
+  // must be sized to AES_BLOCK_SIZE. The |sample| buffer must be at least 16
+  // bytes, as required by the AES and ChaCha20 cipher suites in RFC 9147. Extra
+  // bytes in |sample| will be ignored.
+  bool GenerateRecordNumberMask(Span<uint8_t> out, Span<const uint8_t> sample);
+
  private:
   // GetAdditionalData returns the additional data, writing into |storage| if
   // necessary.
@@ -896,6 +946,8 @@ class SSLAEADContext {
                                         uint64_t seqnum, size_t plaintext_len,
                                         Span<const uint8_t> header);
 
+  void CreateRecordNumberEncrypter();
+
   const SSL_CIPHER *cipher_;
   ScopedEVP_AEAD_CTX ctx_;
   // fixed_nonce_ contains any bytes of the nonce that are fixed for all
@@ -904,6 +956,7 @@ class SSLAEADContext {
   uint8_t fixed_nonce_len_ = 0, variable_nonce_len_ = 0;
   // version_ is the wire version that should be used with this AEAD.
   uint16_t version_;
+  UniquePtr<RecordNumberEncrypter> rn_encrypter_;
   // is_dtls_ is whether DTLS is being used with this AEAD.
   bool is_dtls_;
   // variable_nonce_included_in_record_ is true if the variable nonce
@@ -923,20 +976,70 @@ class SSLAEADContext {
   bool ad_is_header_ : 1;
 };
 
+class AESRecordNumberEncrypter : public RecordNumberEncrypter {
+ public:
+  bool SetKey(Span<const uint8_t> key) override;
+  bool GenerateMask(Span<uint8_t> out, Span<const uint8_t> sample) override;
+
+ private:
+  AES_KEY key_;
+};
+
+class AES128RecordNumberEncrypter : public AESRecordNumberEncrypter {
+ public:
+  size_t KeySize() override;
+};
+
+class AES256RecordNumberEncrypter : public AESRecordNumberEncrypter {
+ public:
+  size_t KeySize() override;
+};
+
+class ChaChaRecordNumberEncrypter : public RecordNumberEncrypter {
+ public:
+  size_t KeySize() override;
+  bool SetKey(Span<const uint8_t> key) override;
+  bool GenerateMask(Span<uint8_t> out, Span<const uint8_t> sample) override;
+
+ private:
+  static const size_t kKeySize = 32;
+  uint8_t key_[kKeySize];
+};
+
+#if defined(BORINGSSL_UNSAFE_FUZZER_MODE)
+class NullRecordNumberEncrypter : public RecordNumberEncrypter {
+ public:
+  size_t KeySize() override;
+  bool SetKey(Span<const uint8_t> key) override;
+  bool GenerateMask(Span<uint8_t> out, Span<const uint8_t> sample) override;
+};
+#endif  // BORINGSSL_UNSAFE_FUZZER_MODE
+
 
 // DTLS replay bitmap.
 
 // DTLS1_BITMAP maintains a sliding window of 64 sequence numbers to detect
 // replayed packets. It should be initialized by zeroing every field.
 struct DTLS1_BITMAP {
-  // map is a bit mask of the last 64 sequence numbers. Bit
-  // |1<<i| corresponds to |max_seq_num - i|.
-  uint64_t map = 0;
+  // map is a bitset of sequence numbers that have been seen. Bit i corresponds
+  // to |max_seq_num - i|.
+  std::bitset<256> map;
   // max_seq_num is the largest sequence number seen so far as a 64-bit
   // integer.
   uint64_t max_seq_num = 0;
 };
 
+// reconstruct_seqnum takes the low order bits of a record sequence number from
+// the wire and reconstructs the full sequence number. It does so using the
+// algorithm described in section 4.2.2 of RFC 9147, where |wire_seq| is the
+// low bits of the sequence number as seen on the wire, |seq_mask| is a bitmask
+// of 8 or 16 1 bits corresponding to the length of the sequence number on the
+// wire, and |max_valid_seqnum| is the largest sequence number of a record
+// successfully deprotected in this epoch. This function returns the sequence
+// number that is numerically closest to one plus |max_valid_seqnum| that when
+// bitwise and-ed with |seq_mask| equals |wire_seq|.
+OPENSSL_EXPORT uint64_t reconstruct_seqnum(uint16_t wire_seq, uint64_t seq_mask,
+                                           uint64_t max_valid_seqnum);
 
 // Record layer.
 
@@ -990,17 +1093,9 @@ enum ssl_open_record_t dtls_open_record(SSL *ssl, uint8_t *out_type,
                                         size_t *out_consumed,
                                         uint8_t *out_alert, Span<uint8_t> in);
 
-// ssl_seal_align_prefix_len returns the length of the prefix before the start
-// of the bulk of the ciphertext when sealing a record with |ssl|. Callers may
-// use this to align buffers.
-//
-// Note when TLS 1.0 CBC record-splitting is enabled, this includes the one byte
-// record and is the offset into second record's ciphertext. Thus sealing a
-// small record may result in a smaller output than this value.
-//
-// TODO(davidben): Is this alignment valuable? Record-splitting makes this a
-// mess.
-size_t ssl_seal_align_prefix_len(const SSL *ssl);
+// ssl_needs_record_splitting returns one if |ssl|'s current outgoing cipher
+// state needs record-splitting and zero otherwise.
+bool ssl_needs_record_splitting(const SSL *ssl);
 
 // tls_seal_record seals a new record of type |type| and body |in| and writes it
 // to |out|. At most |max_out| bytes will be written. It returns true on success
@@ -1008,7 +1103,7 @@ size_t ssl_seal_align_prefix_len(const SSL *ssl);
 // 1/n-1 record splitting and may write two records concatenated.
 //
 // For a large record, the bulk of the ciphertext will begin
-// |ssl_seal_align_prefix_len| bytes into out. Aligning |out| appropriately may
+// |tls_seal_align_prefix_len| bytes into out. Aligning |out| appropriately may
 // improve performance. It writes at most |in_len| + |SSL_max_seal_overhead|
 // bytes to |out|.
 //
@@ -1016,26 +1111,25 @@ size_t ssl_seal_align_prefix_len(const SSL *ssl);
 bool tls_seal_record(SSL *ssl, uint8_t *out, size_t *out_len, size_t max_out,
                      uint8_t type, const uint8_t *in, size_t in_len);
 
-enum dtls1_use_epoch_t {
-  dtls1_use_previous_epoch,
-  dtls1_use_current_epoch,
-};
+// dtls_record_header_write_len returns the length of the record header that
+// will be written at |epoch|.
+size_t dtls_record_header_write_len(const SSL *ssl, uint16_t epoch);
 
 // dtls_max_seal_overhead returns the maximum overhead, in bytes, of sealing a
 // record.
-size_t dtls_max_seal_overhead(const SSL *ssl, enum dtls1_use_epoch_t use_epoch);
+size_t dtls_max_seal_overhead(const SSL *ssl, uint16_t epoch);
 
 // dtls_seal_prefix_len returns the number of bytes of prefix to reserve in
 // front of the plaintext when sealing a record in-place.
-size_t dtls_seal_prefix_len(const SSL *ssl, enum dtls1_use_epoch_t use_epoch);
+size_t dtls_seal_prefix_len(const SSL *ssl, uint16_t epoch);
 
-// dtls_seal_record implements |tls_seal_record| for DTLS. |use_epoch| selects
-// which epoch's cipher state to use. Unlike |tls_seal_record|, |in| and |out|
-// may alias but, if they do, |in| must be exactly |dtls_seal_prefix_len| bytes
+// dtls_seal_record implements |tls_seal_record| for DTLS. |epoch| selects which
+// epoch's cipher state to use. Unlike |tls_seal_record|, |in| and |out| may
+// alias but, if they do, |in| must be exactly |dtls_seal_prefix_len| bytes
 // ahead of |out|.
 bool dtls_seal_record(SSL *ssl, uint8_t *out, size_t *out_len, size_t max_out,
                       uint8_t type, const uint8_t *in, size_t in_len,
-                      enum dtls1_use_epoch_t use_epoch);
+                      uint16_t epoch);
 
 // ssl_process_alert processes |in| as an alert and updates |ssl|'s shutdown
 // state. It returns one of |ssl_open_record_discard|, |ssl_open_record_error|,
@@ -1047,9 +1141,6 @@ enum ssl_open_record_t ssl_process_alert(SSL *ssl, uint8_t *out_alert,
 
 // 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
@@ -1066,10 +1157,10 @@ enum ssl_private_key_result_t ssl_private_key_decrypt(SSL_HANDSHAKE *hs,
                                                       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, bool is_verify);
 
 // ssl_public_key_verify verifies that the |signature| is valid for the public
 // key |pkey| and input |in|, using the signature algorithm |sigalg|.
@@ -1093,18 +1184,17 @@ class SSLKeyShare {
  public:
   virtual ~SSLKeyShare() {}
   static constexpr bool kAllowUniquePtr = true;
-  HAS_VIRTUAL_DESTRUCTOR
 
   // Create returns a SSLKeyShare instance for use with group |group_id| or
   // nullptr on error.
   static UniquePtr<SSLKeyShare> Create(uint16_t group_id);
 
   // GroupID returns the group ID.
-  virtual uint16_t GroupID() const PURE_VIRTUAL;
+  virtual uint16_t GroupID() const = 0;
 
   // Generate generates a keypair and writes the public key to |out_public_key|.
   // It returns true on success and false on error.
-  virtual bool Generate(CBB *out_public_key) PURE_VIRTUAL;
+  virtual bool Generate(CBB *out_public_key) = 0;
 
   // Encap generates an ephemeral, symmetric secret and encapsulates it with
   // |peer_key|. On success, it returns true, writes the encapsulated secret to
@@ -1112,13 +1202,13 @@ class SSLKeyShare {
   // it returns false and sets |*out_alert| to an alert to send to the peer.
   virtual bool Encap(CBB *out_ciphertext, Array<uint8_t> *out_secret,
                      uint8_t *out_alert,
-                     Span<const uint8_t> peer_key) PURE_VIRTUAL;
+                     Span<const uint8_t> peer_key) = 0;
 
   // Decap decapsulates the symmetric secret in |ciphertext|. On success, it
   // returns true and sets |*out_secret| to the shared secret. On failure, it
   // returns false and sets |*out_alert| to an alert to send to the peer.
   virtual bool Decap(Array<uint8_t> *out_secret, uint8_t *out_alert,
-                     Span<const uint8_t> ciphertext) PURE_VIRTUAL;
+                     Span<const uint8_t> ciphertext) = 0;
 
   // SerializePrivateKey writes the private key to |out|, returning true if
   // successful and false otherwise. It should be called after |Generate|.
@@ -1307,10 +1397,6 @@ int ssl_write_buffer_flush(SSL *ssl);
 
 // 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
@@ -1328,11 +1414,6 @@ bool ssl_parse_cert_chain(uint8_t *out_alert,
                           uint8_t *out_leaf_sha256, CBS *cbs,
                           CRYPTO_BUFFER_POOL *pool);
 
-// ssl_add_cert_chain adds |hs->ssl|'s certificate chain to |cbb| in the format
-// used by a TLS Certificate message. If there is no certificate chain, it emits
-// an empty certificate list. It returns true on success and false on error.
-bool ssl_add_cert_chain(SSL_HANDSHAKE *hs, CBB *cbb);
-
 enum ssl_key_usage_t {
   key_usage_digital_signature = 0,
   key_usage_encipherment = 2,
@@ -1371,11 +1452,6 @@ bool ssl_add_client_CA_list(SSL_HANDSHAKE *hs, CBB *cbb);
 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.
 
@@ -1439,7 +1515,8 @@ bool tls13_finished_mac(SSL_HANDSHAKE *hs, uint8_t *out, size_t *out_len,
 // tls13_derive_session_psk calculates the PSK for this session based on the
 // resumption master secret and |nonce|. It returns true on success, and false
 // on failure.
-bool tls13_derive_session_psk(SSL_SESSION *session, Span<const uint8_t> nonce);
+bool tls13_derive_session_psk(SSL_SESSION *session, Span<const uint8_t> nonce,
+                              bool is_dtls);
 
 // tls13_write_psk_binder calculates the PSK binder value over |transcript| and
 // |msg|, and replaces the last bytes of |msg| with the resulting value. It
@@ -1584,43 +1661,117 @@ size_t ssl_ech_extension_body_length(const EVP_HPKE_AEAD *aead, size_t enc_len,
 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
-// draft-ietf-tls-subcerts-03.
-struct DC {
-  static constexpr bool kAllowUniquePtr = true;
-  ~DC();
+enum class SSLCredentialType {
+  kX509,
+  kDelegated,
+};
+
+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);
+
+  // ClearIntermediateCerts clears intermediate certificates in the certificate
+  // chain, while preserving the leaf.
+  void ClearIntermediateCerts();
 
-  // Dup returns a copy of this DC and takes references to |raw| and |pkey|.
-  UniquePtr<DC> Dup();
+  // 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);
 
-  // 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);
+  // type is the credential type and determines which other fields apply.
+  bssl::SSLCredentialType type;
 
-  // raw is the delegated credential encoded as specified in draft-ietf-tls-
-  // subcerts-03.
-  UniquePtr<CRYPTO_BUFFER> raw;
+  // 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;
 
-  // expected_cert_verify_algorithm is the signature scheme of the DC public
-  // key.
-  uint16_t expected_cert_verify_algorithm = 0;
+  // privkey is the private key of the credential. It may be omitted in favor of
+  // |key_method|.
+  bssl::UniquePtr<EVP_PKEY> privkey;
 
-  // pkey is the public key parsed from |public_key|.
-  UniquePtr<EVP_PKEY> pkey;
+  // 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 DC* New<DC>();
-  DC();
+  friend RefCounted;
+  ~ssl_credential_st();
 };
 
-// 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_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.
@@ -1661,7 +1812,7 @@ enum tls12_server_hs_state_t {
   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,
@@ -1896,7 +2047,8 @@ struct SSL_HANDSHAKE {
   Array<uint16_t> peer_supported_group_list;
 
   // peer_delegated_credential_sigalgs are the signature algorithms the peer
-  // supports with delegated credentials.
+  // supports with delegated credentials, or empty if the peer does not support
+  // delegated credentials.
   Array<uint16_t> peer_delegated_credential_sigalgs;
 
   // peer_key is the peer's ECDH key for a TLS 1.2 client.
@@ -1939,8 +2091,8 @@ struct SSL_HANDSHAKE {
   // 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;
@@ -2006,10 +2158,6 @@ struct SSL_HANDSHAKE {
   // ocsp_stapling_requested is true if a client requested OCSP stapling.
   bool ocsp_stapling_requested : 1;
 
-  // delegated_credential_requested is true if the peer indicated support for
-  // the delegated credential extension.
-  bool delegated_credential_requested : 1;
-
   // should_ack_sni is used by a server and indicates that the SNI extension
   // should be echoed in the ServerHello.
   bool should_ack_sni : 1;
@@ -2085,6 +2233,10 @@ struct SSL_HANDSHAKE {
   // record layer.
   uint16_t early_data_written = 0;
 
+  // signature_algorithm is the signature algorithm to be used in signing with
+  // the selected credential, or zero if not applicable or not yet selected.
+  uint16_t signature_algorithm = 0;
+
   // ech_config_id is the ECH config sent by the client.
   uint8_t ech_config_id = 0;
 
@@ -2239,6 +2391,11 @@ bool ssl_is_valid_alpn_list(Span<const uint8_t> in);
 bool ssl_is_alpn_protocol_allowed(const SSL_HANDSHAKE *hs,
                                   Span<const uint8_t> protocol);
 
+// ssl_alpn_list_contains_protocol returns whether |list|, a serialized ALPN
+// protocol list, contains |protocol|.
+bool ssl_alpn_list_contains_protocol(Span<const uint8_t> list,
+                                     Span<const uint8_t> protocol);
+
 // ssl_negotiate_alpn negotiates the ALPN extension, if applicable. It returns
 // true on successful negotiation or if nothing was negotiated. It returns false
 // and sets |*out_alert| to an alert on error.
@@ -2287,8 +2444,14 @@ enum ssl_verify_result_t ssl_reverify_peer_cert(SSL_HANDSHAKE *hs,
                                                 bool send_alert);
 
 enum ssl_hs_wait_t ssl_get_finished(SSL_HANDSHAKE *hs);
+
+// ssl_send_finished adds a Finished message to the current flight of messages.
+// It returns true on success and false on error.
 bool ssl_send_finished(SSL_HANDSHAKE *hs);
-bool ssl_output_cert_chain(SSL_HANDSHAKE *hs);
+
+// ssl_send_tls12_certificate adds a TLS 1.2 Certificate message to the current
+// flight of messages. It returns true on success and false on error.
+bool ssl_send_tls12_certificate(SSL_HANDSHAKE *hs);
 
 // ssl_handshake_session returns the |SSL_SESSION| corresponding to the current
 // handshake. Note, in TLS 1.2 resumptions, this session is immutable.
@@ -2348,28 +2511,20 @@ bool tls1_parse_peer_sigalgs(SSL_HANDSHAKE *hs, const CBS *sigalgs);
 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.
 bool tls12_add_verify_sigalgs(const SSL_HANDSHAKE *hs, CBB *out);
 
 // tls12_check_peer_sigalg checks if |sigalg| is acceptable for the peer
-// signature. It returns true on success and false on error, setting
+// signature from |pkey|. It returns true on success and false on error, setting
 // |*out_alert| to an alert to send.
 bool tls12_check_peer_sigalg(const SSL_HANDSHAKE *hs, uint8_t *out_alert,
-                             uint16_t sigalg);
+                             uint16_t sigalg, EVP_PKEY *pkey);
 
 
 // Underdocumented functions.
@@ -2387,42 +2542,36 @@ struct CERT {
   explicit CERT(const SSL_X509_METHOD *x509_method);
   ~CERT();
 
-  UniquePtr<EVP_PKEY> privatekey;
-
-  // 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;
-
-  // 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;
+  bool is_valid() const { return default_credential != 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;
+  // credentials is the list of credentials to select between. Elements of this
+  // array immutable.
+  GrowableArray<UniquePtr<SSL_CREDENTIAL>> credentials;
 
-  // 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
@@ -2437,29 +2586,10 @@ struct CERT {
   // 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.
@@ -2763,10 +2893,6 @@ struct SSL3_STATE {
   // 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
@@ -2885,7 +3011,23 @@ struct SSL3_STATE {
 };
 
 // lengths of messages
-#define DTLS1_RT_HEADER_LENGTH 13
+#define DTLS1_RT_MAX_HEADER_LENGTH 13
+
+// DTLS_PLAINTEXT_RECORD_HEADER_LENGTH is the length of the DTLS record header
+// for plaintext records (in DTLS 1.3) or DTLS versions <= 1.2.
+#define DTLS_PLAINTEXT_RECORD_HEADER_LENGTH 13
+
+// DTLS1_3_RECORD_HEADER_LENGTH is the length of the DTLS 1.3 record header
+// sent by BoringSSL for encrypted records. Note that received encrypted DTLS
+// 1.3 records might have a different length header.
+#define DTLS1_3_RECORD_HEADER_WRITE_LENGTH 5
+
+static_assert(DTLS1_RT_MAX_HEADER_LENGTH >= DTLS_PLAINTEXT_RECORD_HEADER_LENGTH,
+              "DTLS1_RT_MAX_HEADER_LENGTH must not be smaller than defined "
+              "record header lengths");
+static_assert(DTLS1_RT_MAX_HEADER_LENGTH >= DTLS1_3_RECORD_HEADER_WRITE_LENGTH,
+              "DTLS1_RT_MAX_HEADER_LENGTH must not be smaller than defined "
+              "record header lengths");
 
 #define DTLS1_HM_HEADER_LENGTH 12
 
@@ -2965,6 +3107,11 @@ struct DTLS1_STATE {
   uint64_t last_write_sequence = 0;
   UniquePtr<SSLAEADContext> last_aead_write_ctx;
 
+
+  // In DTLS 1.3, this contains the write AEAD for the initial encryption level.
+  // TODO(crbug.com/boringssl/715): Drop this when it is no longer needed.
+  UniquePtr<SSLAEADContext> initial_aead_write_ctx;
+
   // incoming_messages is a ring buffer of incoming handshake messages that have
   // yet to be processed. The front of the ring buffer is message number
   // |handshake_read_seq|, at position |handshake_read_seq| %
@@ -3157,6 +3304,15 @@ struct SSL_CONFIG {
   // alps_use_new_codepoint if set indicates we use new ALPS extension codepoint
   // to negotiate and convey application settings.
   bool alps_use_new_codepoint : 1;
+
+  // check_client_certificate_type indicates whether the client, in TLS 1.2 and
+  // below, will check its certificate against the server's requested
+  // certificate types.
+  bool check_client_certificate_type : 1;
+
+  // check_ecdsa_curve indicates whether the server, in TLS 1.2 and below, will
+  // check its certificate against the client's supported ECDSA curves.
+  bool check_ecdsa_curve : 1;
 };
 
 // From RFC 8446, used in determining PSK modes.
@@ -3168,7 +3324,6 @@ struct SSL_CONFIG {
 static const size_t kMaxEarlyDataAccepted = 14336;
 
 UniquePtr<CERT> ssl_cert_dup(CERT *cert);
-void ssl_cert_clear_certs(CERT *cert);
 bool ssl_set_cert(CERT *cert, UniquePtr<CRYPTO_BUFFER> buffer);
 bool ssl_is_key_type_supported(int key_type);
 // ssl_compare_public_and_private_key returns true if |pubkey| is the public
@@ -3176,7 +3331,6 @@ bool ssl_is_key_type_supported(int key_type);
 // message on the error queue.
 bool ssl_compare_public_and_private_key(const EVP_PKEY *pubkey,
                                        const EVP_PKEY *privkey);
-bool ssl_cert_check_private_key(const CERT *cert, const EVP_PKEY *privkey);
 bool ssl_get_new_session(SSL_HANDSHAKE *hs);
 bool ssl_encrypt_ticket(SSL_HANDSHAKE *hs, CBB *out,
                         const SSL_SESSION *session);
@@ -3313,7 +3467,7 @@ int dtls1_write_app_data(SSL *ssl, bool *out_needs_handshake,
 // dtls1_write_record sends a record. It returns one on success and <= 0 on
 // error.
 int dtls1_write_record(SSL *ssl, int type, Span<const uint8_t> in,
-                       enum dtls1_use_epoch_t use_epoch);
+                       uint16_t epoch);
 
 int dtls1_retransmit_outgoing_messages(SSL *ssl);
 bool dtls1_parse_fragment(CBS *cbs, struct hm_header_st *out_hdr,
@@ -3459,7 +3613,7 @@ struct ssl_method_st {
   const bssl::SSL_X509_METHOD *x509_method;
 };
 
-struct ssl_ctx_st {
+struct ssl_ctx_st : public bssl::RefCounted<ssl_ctx_st> {
   explicit ssl_ctx_st(const SSL_METHOD *ssl_method);
   ssl_ctx_st(const ssl_ctx_st &) = delete;
   ssl_ctx_st &operator=(const ssl_ctx_st &) = delete;
@@ -3529,8 +3683,6 @@ struct ssl_ctx_st {
   SSL_SESSION *(*get_session_cb)(SSL *ssl, const uint8_t *data, int len,
                                  int *copy) = nullptr;
 
-  CRYPTO_refcount_t references = 1;
-
   // if defined, these override the X509_verify_cert() calls
   int (*app_verify_callback)(X509_STORE_CTX *store_ctx, void *arg) = nullptr;
   void *app_verify_arg = nullptr;
@@ -3767,8 +3919,8 @@ struct ssl_ctx_st {
   bool aes_hw_override_value : 1;
 
  private:
+  friend RefCounted;
   ~ssl_ctx_st();
-  friend OPENSSL_EXPORT void SSL_CTX_free(SSL_CTX *);
 };
 
 struct ssl_st {
@@ -3860,13 +4012,11 @@ struct ssl_st {
   bool enable_early_data : 1;
 };
 
-struct ssl_session_st {
+struct ssl_session_st : public bssl::RefCounted<ssl_session_st> {
   explicit ssl_session_st(const bssl::SSL_X509_METHOD *method);
   ssl_session_st(const ssl_session_st &) = delete;
   ssl_session_st &operator=(const ssl_session_st &) = delete;
 
-  CRYPTO_refcount_t references = 1;
-
   // ssl_version is the (D)TLS version that established the session.
   uint16_t ssl_version = 0;
 
@@ -4009,21 +4159,18 @@ struct ssl_session_st {
   bssl::Array<uint8_t> quic_early_data_context;
 
  private:
+  friend RefCounted;
   ~ssl_session_st();
-  friend OPENSSL_EXPORT void SSL_SESSION_free(SSL_SESSION *);
 };
 
-struct ssl_ech_keys_st {
-  ssl_ech_keys_st() = default;
-  ssl_ech_keys_st(const ssl_ech_keys_st &) = delete;
-  ssl_ech_keys_st &operator=(const ssl_ech_keys_st &) = delete;
+struct ssl_ech_keys_st : public bssl::RefCounted<ssl_ech_keys_st> {
+  ssl_ech_keys_st() : RefCounted(CheckSubClass()) {}
 
   bssl::GrowableArray<bssl::UniquePtr<bssl::ECHServerConfig>> configs;
-  CRYPTO_refcount_t references = 1;
 
  private:
+  friend RefCounted;
   ~ssl_ech_keys_st() = default;
-  friend OPENSSL_EXPORT void SSL_ECH_KEYS_free(SSL_ECH_KEYS *);
 };
 
 #endif  // OPENSSL_HEADER_SSL_INTERNAL_H