1 /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
4 * This package is an SSL implementation written
5 * by Eric Young (eay@cryptsoft.com).
6 * The implementation was written so as to conform with Netscapes SSL.
8 * This library is free for commercial and non-commercial use as long as
9 * the following conditions are aheared to. The following conditions
10 * apply to all code found in this distribution, be it the RC4, RSA,
11 * lhash, DES, etc., code; not just the SSL code. The SSL documentation
12 * included with this distribution is covered by the same copyright terms
13 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
15 * Copyright remains Eric Young's, and as such any Copyright notices in
16 * the code are not to be removed.
17 * If this package is used in a product, Eric Young should be given attribution
18 * as the author of the parts of the library used.
19 * This can be in the form of a textual message at program startup or
20 * in documentation (online or textual) provided with the package.
22 * Redistribution and use in source and binary forms, with or without
23 * modification, are permitted provided that the following conditions
25 * 1. Redistributions of source code must retain the copyright
26 * notice, this list of conditions and the following disclaimer.
27 * 2. Redistributions in binary form must reproduce the above copyright
28 * notice, this list of conditions and the following disclaimer in the
29 * documentation and/or other materials provided with the distribution.
30 * 3. All advertising materials mentioning features or use of this software
31 * must display the following acknowledgement:
32 * "This product includes cryptographic software written by
33 * Eric Young (eay@cryptsoft.com)"
34 * The word 'cryptographic' can be left out if the rouines from the library
35 * being used are not cryptographic related :-).
36 * 4. If you include any Windows specific code (or a derivative thereof) from
37 * the apps directory (application code) you must include an acknowledgement:
38 * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
40 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
41 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
43 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
44 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
45 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
46 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
48 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
49 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
52 * The licence and distribution terms for any publically available version or
53 * derivative of this code cannot be changed. i.e. this code cannot simply be
54 * copied and put under another distribution licence
55 * [including the GNU Public Licence.]
57 /* ====================================================================
58 * Copyright (c) 1998-2007 The OpenSSL Project. All rights reserved.
60 * Redistribution and use in source and binary forms, with or without
61 * modification, are permitted provided that the following conditions
64 * 1. Redistributions of source code must retain the above copyright
65 * notice, this list of conditions and the following disclaimer.
67 * 2. Redistributions in binary form must reproduce the above copyright
68 * notice, this list of conditions and the following disclaimer in
69 * the documentation and/or other materials provided with the
72 * 3. All advertising materials mentioning features or use of this
73 * software must display the following acknowledgment:
74 * "This product includes software developed by the OpenSSL Project
75 * for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
77 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
78 * endorse or promote products derived from this software without
79 * prior written permission. For written permission, please contact
80 * openssl-core@openssl.org.
82 * 5. Products derived from this software may not be called "OpenSSL"
83 * nor may "OpenSSL" appear in their names without prior written
84 * permission of the OpenSSL Project.
86 * 6. Redistributions of any form whatsoever must retain the following
88 * "This product includes software developed by the OpenSSL Project
89 * for use in the OpenSSL Toolkit (http://www.openssl.org/)"
91 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
92 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
93 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
94 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
95 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
96 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
97 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
98 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
99 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
100 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
101 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
102 * OF THE POSSIBILITY OF SUCH DAMAGE.
103 * ====================================================================
105 * This product includes cryptographic software written by Eric Young
106 * (eay@cryptsoft.com). This product includes software written by Tim
107 * Hudson (tjh@cryptsoft.com).
110 /* ====================================================================
111 * Copyright 2002 Sun Microsystems, Inc. ALL RIGHTS RESERVED.
112 * ECC cipher suite support in OpenSSL originally developed by
113 * SUN MICROSYSTEMS, INC., and contributed to the OpenSSL project.
115 /* ====================================================================
116 * Copyright 2005 Nokia. All rights reserved.
118 * The portions of the attached software ("Contribution") is developed by
119 * Nokia Corporation and is licensed pursuant to the OpenSSL open source
122 * The Contribution, originally written by Mika Kousa and Pasi Eronen of
123 * Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites
124 * support (see RFC 4279) to OpenSSL.
126 * No patent licenses or other rights except those expressly stated in
127 * the OpenSSL open source license shall be deemed granted or received
128 * expressly, by implication, estoppel, or otherwise.
130 * No assurances are provided by Nokia that the Contribution does not
131 * infringe the patent or other intellectual property rights of any third
132 * party or that the license provides you with all the necessary rights
133 * to make use of the Contribution.
135 * THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN
136 * ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA
137 * SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY
138 * OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR
142 #ifndef OPENSSL_HEADER_SSL_INTERNAL_H
143 #define OPENSSL_HEADER_SSL_INTERNAL_H
145 #include <openssl/base.h>
151 #include <type_traits>
154 #include <openssl/aead.h>
155 #include <openssl/err.h>
156 #include <openssl/lhash.h>
157 #include <openssl/mem.h>
158 #include <openssl/ssl.h>
159 #include <openssl/span.h>
160 #include <openssl/stack.h>
162 #include "../crypto/err/internal.h"
163 #include "../crypto/internal.h"
166 #if defined(OPENSSL_WINDOWS)
167 // Windows defines struct timeval in winsock2.h.
168 OPENSSL_MSVC_PRAGMA(warning(push, 3))
169 #include <winsock2.h>
170 OPENSSL_MSVC_PRAGMA(warning(pop))
172 #include <sys/time.h>
178 struct SSL_HANDSHAKE;
179 struct SSL_PROTOCOL_METHOD;
183 // New behaves like |new| but uses |OPENSSL_malloc| for memory allocation. It
184 // returns nullptr on allocation error. It only implements single-object
185 // allocation and not new T[n].
187 // Note: unlike |new|, this does not support non-public constructors.
188 template <typename T, typename... Args>
189 T *New(Args &&... args) {
190 void *t = OPENSSL_malloc(sizeof(T));
192 OPENSSL_PUT_ERROR(SSL, ERR_R_MALLOC_FAILURE);
195 return new (t) T(std::forward<Args>(args)...);
198 // Delete behaves like |delete| but uses |OPENSSL_free| to release memory.
200 // Note: unlike |delete| this does not support non-public destructors.
201 template <typename T>
209 // All types with kAllowUniquePtr set may be used with UniquePtr. Other types
210 // may be C structs which require a |BORINGSSL_MAKE_DELETER| registration.
212 template <typename T>
213 struct DeleterImpl<T, typename std::enable_if<T::kAllowUniquePtr>::type> {
214 static void Free(T *t) { Delete(t); }
218 // MakeUnique behaves like |std::make_unique| but returns nullptr on allocation
220 template <typename T, typename... Args>
221 UniquePtr<T> MakeUnique(Args &&... args) {
222 return UniquePtr<T>(New<T>(std::forward<Args>(args)...));
225 #if defined(BORINGSSL_ALLOW_CXX_RUNTIME)
226 #define HAS_VIRTUAL_DESTRUCTOR
227 #define PURE_VIRTUAL = 0
229 // HAS_VIRTUAL_DESTRUCTOR should be declared in any base class which defines a
230 // virtual destructor. This avoids a dependency on |_ZdlPv| and prevents the
231 // class from being used with |delete|.
232 #define HAS_VIRTUAL_DESTRUCTOR \
233 void operator delete(void *) { abort(); }
235 // PURE_VIRTUAL should be used instead of = 0 when defining pure-virtual
236 // functions. This avoids a dependency on |__cxa_pure_virtual| but loses
237 // compile-time checking.
238 #define PURE_VIRTUAL { abort(); }
241 // CONSTEXPR_ARRAY works around a VS 2015 bug where ranged for loops don't work
242 // on constexpr arrays.
243 #if defined(_MSC_VER) && !defined(__clang__) && _MSC_VER < 1910
244 #define CONSTEXPR_ARRAY const
246 #define CONSTEXPR_ARRAY constexpr
249 // Array<T> is an owning array of elements of |T|.
250 template <typename T>
253 // Array's default constructor creates an empty array.
255 Array(const Array &) = delete;
256 Array(Array &&other) { *this = std::move(other); }
258 ~Array() { Reset(); }
260 Array &operator=(const Array &) = delete;
261 Array &operator=(Array &&other) {
263 other.Release(&data_, &size_);
267 const T *data() const { return data_; }
268 T *data() { return data_; }
269 size_t size() const { return size_; }
270 bool empty() const { return size_ == 0; }
272 const T &operator[](size_t i) const { return data_[i]; }
273 T &operator[](size_t i) { return data_[i]; }
275 T *begin() { return data_; }
276 const T *cbegin() const { return data_; }
277 T *end() { return data_ + size_; }
278 const T *cend() const { return data_ + size_; }
280 void Reset() { Reset(nullptr, 0); }
282 // Reset releases the current contents of the array and takes ownership of the
283 // raw pointer supplied by the caller.
284 void Reset(T *new_data, size_t new_size) {
285 for (size_t i = 0; i < size_; i++) {
293 // Release releases ownership of the array to a raw pointer supplied by the
295 void Release(T **out, size_t *out_size) {
302 // Init replaces the array with a newly-allocated array of |new_size|
303 // default-constructed copies of |T|. It returns true on success and false on
306 // Note that if |T| is a primitive type like |uint8_t|, it is uninitialized.
307 bool Init(size_t new_size) {
313 if (new_size > std::numeric_limits<size_t>::max() / sizeof(T)) {
314 OPENSSL_PUT_ERROR(SSL, ERR_R_OVERFLOW);
317 data_ = reinterpret_cast<T*>(OPENSSL_malloc(new_size * sizeof(T)));
318 if (data_ == nullptr) {
319 OPENSSL_PUT_ERROR(SSL, ERR_R_MALLOC_FAILURE);
323 for (size_t i = 0; i < size_; i++) {
329 // CopyFrom replaces the array with a newly-allocated copy of |in|. It returns
330 // true on success and false on error.
331 bool CopyFrom(Span<const uint8_t> in) {
332 if (!Init(in.size())) {
335 OPENSSL_memcpy(data_, in.data(), in.size());
344 // CBBFinishArray behaves like |CBB_finish| but stores the result in an Array.
345 OPENSSL_EXPORT bool CBBFinishArray(CBB *cbb, Array<uint8_t> *out);
348 // Protocol versions.
350 // Due to DTLS's historical wire version differences and to support multiple
351 // variants of the same protocol during development, we maintain two notions of
354 // The "version" or "wire version" is the actual 16-bit value that appears on
355 // the wire. It uniquely identifies a version and is also used at API
356 // boundaries. The set of supported versions differs between TLS and DTLS. Wire
357 // versions are opaque values and may not be compared numerically.
359 // The "protocol version" identifies the high-level handshake variant being
360 // used. DTLS versions map to the corresponding TLS versions. Draft TLS 1.3
361 // variants all map to TLS 1.3. Protocol versions are sequential and may be
362 // compared numerically.
364 // ssl_protocol_version_from_wire sets |*out| to the protocol version
365 // corresponding to wire version |version| and returns true. If |version| is not
366 // a valid TLS or DTLS version, it returns false.
368 // Note this simultaneously handles both DTLS and TLS. Use one of the
369 // higher-level functions below for most operations.
370 bool ssl_protocol_version_from_wire(uint16_t *out, uint16_t version);
372 // ssl_get_version_range sets |*out_min_version| and |*out_max_version| to the
373 // minimum and maximum enabled protocol versions, respectively.
374 bool ssl_get_version_range(const SSL *ssl, uint16_t *out_min_version,
375 uint16_t *out_max_version);
377 // ssl_supports_version returns whether |hs| supports |version|.
378 bool ssl_supports_version(SSL_HANDSHAKE *hs, uint16_t version);
380 // ssl_add_supported_versions writes the supported versions of |hs| to |cbb|, in
381 // decreasing preference order.
382 bool ssl_add_supported_versions(SSL_HANDSHAKE *hs, CBB *cbb);
384 // ssl_negotiate_version negotiates a common version based on |hs|'s preferences
385 // and the peer preference list in |peer_versions|. On success, it returns true
386 // and sets |*out_version| to the selected version. Otherwise, it returns false
387 // and sets |*out_alert| to an alert to send.
388 bool ssl_negotiate_version(SSL_HANDSHAKE *hs, uint8_t *out_alert,
389 uint16_t *out_version, const CBS *peer_versions);
391 // ssl_protocol_version returns |ssl|'s protocol version. It is an error to
392 // call this function before the version is determined.
393 uint16_t ssl_protocol_version(const SSL *ssl);
399 struct ssl_cipher_st {
400 // name is the OpenSSL name for the cipher.
402 // standard_name is the IETF name for the cipher.
403 const char *standard_name;
404 // id is the cipher suite value bitwise OR-d with 0x03000000.
407 // algorithm_* determine the cipher suite. See constants below for the values.
408 uint32_t algorithm_mkey;
409 uint32_t algorithm_auth;
410 uint32_t algorithm_enc;
411 uint32_t algorithm_mac;
412 uint32_t algorithm_prf;
417 // Bits for |algorithm_mkey| (key exchange algorithm).
418 #define SSL_kRSA 0x00000001u
419 #define SSL_kECDHE 0x00000002u
420 // SSL_kPSK is only set for plain PSK, not ECDHE_PSK.
421 #define SSL_kPSK 0x00000004u
422 #define SSL_kGENERIC 0x00000008u
424 // Bits for |algorithm_auth| (server authentication).
425 #define SSL_aRSA 0x00000001u
426 #define SSL_aECDSA 0x00000002u
427 // SSL_aPSK is set for both PSK and ECDHE_PSK.
428 #define SSL_aPSK 0x00000004u
429 #define SSL_aGENERIC 0x00000008u
431 #define SSL_aCERT (SSL_aRSA | SSL_aECDSA)
433 // Bits for |algorithm_enc| (symmetric encryption).
434 #define SSL_3DES 0x00000001u
435 #define SSL_AES128 0x00000002u
436 #define SSL_AES256 0x00000004u
437 #define SSL_AES128GCM 0x00000008u
438 #define SSL_AES256GCM 0x00000010u
439 #define SSL_eNULL 0x00000020u
440 #define SSL_CHACHA20POLY1305 0x00000040u
442 #define SSL_AES (SSL_AES128 | SSL_AES256 | SSL_AES128GCM | SSL_AES256GCM)
444 // Bits for |algorithm_mac| (symmetric authentication).
445 #define SSL_SHA1 0x00000001u
446 #define SSL_SHA256 0x00000002u
447 #define SSL_SHA384 0x00000004u
448 // SSL_AEAD is set for all AEADs.
449 #define SSL_AEAD 0x00000008u
451 // Bits for |algorithm_prf| (handshake digest).
452 #define SSL_HANDSHAKE_MAC_DEFAULT 0x1
453 #define SSL_HANDSHAKE_MAC_SHA256 0x2
454 #define SSL_HANDSHAKE_MAC_SHA384 0x4
456 // SSL_MAX_DIGEST is the number of digest types which exist. When adding a new
457 // one, update the table in ssl_cipher.c.
458 #define SSL_MAX_DIGEST 4
460 // ssl_cipher_get_evp_aead sets |*out_aead| to point to the correct EVP_AEAD
461 // object for |cipher| protocol version |version|. It sets |*out_mac_secret_len|
462 // and |*out_fixed_iv_len| to the MAC key length and fixed IV length,
463 // respectively. The MAC key length is zero except for legacy block and stream
464 // ciphers. It returns true on success and false on error.
465 bool ssl_cipher_get_evp_aead(const EVP_AEAD **out_aead,
466 size_t *out_mac_secret_len,
467 size_t *out_fixed_iv_len, const SSL_CIPHER *cipher,
468 uint16_t version, int is_dtls);
470 // ssl_get_handshake_digest returns the |EVP_MD| corresponding to |version| and
472 const EVP_MD *ssl_get_handshake_digest(uint16_t version,
473 const SSL_CIPHER *cipher);
475 // ssl_create_cipher_list evaluates |rule_str|. It sets |*out_cipher_list| to a
476 // newly-allocated |ssl_cipher_preference_list_st| containing the result. It
477 // returns true on success and false on failure. If |strict| is true, nonsense
478 // will be rejected. If false, nonsense will be silently ignored. An empty
479 // result is considered an error regardless of |strict|.
480 bool ssl_create_cipher_list(
481 struct ssl_cipher_preference_list_st **out_cipher_list,
482 const char *rule_str, bool strict);
484 // ssl_cipher_get_value returns the cipher suite id of |cipher|.
485 uint16_t ssl_cipher_get_value(const SSL_CIPHER *cipher);
487 // ssl_cipher_auth_mask_for_key returns the mask of cipher |algorithm_auth|
488 // values suitable for use with |key| in TLS 1.2 and below.
489 uint32_t ssl_cipher_auth_mask_for_key(const EVP_PKEY *key);
491 // ssl_cipher_uses_certificate_auth returns whether |cipher| authenticates the
492 // server and, optionally, the client with a certificate.
493 bool ssl_cipher_uses_certificate_auth(const SSL_CIPHER *cipher);
495 // ssl_cipher_requires_server_key_exchange returns whether |cipher| requires a
496 // ServerKeyExchange message.
498 // This function may return false while still allowing |cipher| an optional
499 // ServerKeyExchange. This is the case for plain PSK ciphers.
500 bool ssl_cipher_requires_server_key_exchange(const SSL_CIPHER *cipher);
502 // ssl_cipher_get_record_split_len, for TLS 1.0 CBC mode ciphers, returns the
503 // length of an encrypted 1-byte record, for use in record-splitting. Otherwise
505 size_t ssl_cipher_get_record_split_len(const SSL_CIPHER *cipher);
510 // SSLTranscript maintains the handshake transcript as a combination of a
511 // buffer and running hash.
512 class SSLTranscript {
517 // Init initializes the handshake transcript. If called on an existing
518 // transcript, it resets the transcript and hash. It returns true on success
519 // and false on failure.
522 // InitHash initializes the handshake hash based on the PRF and contents of
523 // the handshake transcript. Subsequent calls to |Update| will update the
524 // rolling hash. It returns one on success and zero on failure. It is an error
525 // to call this function after the handshake buffer is released.
526 bool InitHash(uint16_t version, const SSL_CIPHER *cipher);
528 // UpdateForHelloRetryRequest resets the rolling hash with the
529 // HelloRetryRequest construction. It returns true on success and false on
530 // failure. It is an error to call this function before the handshake buffer
532 bool UpdateForHelloRetryRequest();
534 // CopyHashContext copies the hash context into |ctx| and returns true on
536 bool CopyHashContext(EVP_MD_CTX *ctx);
538 Span<const uint8_t> buffer() {
539 return MakeConstSpan(reinterpret_cast<const uint8_t *>(buffer_->data),
543 // FreeBuffer releases the handshake buffer. Subsequent calls to
544 // |Update| will not update the handshake buffer.
547 // DigestLen returns the length of the PRF hash.
548 size_t DigestLen() const;
550 // Digest returns the PRF hash. For TLS 1.1 and below, this is
552 const EVP_MD *Digest() const;
554 // Update adds |in| to the handshake buffer and handshake hash, whichever is
555 // enabled. It returns true on success and false on failure.
556 bool Update(Span<const uint8_t> in);
558 // GetHash writes the handshake hash to |out| which must have room for at
559 // least |DigestLen| bytes. On success, it returns true and sets |*out_len| to
560 // the number of bytes written. Otherwise, it returns false.
561 bool GetHash(uint8_t *out, size_t *out_len);
563 // GetSSL3CertVerifyHash writes the SSL 3.0 CertificateVerify hash into the
564 // bytes pointed to by |out| and writes the number of bytes to
565 // |*out_len|. |out| must have room for |EVP_MAX_MD_SIZE| bytes. It returns
566 // one on success and zero on failure.
567 bool GetSSL3CertVerifyHash(uint8_t *out, size_t *out_len,
568 const SSL_SESSION *session,
569 uint16_t signature_algorithm);
571 // GetFinishedMAC computes the MAC for the Finished message into the bytes
572 // pointed by |out| and writes the number of bytes to |*out_len|. |out| must
573 // have room for |EVP_MAX_MD_SIZE| bytes. It returns true on success and false
575 bool GetFinishedMAC(uint8_t *out, size_t *out_len, const SSL_SESSION *session,
579 // buffer_, if non-null, contains the handshake transcript.
580 UniquePtr<BUF_MEM> buffer_;
581 // hash, if initialized with an |EVP_MD|, maintains the handshake hash. For
582 // TLS 1.1 and below, it is the SHA-1 half.
583 ScopedEVP_MD_CTX hash_;
584 // md5, if initialized with an |EVP_MD|, maintains the MD5 half of the
585 // handshake hash for TLS 1.1 and below.
586 ScopedEVP_MD_CTX md5_;
589 // tls1_prf computes the PRF function for |ssl|. It fills |out|, using |secret|
590 // as the secret and |label| as the label. |seed1| and |seed2| are concatenated
591 // to form the seed parameter. It returns true on success and false on failure.
592 bool tls1_prf(const EVP_MD *digest, Span<uint8_t> out,
593 Span<const uint8_t> secret, Span<const char> label,
594 Span<const uint8_t> seed1, Span<const uint8_t> seed2);
599 // SSLAEADContext contains information about an AEAD that is being used to
600 // encrypt an SSL connection.
601 class SSLAEADContext {
603 SSLAEADContext(uint16_t version, bool is_dtls, const SSL_CIPHER *cipher);
605 static constexpr bool kAllowUniquePtr = true;
607 SSLAEADContext(const SSLAEADContext &&) = delete;
608 SSLAEADContext &operator=(const SSLAEADContext &&) = delete;
610 // CreateNullCipher creates an |SSLAEADContext| for the null cipher.
611 static UniquePtr<SSLAEADContext> CreateNullCipher(bool is_dtls);
613 // Create creates an |SSLAEADContext| using the supplied key material. It
614 // returns nullptr on error. Only one of |Open| or |Seal| may be used with the
615 // resulting object, depending on |direction|. |version| is the normalized
616 // protocol version, so DTLS 1.0 is represented as 0x0301, not 0xffef.
617 static UniquePtr<SSLAEADContext> Create(enum evp_aead_direction_t direction,
618 uint16_t version, int is_dtls,
619 const SSL_CIPHER *cipher,
620 Span<const uint8_t> enc_key,
621 Span<const uint8_t> mac_key,
622 Span<const uint8_t> fixed_iv);
624 // SetVersionIfNullCipher sets the version the SSLAEADContext for the null
625 // cipher, to make version-specific determinations in the record layer prior
626 // to a cipher being selected.
627 void SetVersionIfNullCipher(uint16_t version);
629 // ProtocolVersion returns the protocol version associated with this
630 // SSLAEADContext. It can only be called once |version_| has been set to a
632 uint16_t ProtocolVersion() const;
634 // RecordVersion returns the record version that should be used with this
635 // SSLAEADContext for record construction and crypto.
636 uint16_t RecordVersion() const;
638 const SSL_CIPHER *cipher() const { return cipher_; }
640 // is_null_cipher returns true if this is the null cipher.
641 bool is_null_cipher() const { return !cipher_; }
643 // ExplicitNonceLen returns the length of the explicit nonce.
644 size_t ExplicitNonceLen() const;
646 // MaxOverhead returns the maximum overhead of calling |Seal|.
647 size_t MaxOverhead() const;
649 // SuffixLen calculates the suffix length written by |SealScatter| and writes
650 // it to |*out_suffix_len|. It returns true on success and false on error.
651 // |in_len| and |extra_in_len| should equal the argument of the same names
652 // passed to |SealScatter|.
653 bool SuffixLen(size_t *out_suffix_len, size_t in_len,
654 size_t extra_in_len) const;
656 // Open authenticates and decrypts |in| in-place. On success, it sets |*out|
657 // to the plaintext in |in| and returns true. Otherwise, it returns
658 // false. The output will always be |ExplicitNonceLen| bytes ahead of |in|.
659 bool Open(Span<uint8_t> *out, uint8_t type, uint16_t record_version,
660 const uint8_t seqnum[8], Span<uint8_t> in);
662 // Seal encrypts and authenticates |in_len| bytes from |in| and writes the
663 // result to |out|. It returns true on success and false on error.
665 // If |in| and |out| alias then |out| + |ExplicitNonceLen| must be == |in|.
666 bool Seal(uint8_t *out, size_t *out_len, size_t max_out, uint8_t type,
667 uint16_t record_version, const uint8_t seqnum[8], const uint8_t *in,
670 // SealScatter encrypts and authenticates |in_len| bytes from |in| and splits
671 // the result between |out_prefix|, |out| and |out_suffix|. It returns one on
672 // success and zero on error.
674 // On successful return, exactly |ExplicitNonceLen| bytes are written to
675 // |out_prefix|, |in_len| bytes to |out|, and |SuffixLen| bytes to
678 // |extra_in| may point to an additional plaintext buffer. If present,
679 // |extra_in_len| additional bytes are encrypted and authenticated, and the
680 // ciphertext is written to the beginning of |out_suffix|. |SuffixLen| should
681 // be used to size |out_suffix| accordingly.
683 // If |in| and |out| alias then |out| must be == |in|. Other arguments may not
685 bool SealScatter(uint8_t *out_prefix, uint8_t *out, uint8_t *out_suffix,
686 uint8_t type, uint16_t record_version,
687 const uint8_t seqnum[8], const uint8_t *in, size_t in_len,
688 const uint8_t *extra_in, size_t extra_in_len);
690 bool GetIV(const uint8_t **out_iv, size_t *out_iv_len) const;
693 // GetAdditionalData writes the additional data into |out| and returns the
694 // number of bytes written.
695 size_t GetAdditionalData(uint8_t out[13], uint8_t type,
696 uint16_t record_version, const uint8_t seqnum[8],
697 size_t plaintext_len);
699 const SSL_CIPHER *cipher_;
700 ScopedEVP_AEAD_CTX ctx_;
701 // fixed_nonce_ contains any bytes of the nonce that are fixed for all
703 uint8_t fixed_nonce_[12];
704 uint8_t fixed_nonce_len_ = 0, variable_nonce_len_ = 0;
705 // version_ is the wire version that should be used with this AEAD.
707 // is_dtls_ is whether DTLS is being used with this AEAD.
709 // variable_nonce_included_in_record_ is true if the variable nonce
710 // for a record is included as a prefix before the ciphertext.
711 bool variable_nonce_included_in_record_ : 1;
712 // random_variable_nonce_ is true if the variable nonce is
713 // randomly generated, rather than derived from the sequence
715 bool random_variable_nonce_ : 1;
716 // omit_length_in_ad_ is true if the length should be omitted in the
717 // AEAD's ad parameter.
718 bool omit_length_in_ad_ : 1;
719 // omit_version_in_ad_ is true if the version should be omitted
720 // in the AEAD's ad parameter.
721 bool omit_version_in_ad_ : 1;
722 // omit_ad_ is true if the AEAD's ad parameter should be omitted.
724 // xor_fixed_nonce_ is true if the fixed nonce should be XOR'd into the
725 // variable nonce rather than prepended.
726 bool xor_fixed_nonce_ : 1;
730 // DTLS replay bitmap.
732 // DTLS1_BITMAP maintains a sliding window of 64 sequence numbers to detect
733 // replayed packets. It should be initialized by zeroing every field.
734 struct DTLS1_BITMAP {
735 // map is a bit mask of the last 64 sequence numbers. Bit
736 // |1<<i| corresponds to |max_seq_num - i|.
738 // max_seq_num is the largest sequence number seen so far as a 64-bit
740 uint64_t max_seq_num = 0;
746 // ssl_record_sequence_update increments the sequence number in |seq|. It
747 // returns one on success and zero on wraparound.
748 int ssl_record_sequence_update(uint8_t *seq, size_t seq_len);
750 // ssl_record_prefix_len returns the length of the prefix before the ciphertext
751 // of a record for |ssl|.
753 // TODO(davidben): Expose this as part of public API once the high-level
754 // buffer-free APIs are available.
755 size_t ssl_record_prefix_len(const SSL *ssl);
757 enum ssl_open_record_t {
758 ssl_open_record_success,
759 ssl_open_record_discard,
760 ssl_open_record_partial,
761 ssl_open_record_close_notify,
762 ssl_open_record_error,
765 // tls_open_record decrypts a record from |in| in-place.
767 // If the input did not contain a complete record, it returns
768 // |ssl_open_record_partial|. It sets |*out_consumed| to the total number of
769 // bytes necessary. It is guaranteed that a successful call to |tls_open_record|
770 // will consume at least that many bytes.
772 // Otherwise, it sets |*out_consumed| to the number of bytes of input
773 // consumed. Note that input may be consumed on all return codes if a record was
776 // On success, it returns |ssl_open_record_success|. It sets |*out_type| to the
777 // record type and |*out| to the record body in |in|. Note that |*out| may be
780 // If a record was successfully processed but should be discarded, it returns
781 // |ssl_open_record_discard|.
783 // If a record was successfully processed but is a close_notify, it returns
784 // |ssl_open_record_close_notify|.
786 // On failure or fatal alert, it returns |ssl_open_record_error| and sets
787 // |*out_alert| to an alert to emit, or zero if no alert should be emitted.
788 enum ssl_open_record_t tls_open_record(SSL *ssl, uint8_t *out_type,
789 Span<uint8_t> *out, size_t *out_consumed,
790 uint8_t *out_alert, Span<uint8_t> in);
792 // dtls_open_record implements |tls_open_record| for DTLS. It only returns
793 // |ssl_open_record_partial| if |in| was empty and sets |*out_consumed| to
794 // zero. The caller should read one packet and try again.
795 enum ssl_open_record_t dtls_open_record(SSL *ssl, uint8_t *out_type,
797 size_t *out_consumed,
798 uint8_t *out_alert, Span<uint8_t> in);
800 // ssl_seal_align_prefix_len returns the length of the prefix before the start
801 // of the bulk of the ciphertext when sealing a record with |ssl|. Callers may
802 // use this to align buffers.
804 // Note when TLS 1.0 CBC record-splitting is enabled, this includes the one byte
805 // record and is the offset into second record's ciphertext. Thus sealing a
806 // small record may result in a smaller output than this value.
808 // TODO(davidben): Is this alignment valuable? Record-splitting makes this a
810 size_t ssl_seal_align_prefix_len(const SSL *ssl);
812 // tls_seal_record seals a new record of type |type| and body |in| and writes it
813 // to |out|. At most |max_out| bytes will be written. It returns one on success
814 // and zero on error. If enabled, |tls_seal_record| implements TLS 1.0 CBC 1/n-1
815 // record splitting and may write two records concatenated.
817 // For a large record, the bulk of the ciphertext will begin
818 // |ssl_seal_align_prefix_len| bytes into out. Aligning |out| appropriately may
819 // improve performance. It writes at most |in_len| + |SSL_max_seal_overhead|
822 // |in| and |out| may not alias.
823 int tls_seal_record(SSL *ssl, uint8_t *out, size_t *out_len, size_t max_out,
824 uint8_t type, const uint8_t *in, size_t in_len);
826 enum dtls1_use_epoch_t {
827 dtls1_use_previous_epoch,
828 dtls1_use_current_epoch,
831 // dtls_max_seal_overhead returns the maximum overhead, in bytes, of sealing a
833 size_t dtls_max_seal_overhead(const SSL *ssl, enum dtls1_use_epoch_t use_epoch);
835 // dtls_seal_prefix_len returns the number of bytes of prefix to reserve in
836 // front of the plaintext when sealing a record in-place.
837 size_t dtls_seal_prefix_len(const SSL *ssl, enum dtls1_use_epoch_t use_epoch);
839 // dtls_seal_record implements |tls_seal_record| for DTLS. |use_epoch| selects
840 // which epoch's cipher state to use. Unlike |tls_seal_record|, |in| and |out|
841 // may alias but, if they do, |in| must be exactly |dtls_seal_prefix_len| bytes
843 int dtls_seal_record(SSL *ssl, uint8_t *out, size_t *out_len, size_t max_out,
844 uint8_t type, const uint8_t *in, size_t in_len,
845 enum dtls1_use_epoch_t use_epoch);
847 // ssl_process_alert processes |in| as an alert and updates |ssl|'s shutdown
848 // state. It returns one of |ssl_open_record_discard|, |ssl_open_record_error|,
849 // |ssl_open_record_close_notify|, or |ssl_open_record_fatal_alert| as
851 enum ssl_open_record_t ssl_process_alert(SSL *ssl, uint8_t *out_alert,
852 Span<const uint8_t> in);
855 // Private key operations.
857 // ssl_has_private_key returns one if |ssl| has a private key
858 // configured and zero otherwise.
859 int ssl_has_private_key(const SSL *ssl);
861 // ssl_private_key_* perform the corresponding operation on
862 // |SSL_PRIVATE_KEY_METHOD|. If there is a custom private key configured, they
863 // call the corresponding function or |complete| depending on whether there is a
864 // pending operation. Otherwise, they implement the operation with
867 enum ssl_private_key_result_t ssl_private_key_sign(
868 SSL_HANDSHAKE *hs, uint8_t *out, size_t *out_len, size_t max_out,
869 uint16_t sigalg, Span<const uint8_t> in);
871 enum ssl_private_key_result_t ssl_private_key_decrypt(SSL_HANDSHAKE *hs,
875 Span<const uint8_t> in);
877 // ssl_private_key_supports_signature_algorithm returns whether |hs|'s private
878 // key supports |sigalg|.
879 bool ssl_private_key_supports_signature_algorithm(SSL_HANDSHAKE *hs,
882 // ssl_public_key_verify verifies that the |signature| is valid for the public
883 // key |pkey| and input |in|, using the signature algorithm |sigalg|.
884 bool ssl_public_key_verify(SSL *ssl, Span<const uint8_t> signature,
885 uint16_t sigalg, EVP_PKEY *pkey,
886 Span<const uint8_t> in);
893 // |SSL_CUSTOM_EXTENSION| is a structure that contains information about
894 // custom-extension callbacks. It is defined unnamespaced for compatibility with
895 // |STACK_OF(SSL_CUSTOM_EXTENSION)|.
896 typedef struct ssl_custom_extension {
897 SSL_custom_ext_add_cb add_callback;
899 SSL_custom_ext_free_cb free_callback;
900 SSL_custom_ext_parse_cb parse_callback;
903 } SSL_CUSTOM_EXTENSION;
905 DEFINE_STACK_OF(SSL_CUSTOM_EXTENSION)
909 void SSL_CUSTOM_EXTENSION_free(SSL_CUSTOM_EXTENSION *custom_extension);
911 int custom_ext_add_clienthello(SSL_HANDSHAKE *hs, CBB *extensions);
912 int custom_ext_parse_serverhello(SSL_HANDSHAKE *hs, int *out_alert,
913 uint16_t value, const CBS *extension);
914 int custom_ext_parse_clienthello(SSL_HANDSHAKE *hs, int *out_alert,
915 uint16_t value, const CBS *extension);
916 int custom_ext_add_serverhello(SSL_HANDSHAKE *hs, CBB *extensions);
921 // SSLKeyShare abstracts over Diffie-Hellman-like key exchanges.
924 virtual ~SSLKeyShare() {}
925 static constexpr bool kAllowUniquePtr = true;
926 HAS_VIRTUAL_DESTRUCTOR
928 // Create returns a SSLKeyShare instance for use with group |group_id| or
930 static UniquePtr<SSLKeyShare> Create(uint16_t group_id);
932 // GroupID returns the group ID.
933 virtual uint16_t GroupID() const PURE_VIRTUAL;
935 // Offer generates a keypair and writes the public value to
936 // |out_public_key|. It returns true on success and false on error.
937 virtual bool Offer(CBB *out_public_key) PURE_VIRTUAL;
939 // Accept performs a key exchange against the |peer_key| generated by |offer|.
940 // On success, it returns true, writes the public value to |out_public_key|,
941 // and sets |*out_secret| the shared secret. On failure, it returns false and
942 // sets |*out_alert| to an alert to send to the peer.
944 // The default implementation calls |Offer| and then |Finish|, assuming a key
945 // exchange protocol where the peers are symmetric.
946 virtual bool Accept(CBB *out_public_key, Array<uint8_t> *out_secret,
947 uint8_t *out_alert, Span<const uint8_t> peer_key);
949 // Finish performs a key exchange against the |peer_key| generated by
950 // |Accept|. On success, it returns true and sets |*out_secret| to the shared
951 // secret. On failure, it returns zero and sets |*out_alert| to an alert to
953 virtual bool Finish(Array<uint8_t> *out_secret, uint8_t *out_alert,
954 Span<const uint8_t> peer_key) PURE_VIRTUAL;
957 // ssl_nid_to_group_id looks up the group corresponding to |nid|. On success, it
958 // sets |*out_group_id| to the group ID and returns one. Otherwise, it returns
960 int ssl_nid_to_group_id(uint16_t *out_group_id, int nid);
962 // ssl_name_to_group_id looks up the group corresponding to the |name| string
963 // of length |len|. On success, it sets |*out_group_id| to the group ID and
964 // returns one. Otherwise, it returns zero.
965 int ssl_name_to_group_id(uint16_t *out_group_id, const char *name, size_t len);
968 // Handshake messages.
974 // raw is the entire serialized handshake message, including the TLS or DTLS
979 // SSL_MAX_HANDSHAKE_FLIGHT is the number of messages, including
980 // ChangeCipherSpec, in the longest handshake flight. Currently this is the
981 // client's second leg in a full handshake when client certificates, NPN, and
982 // Channel ID, are all enabled.
983 #define SSL_MAX_HANDSHAKE_FLIGHT 7
985 extern const uint8_t kHelloRetryRequest[SSL3_RANDOM_SIZE];
986 extern const uint8_t kDraftDowngradeRandom[8];
988 // ssl_max_handshake_message_len returns the maximum number of bytes permitted
989 // in a handshake message for |ssl|.
990 size_t ssl_max_handshake_message_len(const SSL *ssl);
992 // tls_can_accept_handshake_data returns whether |ssl| is able to accept more
993 // data into handshake buffer.
994 bool tls_can_accept_handshake_data(const SSL *ssl, uint8_t *out_alert);
996 // tls_has_unprocessed_handshake_data returns whether there is buffered
997 // handshake data that has not been consumed by |get_message|.
998 bool tls_has_unprocessed_handshake_data(const SSL *ssl);
1000 // dtls_has_unprocessed_handshake_data behaves like
1001 // |tls_has_unprocessed_handshake_data| for DTLS.
1002 bool dtls_has_unprocessed_handshake_data(const SSL *ssl);
1004 struct DTLS_OUTGOING_MESSAGE {
1005 DTLS_OUTGOING_MESSAGE() {}
1006 DTLS_OUTGOING_MESSAGE(const DTLS_OUTGOING_MESSAGE &) = delete;
1007 DTLS_OUTGOING_MESSAGE &operator=(const DTLS_OUTGOING_MESSAGE &) = delete;
1008 ~DTLS_OUTGOING_MESSAGE() { Clear(); }
1012 uint8_t *data = nullptr;
1015 bool is_ccs = false;
1018 // dtls_clear_outgoing_messages releases all buffered outgoing messages.
1019 void dtls_clear_outgoing_messages(SSL *ssl);
1024 // ssl_do_info_callback calls |ssl|'s info callback, if set.
1025 void ssl_do_info_callback(const SSL *ssl, int type, int value);
1027 // ssl_do_msg_callback calls |ssl|'s message callback, if set.
1028 void ssl_do_msg_callback(SSL *ssl, int is_write, int content_type,
1029 Span<const uint8_t> in);
1032 // Transport buffers.
1037 ~SSLBuffer() { Clear(); }
1039 SSLBuffer(const SSLBuffer &) = delete;
1040 SSLBuffer &operator=(const SSLBuffer &) = delete;
1042 uint8_t *data() { return buf_ + offset_; }
1043 size_t size() const { return size_; }
1044 bool empty() const { return size_ == 0; }
1045 size_t cap() const { return cap_; }
1047 Span<uint8_t> span() { return MakeSpan(data(), size()); }
1049 Span<uint8_t> remaining() {
1050 return MakeSpan(data() + size(), cap() - size());
1053 // Clear releases the buffer.
1056 // EnsureCap ensures the buffer has capacity at least |new_cap|, aligned such
1057 // that data written after |header_len| is aligned to a
1058 // |SSL3_ALIGN_PAYLOAD|-byte boundary. It returns true on success and false
1060 bool EnsureCap(size_t header_len, size_t new_cap);
1062 // DidWrite extends the buffer by |len|. The caller must have filled in to
1064 void DidWrite(size_t len);
1066 // Consume consumes |len| bytes from the front of the buffer. The memory
1067 // consumed will remain valid until the next call to |DiscardConsumed| or
1069 void Consume(size_t len);
1071 // DiscardConsumed discards the consumed bytes from the buffer. If the buffer
1072 // is now empty, it releases memory used by it.
1073 void DiscardConsumed();
1076 // buf_ is the memory allocated for this buffer.
1077 uint8_t *buf_ = nullptr;
1078 // offset_ is the offset into |buf_| which the buffer contents start at.
1079 uint16_t offset_ = 0;
1080 // size_ is the size of the buffer contents from |buf_| + |offset_|.
1082 // cap_ is how much memory beyond |buf_| + |offset_| is available.
1086 // ssl_read_buffer_extend_to extends the read buffer to the desired length. For
1087 // TLS, it reads to the end of the buffer until the buffer is |len| bytes
1088 // long. For DTLS, it reads a new packet and ignores |len|. It returns one on
1089 // success, zero on EOF, and a negative number on error.
1091 // It is an error to call |ssl_read_buffer_extend_to| in DTLS when the buffer is
1093 int ssl_read_buffer_extend_to(SSL *ssl, size_t len);
1095 // ssl_handle_open_record handles the result of passing |ssl->s3->read_buffer|
1096 // to a record-processing function. If |ret| is a success or if the caller
1097 // should retry, it returns one and sets |*out_retry|. Otherwise, it returns <=
1099 int ssl_handle_open_record(SSL *ssl, bool *out_retry, ssl_open_record_t ret,
1100 size_t consumed, uint8_t alert);
1102 // ssl_write_buffer_flush flushes the write buffer to the transport. It returns
1103 // one on success and <= 0 on error. For DTLS, whether or not the write
1104 // succeeds, the write buffer will be cleared.
1105 int ssl_write_buffer_flush(SSL *ssl);
1108 // Certificate functions.
1110 // ssl_has_certificate returns one if a certificate and private key are
1111 // configured and zero otherwise.
1112 int ssl_has_certificate(const SSL *ssl);
1114 // ssl_parse_cert_chain parses a certificate list from |cbs| in the format used
1115 // by a TLS Certificate message. On success, it advances |cbs| and returns
1116 // true. Otherwise, it returns false and sets |*out_alert| to an alert to send
1119 // If the list is non-empty then |*out_chain| and |*out_pubkey| will be set to
1120 // the certificate chain and the leaf certificate's public key
1121 // respectively. Otherwise, both will be set to nullptr.
1123 // If the list is non-empty and |out_leaf_sha256| is non-NULL, it writes the
1124 // SHA-256 hash of the leaf to |out_leaf_sha256|.
1125 bool ssl_parse_cert_chain(uint8_t *out_alert,
1126 UniquePtr<STACK_OF(CRYPTO_BUFFER)> *out_chain,
1127 UniquePtr<EVP_PKEY> *out_pubkey,
1128 uint8_t *out_leaf_sha256, CBS *cbs,
1129 CRYPTO_BUFFER_POOL *pool);
1131 // ssl_add_cert_chain adds |ssl|'s certificate chain to |cbb| in the format used
1132 // by a TLS Certificate message. If there is no certificate chain, it emits an
1133 // empty certificate list. It returns one on success and zero on error.
1134 int ssl_add_cert_chain(SSL *ssl, CBB *cbb);
1136 // ssl_cert_check_digital_signature_key_usage parses the DER-encoded, X.509
1137 // certificate in |in| and returns one if doesn't specify a key usage or, if it
1138 // does, if it includes digitalSignature. Otherwise it pushes to the error
1139 // queue and returns zero.
1140 int ssl_cert_check_digital_signature_key_usage(const CBS *in);
1142 // ssl_cert_parse_pubkey extracts the public key from the DER-encoded, X.509
1143 // certificate in |in|. It returns an allocated |EVP_PKEY| or else returns
1144 // nullptr and pushes to the error queue.
1145 UniquePtr<EVP_PKEY> ssl_cert_parse_pubkey(const CBS *in);
1147 // ssl_parse_client_CA_list parses a CA list from |cbs| in the format used by a
1148 // TLS CertificateRequest message. On success, it returns a newly-allocated
1149 // |CRYPTO_BUFFER| list and advances |cbs|. Otherwise, it returns nullptr and
1150 // sets |*out_alert| to an alert to send to the peer.
1151 UniquePtr<STACK_OF(CRYPTO_BUFFER)> ssl_parse_client_CA_list(SSL *ssl,
1155 // ssl_has_client_CAs returns there are configured CAs.
1156 bool ssl_has_client_CAs(SSL *ssl);
1158 // ssl_add_client_CA_list adds the configured CA list to |cbb| in the format
1159 // used by a TLS CertificateRequest message. It returns one on success and zero
1161 int ssl_add_client_CA_list(SSL *ssl, CBB *cbb);
1163 // ssl_check_leaf_certificate returns one if |pkey| and |leaf| are suitable as
1164 // a server's leaf certificate for |hs|. Otherwise, it returns zero and pushes
1165 // an error on the error queue.
1166 int ssl_check_leaf_certificate(SSL_HANDSHAKE *hs, EVP_PKEY *pkey,
1167 const CRYPTO_BUFFER *leaf);
1169 // ssl_on_certificate_selected is called once the certificate has been selected.
1170 // It finalizes the certificate and initializes |hs->local_pubkey|. It returns
1171 // one on success and zero on error.
1172 int ssl_on_certificate_selected(SSL_HANDSHAKE *hs);
1175 // TLS 1.3 key derivation.
1177 // tls13_init_key_schedule initializes the handshake hash and key derivation
1178 // state, and incorporates the PSK. The cipher suite and PRF hash must have been
1179 // selected at this point. It returns one on success and zero on error.
1180 int tls13_init_key_schedule(SSL_HANDSHAKE *hs, const uint8_t *psk,
1183 // tls13_init_early_key_schedule initializes the handshake hash and key
1184 // derivation state from the resumption secret and incorporates the PSK to
1185 // derive the early secrets. It returns one on success and zero on error.
1186 int tls13_init_early_key_schedule(SSL_HANDSHAKE *hs, const uint8_t *psk,
1189 // tls13_advance_key_schedule incorporates |in| into the key schedule with
1190 // HKDF-Extract. It returns one on success and zero on error.
1191 int tls13_advance_key_schedule(SSL_HANDSHAKE *hs, const uint8_t *in,
1194 // tls13_set_traffic_key sets the read or write traffic keys to
1195 // |traffic_secret|. It returns one on success and zero on error.
1196 int tls13_set_traffic_key(SSL *ssl, enum evp_aead_direction_t direction,
1197 const uint8_t *traffic_secret,
1198 size_t traffic_secret_len);
1200 // tls13_derive_early_secrets derives the early traffic secret. It returns one
1201 // on success and zero on error.
1202 int tls13_derive_early_secrets(SSL_HANDSHAKE *hs);
1204 // tls13_derive_handshake_secrets derives the handshake traffic secret. It
1205 // returns one on success and zero on error.
1206 int tls13_derive_handshake_secrets(SSL_HANDSHAKE *hs);
1208 // tls13_rotate_traffic_key derives the next read or write traffic secret. It
1209 // returns one on success and zero on error.
1210 int tls13_rotate_traffic_key(SSL *ssl, enum evp_aead_direction_t direction);
1212 // tls13_derive_application_secrets derives the initial application data traffic
1213 // and exporter secrets based on the handshake transcripts and |master_secret|.
1214 // It returns one on success and zero on error.
1215 int tls13_derive_application_secrets(SSL_HANDSHAKE *hs);
1217 // tls13_derive_resumption_secret derives the |resumption_secret|.
1218 int tls13_derive_resumption_secret(SSL_HANDSHAKE *hs);
1220 // tls13_export_keying_material provides an exporter interface to use the
1221 // |exporter_secret|.
1222 int tls13_export_keying_material(SSL *ssl, Span<uint8_t> out,
1223 Span<const uint8_t> secret,
1224 Span<const char> label,
1225 Span<const uint8_t> context);
1227 // tls13_finished_mac calculates the MAC of the handshake transcript to verify
1228 // the integrity of the Finished message, and stores the result in |out| and
1229 // length in |out_len|. |is_server| is 1 if this is for the Server Finished and
1230 // 0 for the Client Finished.
1231 int tls13_finished_mac(SSL_HANDSHAKE *hs, uint8_t *out,
1232 size_t *out_len, int is_server);
1234 // tls13_derive_session_psk calculates the PSK for this session based on the
1235 // resumption master secret and |nonce|. It returns true on success, and false
1237 bool tls13_derive_session_psk(SSL_SESSION *session, Span<const uint8_t> nonce);
1239 // tls13_write_psk_binder calculates the PSK binder value and replaces the last
1240 // bytes of |msg| with the resulting value. It returns 1 on success, and 0 on
1242 int tls13_write_psk_binder(SSL_HANDSHAKE *hs, uint8_t *msg, size_t len);
1244 // tls13_verify_psk_binder verifies that the handshake transcript, truncated
1245 // up to the binders has a valid signature using the value of |session|'s
1246 // resumption secret. It returns 1 on success, and 0 on failure.
1247 int tls13_verify_psk_binder(SSL_HANDSHAKE *hs, SSL_SESSION *session,
1248 const SSLMessage &msg, CBS *binders);
1251 // Handshake functions.
1253 enum ssl_hs_wait_t {
1256 ssl_hs_read_server_hello,
1257 ssl_hs_read_message,
1259 ssl_hs_certificate_selection_pending,
1262 ssl_hs_channel_id_lookup,
1263 ssl_hs_private_key_operation,
1264 ssl_hs_pending_session,
1265 ssl_hs_pending_ticket,
1266 ssl_hs_early_return,
1267 ssl_hs_early_data_rejected,
1268 ssl_hs_read_end_of_early_data,
1269 ssl_hs_read_change_cipher_spec,
1270 ssl_hs_certificate_verify,
1273 enum ssl_grease_index_t {
1274 ssl_grease_cipher = 0,
1276 ssl_grease_extension1,
1277 ssl_grease_extension2,
1279 ssl_grease_ticket_extension,
1280 ssl_grease_last_index = ssl_grease_ticket_extension,
1283 struct SSL_HANDSHAKE {
1284 explicit SSL_HANDSHAKE(SSL *ssl);
1286 static constexpr bool kAllowUniquePtr = true;
1288 // ssl is a non-owning pointer to the parent |SSL| object.
1291 // wait contains the operation the handshake is currently blocking on or
1292 // |ssl_hs_ok| if none.
1293 enum ssl_hs_wait_t wait = ssl_hs_ok;
1295 // state is the internal state for the TLS 1.2 and below handshake. Its
1296 // values depend on |do_handshake| but the starting state is always zero.
1299 // tls13_state is the internal state for the TLS 1.3 handshake. Its values
1300 // depend on |do_handshake| but the starting state is always zero.
1301 int tls13_state = 0;
1303 // min_version is the minimum accepted protocol version, taking account both
1304 // |SSL_OP_NO_*| and |SSL_CTX_set_min_proto_version| APIs.
1305 uint16_t min_version = 0;
1307 // max_version is the maximum accepted protocol version, taking account both
1308 // |SSL_OP_NO_*| and |SSL_CTX_set_max_proto_version| APIs.
1309 uint16_t max_version = 0;
1311 size_t hash_len = 0;
1312 uint8_t secret[EVP_MAX_MD_SIZE] = {0};
1313 uint8_t early_traffic_secret[EVP_MAX_MD_SIZE] = {0};
1314 uint8_t client_handshake_secret[EVP_MAX_MD_SIZE] = {0};
1315 uint8_t server_handshake_secret[EVP_MAX_MD_SIZE] = {0};
1316 uint8_t client_traffic_secret_0[EVP_MAX_MD_SIZE] = {0};
1317 uint8_t server_traffic_secret_0[EVP_MAX_MD_SIZE] = {0};
1318 uint8_t expected_client_finished[EVP_MAX_MD_SIZE] = {0};
1321 // sent is a bitset where the bits correspond to elements of kExtensions
1322 // in t1_lib.c. Each bit is set if that extension was sent in a
1323 // ClientHello. It's not used by servers.
1325 // received is a bitset, like |sent|, but is used by servers to record
1326 // which extensions were received from a client.
1331 // sent is a bitset where the bits correspond to elements of
1332 // |client_custom_extensions| in the |SSL_CTX|. Each bit is set if that
1333 // extension was sent in a ClientHello. It's not used by servers.
1335 // received is a bitset, like |sent|, but is used by servers to record
1336 // which custom extensions were received from a client. The bits here
1337 // correspond to |server_custom_extensions|.
1339 } custom_extensions;
1341 // retry_group is the group ID selected by the server in HelloRetryRequest in
1343 uint16_t retry_group = 0;
1345 // error, if |wait| is |ssl_hs_error|, is the error the handshake failed on.
1346 UniquePtr<ERR_SAVE_STATE> error;
1348 // key_share is the current key exchange instance.
1349 UniquePtr<SSLKeyShare> key_share;
1351 // transcript is the current handshake transcript.
1352 SSLTranscript transcript;
1354 // cookie is the value of the cookie received from the server, if any.
1355 Array<uint8_t> cookie;
1357 // key_share_bytes is the value of the previously sent KeyShare extension by
1358 // the client in TLS 1.3.
1359 Array<uint8_t> key_share_bytes;
1361 // ecdh_public_key, for servers, is the key share to be sent to the client in
1363 Array<uint8_t> ecdh_public_key;
1365 // peer_sigalgs are the signature algorithms that the peer supports. These are
1366 // taken from the contents of the signature algorithms extension for a server
1367 // or from the CertificateRequest for a client.
1368 Array<uint16_t> peer_sigalgs;
1370 // peer_supported_group_list contains the supported group IDs advertised by
1371 // the peer. This is only set on the server's end. The server does not
1372 // advertise this extension to the client.
1373 Array<uint16_t> peer_supported_group_list;
1375 // peer_key is the peer's ECDH key for a TLS 1.2 client.
1376 Array<uint8_t> peer_key;
1378 // negotiated_token_binding_version is used by a server to store the
1379 // on-the-wire encoding of the Token Binding protocol version to advertise in
1380 // the ServerHello/EncryptedExtensions if the Token Binding extension is to be
1382 uint16_t negotiated_token_binding_version;
1384 // server_params, in a TLS 1.2 server, stores the ServerKeyExchange
1385 // parameters. It has client and server randoms prepended for signing
1387 Array<uint8_t> server_params;
1389 // peer_psk_identity_hint, on the client, is the psk_identity_hint sent by the
1390 // server when using a TLS 1.2 PSK key exchange.
1391 UniquePtr<char> peer_psk_identity_hint;
1393 // ca_names, on the client, contains the list of CAs received in a
1394 // CertificateRequest message.
1395 UniquePtr<STACK_OF(CRYPTO_BUFFER)> ca_names;
1397 // cached_x509_ca_names contains a cache of parsed versions of the elements of
1398 // |ca_names|. This pointer is left non-owning so only
1399 // |ssl_crypto_x509_method| needs to link against crypto/x509.
1400 STACK_OF(X509_NAME) *cached_x509_ca_names = nullptr;
1402 // certificate_types, on the client, contains the set of certificate types
1403 // received in a CertificateRequest message.
1404 Array<uint8_t> certificate_types;
1406 // local_pubkey is the public key we are authenticating as.
1407 UniquePtr<EVP_PKEY> local_pubkey;
1409 // peer_pubkey is the public key parsed from the peer's leaf certificate.
1410 UniquePtr<EVP_PKEY> peer_pubkey;
1412 // new_session is the new mutable session being established by the current
1413 // handshake. It should not be cached.
1414 UniquePtr<SSL_SESSION> new_session;
1416 // early_session is the session corresponding to the current 0-RTT state on
1417 // the client if |in_early_data| is true.
1418 UniquePtr<SSL_SESSION> early_session;
1420 // new_cipher is the cipher being negotiated in this handshake.
1421 const SSL_CIPHER *new_cipher = nullptr;
1423 // key_block is the record-layer key block for TLS 1.2 and earlier.
1424 Array<uint8_t> key_block;
1426 // scts_requested is true if the SCT extension is in the ClientHello.
1427 bool scts_requested:1;
1429 // needs_psk_binder is true if the ClientHello has a placeholder PSK binder to
1431 bool needs_psk_binder:1;
1433 bool received_hello_retry_request:1;
1434 bool sent_hello_retry_request:1;
1436 bool received_custom_extension:1;
1438 // handshake_finalized is true once the handshake has completed, at which
1439 // point accessors should use the established state.
1440 bool handshake_finalized:1;
1442 // accept_psk_mode stores whether the client's PSK mode is compatible with our
1444 bool accept_psk_mode:1;
1446 // cert_request is true if a client certificate was requested.
1447 bool cert_request:1;
1449 // certificate_status_expected is true if OCSP stapling was negotiated and the
1450 // server is expected to send a CertificateStatus message. (This is used on
1451 // both the client and server sides.)
1452 bool certificate_status_expected:1;
1454 // ocsp_stapling_requested is true if a client requested OCSP stapling.
1455 bool ocsp_stapling_requested:1;
1457 // should_ack_sni is used by a server and indicates that the SNI extension
1458 // should be echoed in the ServerHello.
1459 bool should_ack_sni:1;
1461 // in_false_start is true if there is a pending client handshake in False
1462 // Start. The client may write data at this point.
1463 bool in_false_start:1;
1465 // in_early_data is true if there is a pending handshake that has progressed
1466 // enough to send and receive early data.
1467 bool in_early_data:1;
1469 // early_data_offered is true if the client sent the early_data extension.
1470 bool early_data_offered:1;
1472 // can_early_read is true if application data may be read at this point in the
1474 bool can_early_read:1;
1476 // can_early_write is true if application data may be written at this point in
1478 bool can_early_write:1;
1480 // next_proto_neg_seen is one of NPN was negotiated.
1481 bool next_proto_neg_seen:1;
1483 // ticket_expected is true if a TLS 1.2 NewSessionTicket message is to be sent
1485 bool ticket_expected:1;
1487 // extended_master_secret is true if the extended master secret extension is
1488 // negotiated in this handshake.
1489 bool extended_master_secret:1;
1491 // pending_private_key_op is true if there is a pending private key operation
1493 bool pending_private_key_op:1;
1495 // grease_seeded is true if |grease_seed| has been initialized.
1496 bool grease_seeded:1;
1498 // client_version is the value sent or received in the ClientHello version.
1499 uint16_t client_version = 0;
1501 // early_data_read is the amount of early data that has been read by the
1503 uint16_t early_data_read = 0;
1505 // early_data_written is the amount of early data that has been written by the
1507 uint16_t early_data_written = 0;
1509 // session_id is the session ID in the ClientHello, used for the experimental
1511 uint8_t session_id[SSL_MAX_SSL_SESSION_ID_LENGTH] = {0};
1512 uint8_t session_id_len = 0;
1514 // grease_seed is the entropy for GREASE values. It is valid if
1515 // |grease_seeded| is true.
1516 uint8_t grease_seed[ssl_grease_last_index + 1] = {0};
1518 // dummy_pq_padding_len, in a server, is the length of the extension that
1519 // should be echoed in a ServerHello, or zero if no extension should be
1521 uint16_t dummy_pq_padding_len = 0;
1524 UniquePtr<SSL_HANDSHAKE> ssl_handshake_new(SSL *ssl);
1526 // ssl_check_message_type checks if |msg| has type |type|. If so it returns
1527 // one. Otherwise, it sends an alert and returns zero.
1528 bool ssl_check_message_type(SSL *ssl, const SSLMessage &msg, int type);
1530 // ssl_run_handshake runs the TLS handshake. It returns one on success and <= 0
1531 // on error. It sets |out_early_return| to one if we've completed the handshake
1533 int ssl_run_handshake(SSL_HANDSHAKE *hs, bool *out_early_return);
1535 // The following are implementations of |do_handshake| for the client and
1537 enum ssl_hs_wait_t ssl_client_handshake(SSL_HANDSHAKE *hs);
1538 enum ssl_hs_wait_t ssl_server_handshake(SSL_HANDSHAKE *hs);
1539 enum ssl_hs_wait_t tls13_client_handshake(SSL_HANDSHAKE *hs);
1540 enum ssl_hs_wait_t tls13_server_handshake(SSL_HANDSHAKE *hs);
1542 // The following functions return human-readable representations of the TLS
1543 // handshake states for debugging.
1544 const char *ssl_client_handshake_state(SSL_HANDSHAKE *hs);
1545 const char *ssl_server_handshake_state(SSL_HANDSHAKE *hs);
1546 const char *tls13_client_handshake_state(SSL_HANDSHAKE *hs);
1547 const char *tls13_server_handshake_state(SSL_HANDSHAKE *hs);
1549 // tls13_post_handshake processes a post-handshake message. It returns one on
1550 // success and zero on failure.
1551 int tls13_post_handshake(SSL *ssl, const SSLMessage &msg);
1553 int tls13_process_certificate(SSL_HANDSHAKE *hs, const SSLMessage &msg,
1554 int allow_anonymous);
1555 int tls13_process_certificate_verify(SSL_HANDSHAKE *hs, const SSLMessage &msg);
1557 // tls13_process_finished processes |msg| as a Finished message from the
1558 // peer. If |use_saved_value| is one, the verify_data is compared against
1559 // |hs->expected_client_finished| rather than computed fresh.
1560 int tls13_process_finished(SSL_HANDSHAKE *hs, const SSLMessage &msg,
1561 int use_saved_value);
1563 int tls13_add_certificate(SSL_HANDSHAKE *hs);
1565 // tls13_add_certificate_verify adds a TLS 1.3 CertificateVerify message to the
1566 // handshake. If it returns |ssl_private_key_retry|, it should be called again
1567 // to retry when the signing operation is completed.
1568 enum ssl_private_key_result_t tls13_add_certificate_verify(SSL_HANDSHAKE *hs);
1570 int tls13_add_finished(SSL_HANDSHAKE *hs);
1571 int tls13_process_new_session_ticket(SSL *ssl, const SSLMessage &msg);
1573 bool ssl_ext_key_share_parse_serverhello(SSL_HANDSHAKE *hs,
1574 Array<uint8_t> *out_secret,
1575 uint8_t *out_alert, CBS *contents);
1576 bool ssl_ext_key_share_parse_clienthello(SSL_HANDSHAKE *hs, bool *out_found,
1577 Array<uint8_t> *out_secret,
1578 uint8_t *out_alert, CBS *contents);
1579 bool ssl_ext_key_share_add_serverhello(SSL_HANDSHAKE *hs, CBB *out);
1581 bool ssl_ext_pre_shared_key_parse_serverhello(SSL_HANDSHAKE *hs,
1584 bool ssl_ext_pre_shared_key_parse_clienthello(
1585 SSL_HANDSHAKE *hs, CBS *out_ticket, CBS *out_binders,
1586 uint32_t *out_obfuscated_ticket_age, uint8_t *out_alert, CBS *contents);
1587 bool ssl_ext_pre_shared_key_add_serverhello(SSL_HANDSHAKE *hs, CBB *out);
1589 // ssl_is_sct_list_valid does a shallow parse of the SCT list in |contents| and
1590 // returns one iff it's valid.
1591 int ssl_is_sct_list_valid(const CBS *contents);
1593 int ssl_write_client_hello(SSL_HANDSHAKE *hs);
1595 enum ssl_cert_verify_context_t {
1596 ssl_cert_verify_server,
1597 ssl_cert_verify_client,
1598 ssl_cert_verify_channel_id,
1601 // tls13_get_cert_verify_signature_input generates the message to be signed for
1602 // TLS 1.3's CertificateVerify message. |cert_verify_context| determines the
1603 // type of signature. It sets |*out| to a newly allocated buffer containing the
1604 // result. This function returns true on success and false on failure.
1605 bool tls13_get_cert_verify_signature_input(
1606 SSL_HANDSHAKE *hs, Array<uint8_t> *out,
1607 enum ssl_cert_verify_context_t cert_verify_context);
1609 // ssl_is_alpn_protocol_allowed returns whether |protocol| is a valid server
1610 // selection for |ssl|'s client preferences.
1611 bool ssl_is_alpn_protocol_allowed(const SSL *ssl, Span<const uint8_t> protocol);
1613 // ssl_negotiate_alpn negotiates the ALPN extension, if applicable. It returns
1614 // true on successful negotiation or if nothing was negotiated. It returns false
1615 // and sets |*out_alert| to an alert on error.
1616 bool ssl_negotiate_alpn(SSL_HANDSHAKE *hs, uint8_t *out_alert,
1617 const SSL_CLIENT_HELLO *client_hello);
1619 struct SSL_EXTENSION_TYPE {
1625 // ssl_parse_extensions parses a TLS extensions block out of |cbs| and advances
1626 // it. It writes the parsed extensions to pointers denoted by |ext_types|. On
1627 // success, it fills in the |out_present| and |out_data| fields and returns one.
1628 // Otherwise, it sets |*out_alert| to an alert to send and returns zero. Unknown
1629 // extensions are rejected unless |ignore_unknown| is 1.
1630 int ssl_parse_extensions(const CBS *cbs, uint8_t *out_alert,
1631 const SSL_EXTENSION_TYPE *ext_types,
1632 size_t num_ext_types, int ignore_unknown);
1634 // ssl_verify_peer_cert verifies the peer certificate for |hs|.
1635 enum ssl_verify_result_t ssl_verify_peer_cert(SSL_HANDSHAKE *hs);
1637 enum ssl_hs_wait_t ssl_get_finished(SSL_HANDSHAKE *hs);
1638 bool ssl_send_finished(SSL_HANDSHAKE *hs);
1639 bool ssl_output_cert_chain(SSL *ssl);
1642 // SSLKEYLOGFILE functions.
1644 // ssl_log_secret logs |secret| with label |label|, if logging is enabled for
1645 // |ssl|. It returns one on success and zero on failure.
1646 int ssl_log_secret(const SSL *ssl, const char *label, const uint8_t *secret,
1650 // ClientHello functions.
1652 int ssl_client_hello_init(SSL *ssl, SSL_CLIENT_HELLO *out,
1653 const SSLMessage &msg);
1655 int ssl_client_hello_get_extension(const SSL_CLIENT_HELLO *client_hello,
1656 CBS *out, uint16_t extension_type);
1658 int ssl_client_cipher_list_contains_cipher(const SSL_CLIENT_HELLO *client_hello,
1664 // ssl_get_grease_value returns a GREASE value for |hs|. For a given
1665 // connection, the values for each index will be deterministic. This allows the
1666 // same ClientHello be sent twice for a HelloRetryRequest or the same group be
1667 // advertised in both supported_groups and key_shares.
1668 uint16_t ssl_get_grease_value(SSL_HANDSHAKE *hs, enum ssl_grease_index_t index);
1671 // Signature algorithms.
1673 // tls1_parse_peer_sigalgs parses |sigalgs| as the list of peer signature
1674 // algorithms and saves them on |hs|. It returns true on success and false on
1676 bool tls1_parse_peer_sigalgs(SSL_HANDSHAKE *hs, const CBS *sigalgs);
1678 // tls1_get_legacy_signature_algorithm sets |*out| to the signature algorithm
1679 // that should be used with |pkey| in TLS 1.1 and earlier. It returns true on
1680 // success and false if |pkey| may not be used at those versions.
1681 bool tls1_get_legacy_signature_algorithm(uint16_t *out, const EVP_PKEY *pkey);
1683 // tls1_choose_signature_algorithm sets |*out| to a signature algorithm for use
1684 // with |hs|'s private key based on the peer's preferences and the algorithms
1685 // supported. It returns true on success and false on error.
1686 bool tls1_choose_signature_algorithm(SSL_HANDSHAKE *hs, uint16_t *out);
1688 // tls12_add_verify_sigalgs adds the signature algorithms acceptable for the
1689 // peer signature to |out|. It returns true on success and false on error.
1690 bool tls12_add_verify_sigalgs(const SSL *ssl, CBB *out);
1692 // tls12_check_peer_sigalg checks if |sigalg| is acceptable for the peer
1693 // signature. It returns true on success and false on error, setting
1694 // |*out_alert| to an alert to send.
1695 bool tls12_check_peer_sigalg(const SSL *ssl, uint8_t *out_alert,
1699 // Underdocumented functions.
1701 // Functions below here haven't been touched up and may be underdocumented.
1703 #define TLSEXT_CHANNEL_ID_SIZE 128
1705 // From RFC4492, used in encoding the curve type in ECParameters
1706 #define NAMED_CURVE_TYPE 3
1709 EVP_PKEY *privatekey;
1711 // chain contains the certificate chain, with the leaf at the beginning. The
1712 // first element of |chain| may be NULL to indicate that the leaf certificate
1713 // has not yet been set.
1714 // If |chain| != NULL -> len(chain) >= 1
1715 // If |chain[0]| == NULL -> len(chain) >= 2.
1716 // |chain[1..]| != NULL
1717 STACK_OF(CRYPTO_BUFFER) *chain;
1719 // x509_chain may contain a parsed copy of |chain[1..]|. This is only used as
1720 // a cache in order to implement “get0” functions that return a non-owning
1721 // pointer to the certificate chain.
1722 STACK_OF(X509) *x509_chain;
1724 // x509_leaf may contain a parsed copy of the first element of |chain|. This
1725 // is only used as a cache in order to implement “get0” functions that return
1726 // a non-owning pointer to the certificate chain.
1729 // x509_stash contains the last |X509| object append to the chain. This is a
1730 // workaround for some third-party code that continue to use an |X509| object
1731 // even after passing ownership with an “add0” function.
1734 // key_method, if non-NULL, is a set of callbacks to call for private key
1736 const SSL_PRIVATE_KEY_METHOD *key_method;
1738 // x509_method contains pointers to functions that might deal with |X509|
1739 // compatibility, or might be a no-op, depending on the application.
1740 const SSL_X509_METHOD *x509_method;
1742 // sigalgs, if non-NULL, is the set of signature algorithms supported by
1743 // |privatekey| in decreasing order of preference.
1747 // Certificate setup callback: if set is called whenever a
1748 // certificate may be required (client or server). the callback
1749 // can then examine any appropriate parameters and setup any
1750 // certificates required. This allows advanced applications
1751 // to select certificates on the fly: for example based on
1752 // supported signature algorithms or curves.
1753 int (*cert_cb)(SSL *ssl, void *arg);
1756 // Optional X509_STORE for certificate validation. If NULL the parent SSL_CTX
1757 // store is used instead.
1758 X509_STORE *verify_store;
1760 // Signed certificate timestamp list to be sent to the client, if requested
1761 CRYPTO_BUFFER *signed_cert_timestamp_list;
1763 // OCSP response to be sent to the client, if requested.
1764 CRYPTO_BUFFER *ocsp_response;
1766 // sid_ctx partitions the session space within a shared session cache or
1767 // ticket key. Only sessions with a matching value will be accepted.
1768 uint8_t sid_ctx_length;
1769 uint8_t sid_ctx[SSL_MAX_SID_CTX_LENGTH];
1771 // If enable_early_data is true, early data can be sent and accepted.
1772 bool enable_early_data:1;
1775 // |SSL_PROTOCOL_METHOD| abstracts between TLS and DTLS.
1776 struct SSL_PROTOCOL_METHOD {
1778 bool (*ssl_new)(SSL *ssl);
1779 void (*ssl_free)(SSL *ssl);
1780 // get_message sets |*out| to the current handshake message and returns true
1781 // if one has been received. It returns false if more input is needed.
1782 bool (*get_message)(SSL *ssl, SSLMessage *out);
1783 // next_message is called to release the current handshake message.
1784 void (*next_message)(SSL *ssl);
1785 // Use the |ssl_open_handshake| wrapper.
1786 ssl_open_record_t (*open_handshake)(SSL *ssl, size_t *out_consumed,
1787 uint8_t *out_alert, Span<uint8_t> in);
1788 // Use the |ssl_open_change_cipher_spec| wrapper.
1789 ssl_open_record_t (*open_change_cipher_spec)(SSL *ssl, size_t *out_consumed,
1792 // Use the |ssl_open_app_data| wrapper.
1793 ssl_open_record_t (*open_app_data)(SSL *ssl, Span<uint8_t> *out,
1794 size_t *out_consumed, uint8_t *out_alert,
1796 int (*write_app_data)(SSL *ssl, bool *out_needs_handshake, const uint8_t *buf,
1798 int (*dispatch_alert)(SSL *ssl);
1799 // init_message begins a new handshake message of type |type|. |cbb| is the
1800 // root CBB to be passed into |finish_message|. |*body| is set to a child CBB
1801 // the caller should write to. It returns true on success and false on error.
1802 bool (*init_message)(SSL *ssl, CBB *cbb, CBB *body, uint8_t type);
1803 // finish_message finishes a handshake message. It sets |*out_msg| to the
1804 // serialized message. It returns true on success and false on error.
1805 bool (*finish_message)(SSL *ssl, CBB *cbb, bssl::Array<uint8_t> *out_msg);
1806 // add_message adds a handshake message to the pending flight. It returns
1807 // true on success and false on error.
1808 bool (*add_message)(SSL *ssl, bssl::Array<uint8_t> msg);
1809 // add_change_cipher_spec adds a ChangeCipherSpec record to the pending
1810 // flight. It returns true on success and false on error.
1811 bool (*add_change_cipher_spec)(SSL *ssl);
1812 // add_alert adds an alert to the pending flight. It returns true on success
1813 // and false on error.
1814 bool (*add_alert)(SSL *ssl, uint8_t level, uint8_t desc);
1815 // flush_flight flushes the pending flight to the transport. It returns one on
1816 // success and <= 0 on error.
1817 int (*flush_flight)(SSL *ssl);
1818 // on_handshake_complete is called when the handshake is complete.
1819 void (*on_handshake_complete)(SSL *ssl);
1820 // set_read_state sets |ssl|'s read cipher state to |aead_ctx|. It returns
1821 // true on success and false if changing the read state is forbidden at this
1823 bool (*set_read_state)(SSL *ssl, UniquePtr<SSLAEADContext> aead_ctx);
1824 // set_write_state sets |ssl|'s write cipher state to |aead_ctx|. It returns
1825 // true on success and false if changing the write state is forbidden at this
1827 bool (*set_write_state)(SSL *ssl, UniquePtr<SSLAEADContext> aead_ctx);
1830 // The following wrappers call |open_*| but handle |read_shutdown| correctly.
1832 // ssl_open_handshake processes a record from |in| for reading a handshake
1834 ssl_open_record_t ssl_open_handshake(SSL *ssl, size_t *out_consumed,
1835 uint8_t *out_alert, Span<uint8_t> in);
1837 // ssl_open_change_cipher_spec processes a record from |in| for reading a
1838 // ChangeCipherSpec.
1839 ssl_open_record_t ssl_open_change_cipher_spec(SSL *ssl, size_t *out_consumed,
1843 // ssl_open_app_data processes a record from |in| for reading application data.
1844 // On success, it returns |ssl_open_record_success| and sets |*out| to the
1845 // input. If it encounters a post-handshake message, it returns
1846 // |ssl_open_record_discard|. The caller should then retry, after processing any
1847 // messages received with |get_message|.
1848 ssl_open_record_t ssl_open_app_data(SSL *ssl, Span<uint8_t> *out,
1849 size_t *out_consumed, uint8_t *out_alert,
1852 // ssl_crypto_x509_method provides the |SSL_X509_METHOD| functions using
1854 extern const SSL_X509_METHOD ssl_crypto_x509_method;
1856 // ssl_noop_x509_method provides the |SSL_X509_METHOD| functions that avoid
1858 extern const SSL_X509_METHOD ssl_noop_x509_method;
1860 // ssl_cipher_preference_list_st contains a list of SSL_CIPHERs with
1861 // equal-preference groups. For TLS clients, the groups are moot because the
1862 // server picks the cipher and groups cannot be expressed on the wire. However,
1863 // for servers, the equal-preference groups allow the client's preferences to
1864 // be partially respected. (This only has an effect with
1865 // SSL_OP_CIPHER_SERVER_PREFERENCE).
1867 // The equal-preference groups are expressed by grouping SSL_CIPHERs together.
1868 // All elements of a group have the same priority: no ordering is expressed
1871 // The values in |ciphers| are in one-to-one correspondence with
1872 // |in_group_flags|. (That is, sk_SSL_CIPHER_num(ciphers) is the number of
1873 // bytes in |in_group_flags|.) The bytes in |in_group_flags| are either 1, to
1874 // indicate that the corresponding SSL_CIPHER is not the last element of a
1875 // group, or 0 to indicate that it is.
1877 // For example, if |in_group_flags| contains all zeros then that indicates a
1878 // traditional, fully-ordered preference. Every SSL_CIPHER is the last element
1879 // of the group (i.e. they are all in a one-element group).
1881 // For a more complex example, consider:
1882 // ciphers: A B C D E F
1883 // in_group_flags: 1 1 0 0 1 0
1885 // That would express the following, order:
1890 struct ssl_cipher_preference_list_st {
1891 STACK_OF(SSL_CIPHER) *ciphers;
1892 uint8_t *in_group_flags;
1895 struct tlsext_ticket_key {
1896 static constexpr bool kAllowUniquePtr = true;
1898 uint8_t name[SSL_TICKET_KEY_NAME_LEN];
1899 uint8_t hmac_key[16];
1900 uint8_t aes_key[16];
1901 // next_rotation_tv_sec is the time (in seconds from the epoch) when the
1902 // current key should be superseded by a new key, or the time when a previous
1903 // key should be dropped. If zero, then the key should not be automatically
1905 uint64_t next_rotation_tv_sec;
1910 DECLARE_LHASH_OF(SSL_SESSION)
1914 // SSLContext backs the public |SSL_CTX| type. Due to compatibility constraints,
1915 // it is a base class for |ssl_ctx_st|.
1917 const SSL_PROTOCOL_METHOD *method;
1918 const SSL_X509_METHOD *x509_method;
1920 // lock is used to protect various operations on this object.
1923 // conf_max_version is the maximum acceptable protocol version configured by
1924 // |SSL_CTX_set_max_proto_version|. Note this version is normalized in DTLS
1925 // and is further constrainted by |SSL_OP_NO_*|.
1926 uint16_t conf_max_version;
1928 // conf_min_version is the minimum acceptable protocol version configured by
1929 // |SSL_CTX_set_min_proto_version|. Note this version is normalized in DTLS
1930 // and is further constrainted by |SSL_OP_NO_*|.
1931 uint16_t conf_min_version;
1933 // tls13_variant is the variant of TLS 1.3 we are using for this
1935 enum tls13_variant_t tls13_variant;
1937 struct ssl_cipher_preference_list_st *cipher_list;
1939 X509_STORE *cert_store;
1940 LHASH_OF(SSL_SESSION) *sessions;
1941 // Most session-ids that will be cached, default is
1942 // SSL_SESSION_CACHE_MAX_SIZE_DEFAULT. 0 is unlimited.
1943 unsigned long session_cache_size;
1944 SSL_SESSION *session_cache_head;
1945 SSL_SESSION *session_cache_tail;
1947 // handshakes_since_cache_flush is the number of successful handshakes since
1948 // the last cache flush.
1949 int handshakes_since_cache_flush;
1951 // This can have one of 2 values, ored together,
1952 // SSL_SESS_CACHE_CLIENT,
1953 // SSL_SESS_CACHE_SERVER,
1954 // Default is SSL_SESSION_CACHE_SERVER, which means only
1955 // SSL_accept which cache SSL_SESSIONS.
1956 int session_cache_mode;
1958 // session_timeout is the default lifetime for new sessions in TLS 1.2 and
1959 // earlier, in seconds.
1960 uint32_t session_timeout;
1962 // session_psk_dhe_timeout is the default lifetime for new sessions in TLS
1964 uint32_t session_psk_dhe_timeout;
1966 // If this callback is not null, it will be called each time a session id is
1967 // added to the cache. If this function returns 1, it means that the
1968 // callback will do a SSL_SESSION_free() when it has finished using it.
1969 // Otherwise, on 0, it means the callback has finished with it. If
1970 // remove_session_cb is not null, it will be called when a session-id is
1971 // removed from the cache. After the call, OpenSSL will SSL_SESSION_free()
1973 int (*new_session_cb)(SSL *ssl, SSL_SESSION *sess);
1974 void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *sess);
1975 SSL_SESSION *(*get_session_cb)(SSL *ssl, const uint8_t *data, int len,
1977 SSL_SESSION *(*get_session_cb_legacy)(SSL *ssl, uint8_t *data, int len,
1980 CRYPTO_refcount_t references;
1982 // if defined, these override the X509_verify_cert() calls
1983 int (*app_verify_callback)(X509_STORE_CTX *store_ctx, void *arg);
1984 void *app_verify_arg;
1986 enum ssl_verify_result_t (*custom_verify_callback)(SSL *ssl,
1987 uint8_t *out_alert);
1989 // Default password callback.
1990 pem_password_cb *default_passwd_callback;
1992 // Default password callback user data.
1993 void *default_passwd_callback_userdata;
1995 // get client cert callback
1996 int (*client_cert_cb)(SSL *ssl, X509 **out_x509, EVP_PKEY **out_pkey);
1998 // get channel id callback
1999 void (*channel_id_cb)(SSL *ssl, EVP_PKEY **out_pkey);
2001 CRYPTO_EX_DATA ex_data;
2003 // custom_*_extensions stores any callback sets for custom extensions. Note
2004 // that these pointers will be NULL if the stack would otherwise be empty.
2005 STACK_OF(SSL_CUSTOM_EXTENSION) *client_custom_extensions;
2006 STACK_OF(SSL_CUSTOM_EXTENSION) *server_custom_extensions;
2008 // Default values used when no per-SSL value is defined follow
2010 void (*info_callback)(const SSL *ssl, int type, int value);
2012 // what we put in client cert requests
2013 STACK_OF(CRYPTO_BUFFER) *client_CA;
2015 // cached_x509_client_CA is a cache of parsed versions of the elements of
2017 STACK_OF(X509_NAME) *cached_x509_client_CA;
2020 // Default values to use in SSL structures follow (these are copied by
2025 uint32_t max_cert_list;
2029 // callback that allows applications to peek at protocol messages
2030 void (*msg_callback)(int write_p, int version, int content_type,
2031 const void *buf, size_t len, SSL *ssl, void *arg);
2032 void *msg_callback_arg;
2035 int (*default_verify_callback)(
2036 int ok, X509_STORE_CTX *ctx); // called 'verify_callback' in the SSL
2038 X509_VERIFY_PARAM *param;
2040 // select_certificate_cb is called before most ClientHello processing and
2041 // before the decision whether to resume a session is made. See
2042 // |ssl_select_cert_result_t| for details of the return values.
2043 enum ssl_select_cert_result_t (*select_certificate_cb)(
2044 const SSL_CLIENT_HELLO *);
2046 // dos_protection_cb is called once the resumption decision for a ClientHello
2047 // has been made. It returns one to continue the handshake or zero to
2049 int (*dos_protection_cb) (const SSL_CLIENT_HELLO *);
2051 // Maximum amount of data to send in one fragment. actual record size can be
2052 // more than this due to padding and MAC overheads.
2053 uint16_t max_send_fragment;
2055 // TLS extensions servername callback
2056 int (*tlsext_servername_callback)(SSL *, int *, void *);
2057 void *tlsext_servername_arg;
2059 // RFC 4507 session ticket keys. |tlsext_ticket_key_current| may be NULL
2060 // before the first handshake and |tlsext_ticket_key_prev| may be NULL at any
2061 // time. Automatically generated ticket keys are rotated as needed at
2062 // handshake time. Hence, all access must be synchronized through |lock|.
2063 struct tlsext_ticket_key *tlsext_ticket_key_current;
2064 struct tlsext_ticket_key *tlsext_ticket_key_prev;
2066 // Callback to support customisation of ticket key setting
2067 int (*tlsext_ticket_key_cb)(SSL *ssl, uint8_t *name, uint8_t *iv,
2068 EVP_CIPHER_CTX *ectx, HMAC_CTX *hctx, int enc);
2070 // Server-only: psk_identity_hint is the default identity hint to send in
2071 // PSK-based key exchanges.
2072 char *psk_identity_hint;
2074 unsigned int (*psk_client_callback)(SSL *ssl, const char *hint,
2076 unsigned int max_identity_len,
2077 uint8_t *psk, unsigned int max_psk_len);
2078 unsigned int (*psk_server_callback)(SSL *ssl, const char *identity,
2079 uint8_t *psk, unsigned int max_psk_len);
2082 // Next protocol negotiation information
2083 // (for experimental NPN extension).
2085 // For a server, this contains a callback function by which the set of
2086 // advertised protocols can be provided.
2087 int (*next_protos_advertised_cb)(SSL *ssl, const uint8_t **out,
2088 unsigned *out_len, void *arg);
2089 void *next_protos_advertised_cb_arg;
2090 // For a client, this contains a callback function that selects the
2091 // next protocol from the list provided by the server.
2092 int (*next_proto_select_cb)(SSL *ssl, uint8_t **out, uint8_t *out_len,
2093 const uint8_t *in, unsigned in_len, void *arg);
2094 void *next_proto_select_cb_arg;
2097 // (we are in the process of transitioning from NPN to ALPN.)
2099 // For a server, this contains a callback function that allows the
2100 // server to select the protocol for the connection.
2101 // out: on successful return, this must point to the raw protocol
2102 // name (without the length prefix).
2103 // outlen: on successful return, this contains the length of |*out|.
2104 // in: points to the client's list of supported protocols in
2106 // inlen: the length of |in|.
2107 int (*alpn_select_cb)(SSL *ssl, const uint8_t **out, uint8_t *out_len,
2108 const uint8_t *in, unsigned in_len, void *arg);
2109 void *alpn_select_cb_arg;
2111 // For a client, this contains the list of supported protocols in wire
2113 uint8_t *alpn_client_proto_list;
2114 unsigned alpn_client_proto_list_len;
2116 // SRTP profiles we are willing to do from RFC 5764
2117 STACK_OF(SRTP_PROTECTION_PROFILE) *srtp_profiles;
2119 // Supported group values inherited by SSL structure
2120 size_t supported_group_list_len;
2121 uint16_t *supported_group_list;
2123 // The client's Channel ID private key.
2124 EVP_PKEY *tlsext_channel_id_private;
2126 // keylog_callback, if not NULL, is the key logging callback. See
2127 // |SSL_CTX_set_keylog_callback|.
2128 void (*keylog_callback)(const SSL *ssl, const char *line);
2130 // current_time_cb, if not NULL, is the function to use to get the current
2131 // time. It sets |*out_clock| to the current time. The |ssl| argument is
2132 // always NULL. See |SSL_CTX_set_current_time_cb|.
2133 void (*current_time_cb)(const SSL *ssl, struct timeval *out_clock);
2135 // pool is used for all |CRYPTO_BUFFER|s in case we wish to share certificate
2137 CRYPTO_BUFFER_POOL *pool;
2139 // ticket_aead_method contains function pointers for opening and sealing
2141 const SSL_TICKET_AEAD_METHOD *ticket_aead_method;
2143 // verify_sigalgs, if not empty, is the set of signature algorithms
2144 // accepted from the peer in decreasing order of preference.
2145 uint16_t *verify_sigalgs;
2146 size_t num_verify_sigalgs;
2148 // retain_only_sha256_of_client_certs is true if we should compute the SHA256
2149 // hash of the peer's certificate and then discard it to save memory and
2150 // session space. Only effective on the server side.
2151 bool retain_only_sha256_of_client_certs:1;
2153 // quiet_shutdown is true if the connection should not send a close_notify on
2155 bool quiet_shutdown:1;
2157 // ocsp_stapling_enabled is only used by client connections and indicates
2158 // whether OCSP stapling will be requested.
2159 bool ocsp_stapling_enabled:1;
2161 // If true, a client will request certificate timestamps.
2162 bool signed_cert_timestamps_enabled:1;
2164 // tlsext_channel_id_enabled is whether Channel ID is enabled. For a server,
2165 // means that we'll accept Channel IDs from clients. For a client, means that
2166 // we'll advertise support.
2167 bool tlsext_channel_id_enabled:1;
2169 // grease_enabled is whether draft-davidben-tls-grease-01 is enabled.
2170 bool grease_enabled:1;
2172 // allow_unknown_alpn_protos is whether the client allows unsolicited ALPN
2173 // protocols from the peer.
2174 bool allow_unknown_alpn_protos:1;
2176 // ed25519_enabled is whether Ed25519 is advertised in the handshake.
2177 bool ed25519_enabled:1;
2179 // false_start_allowed_without_alpn is whether False Start (if
2180 // |SSL_MODE_ENABLE_FALSE_START| is enabled) is allowed without ALPN.
2181 bool false_start_allowed_without_alpn:1;
2183 // handoff indicates that a server should stop after receiving the
2184 // ClientHello and pause the handshake in such a way that |SSL_get_error|
2185 // returns |SSL_HANDOFF|.
2189 // An ssl_shutdown_t describes the shutdown state of one end of the connection,
2190 // whether it is alive or has been shutdown via close_notify or fatal alert.
2191 enum ssl_shutdown_t {
2192 ssl_shutdown_none = 0,
2193 ssl_shutdown_close_notify = 1,
2194 ssl_shutdown_error = 2,
2198 static constexpr bool kAllowUniquePtr = true;
2203 uint8_t read_sequence[8] = {0};
2204 uint8_t write_sequence[8] = {0};
2206 uint8_t server_random[SSL3_RANDOM_SIZE] = {0};
2207 uint8_t client_random[SSL3_RANDOM_SIZE] = {0};
2209 // read_buffer holds data from the transport to be processed.
2210 SSLBuffer read_buffer;
2211 // write_buffer holds data to be written to the transport.
2212 SSLBuffer write_buffer;
2214 // pending_app_data is the unconsumed application data. It points into
2216 Span<uint8_t> pending_app_data;
2218 // partial write - check the numbers match
2219 unsigned int wnum = 0; // number of bytes sent so far
2220 int wpend_tot = 0; // number bytes written
2222 int wpend_ret = 0; // number of bytes submitted
2223 const uint8_t *wpend_buf = nullptr;
2225 // read_shutdown is the shutdown state for the read half of the connection.
2226 enum ssl_shutdown_t read_shutdown = ssl_shutdown_none;
2228 // write_shutdown is the shutdown state for the write half of the connection.
2229 enum ssl_shutdown_t write_shutdown = ssl_shutdown_none;
2231 // read_error, if |read_shutdown| is |ssl_shutdown_error|, is the error for
2232 // the receive half of the connection.
2233 UniquePtr<ERR_SAVE_STATE> read_error;
2235 int alert_dispatch = 0;
2237 int total_renegotiations = 0;
2239 // This holds a variable that indicates what we were doing when a 0 or -1 is
2240 // returned. This is needed for non-blocking IO so we know what request
2241 // needs re-doing when in SSL_accept or SSL_connect
2242 int rwstate = SSL_NOTHING;
2244 // early_data_skipped is the amount of early data that has been skipped by the
2246 uint16_t early_data_skipped = 0;
2248 // empty_record_count is the number of consecutive empty records received.
2249 uint8_t empty_record_count = 0;
2251 // warning_alert_count is the number of consecutive warning alerts
2253 uint8_t warning_alert_count = 0;
2255 // key_update_count is the number of consecutive KeyUpdates received.
2256 uint8_t key_update_count = 0;
2258 // skip_early_data instructs the record layer to skip unexpected early data
2259 // messages when 0RTT is rejected.
2260 bool skip_early_data:1;
2262 // have_version is true if the connection's final version is known. Otherwise
2263 // the version has not been negotiated yet.
2264 bool have_version:1;
2266 // v2_hello_done is true if the peer's V2ClientHello, if any, has been handled
2267 // and future messages should use the record layer.
2268 bool v2_hello_done:1;
2270 // is_v2_hello is true if the current handshake message was derived from a
2271 // V2ClientHello rather than received from the peer directly.
2274 // has_message is true if the current handshake message has been returned
2275 // at least once by |get_message| and false otherwise.
2278 // initial_handshake_complete is true if the initial handshake has
2280 bool initial_handshake_complete:1;
2282 // session_reused indicates whether a session was resumed.
2283 bool session_reused:1;
2285 bool send_connection_binding:1;
2287 // In a client, this means that the server supported Channel ID and that a
2288 // Channel ID was sent. In a server it means that we echoed support for
2289 // Channel IDs and that tlsext_channel_id will be valid after the
2291 bool tlsext_channel_id_valid:1;
2293 // key_update_pending is true if we have a KeyUpdate acknowledgment
2295 bool key_update_pending:1;
2297 // wpend_pending is true if we have a pending write outstanding.
2298 bool wpend_pending:1;
2300 // early_data_accepted is true if early data was accepted by the server.
2301 bool early_data_accepted:1;
2303 // draft_downgrade is whether the TLS 1.3 anti-downgrade logic would have
2304 // fired, were it not a draft.
2305 bool draft_downgrade:1;
2307 // hs_buf is the buffer of handshake data to process.
2308 UniquePtr<BUF_MEM> hs_buf;
2310 // pending_flight is the pending outgoing flight. This is used to flush each
2311 // handshake flight in a single write. |write_buffer| must be written out
2312 // before this data.
2313 UniquePtr<BUF_MEM> pending_flight;
2315 // pending_flight_offset is the number of bytes of |pending_flight| which have
2316 // been successfully written.
2317 uint32_t pending_flight_offset = 0;
2319 // ticket_age_skew is the difference, in seconds, between the client-sent
2320 // ticket age and the server-computed value in TLS 1.3 server connections
2321 // which resumed a session.
2322 int32_t ticket_age_skew = 0;
2324 // aead_read_ctx is the current read cipher state.
2325 UniquePtr<SSLAEADContext> aead_read_ctx;
2327 // aead_write_ctx is the current write cipher state.
2328 UniquePtr<SSLAEADContext> aead_write_ctx;
2330 // hs is the handshake state for the current handshake or NULL if there isn't
2332 UniquePtr<SSL_HANDSHAKE> hs;
2334 uint8_t write_traffic_secret[EVP_MAX_MD_SIZE] = {0};
2335 uint8_t read_traffic_secret[EVP_MAX_MD_SIZE] = {0};
2336 uint8_t exporter_secret[EVP_MAX_MD_SIZE] = {0};
2337 uint8_t early_exporter_secret[EVP_MAX_MD_SIZE] = {0};
2338 uint8_t write_traffic_secret_len = 0;
2339 uint8_t read_traffic_secret_len = 0;
2340 uint8_t exporter_secret_len = 0;
2341 uint8_t early_exporter_secret_len = 0;
2343 // Connection binding to prevent renegotiation attacks
2344 uint8_t previous_client_finished[12] = {0};
2345 uint8_t previous_client_finished_len = 0;
2346 uint8_t previous_server_finished_len = 0;
2347 uint8_t previous_server_finished[12] = {0};
2349 uint8_t send_alert[2] = {0};
2351 // established_session is the session established by the connection. This
2352 // session is only filled upon the completion of the handshake and is
2354 UniquePtr<SSL_SESSION> established_session;
2356 // Next protocol negotiation. For the client, this is the protocol that we
2357 // sent in NextProtocol and is set when handling ServerHello extensions.
2359 // For a server, this is the client's selected_protocol from NextProtocol and
2360 // is set when handling the NextProtocol message, before the Finished
2362 Array<uint8_t> next_proto_negotiated;
2365 // (we are in the process of transitioning from NPN to ALPN.)
2367 // In a server these point to the selected ALPN protocol after the
2368 // ClientHello has been processed. In a client these contain the protocol
2369 // that the server selected once the ServerHello has been processed.
2370 Array<uint8_t> alpn_selected;
2372 // hostname, on the server, is the value of the SNI extension.
2373 UniquePtr<char> hostname;
2376 // If |tlsext_channel_id_valid| is true, then this contains the
2377 // verified Channel ID from the client: a P256 point, (x,y), where
2378 // each are big-endian values.
2379 uint8_t tlsext_channel_id[64] = {0};
2381 // Contains the QUIC transport params received by the peer.
2382 Array<uint8_t> peer_quic_transport_params;
2385 // lengths of messages
2386 #define DTLS1_COOKIE_LENGTH 256
2388 #define DTLS1_RT_HEADER_LENGTH 13
2390 #define DTLS1_HM_HEADER_LENGTH 12
2392 #define DTLS1_CCS_HEADER_LENGTH 1
2394 #define DTLS1_AL_HEADER_LENGTH 2
2396 struct hm_header_st {
2404 // An hm_fragment is an incoming DTLS message, possibly not yet assembled.
2405 struct hm_fragment {
2406 static constexpr bool kAllowUniquePtr = true;
2409 hm_fragment(const hm_fragment &) = delete;
2410 hm_fragment &operator=(const hm_fragment &) = delete;
2414 // type is the type of the message.
2416 // seq is the sequence number of this message.
2418 // msg_len is the length of the message body.
2419 uint32_t msg_len = 0;
2420 // data is a pointer to the message, including message header. It has length
2421 // |DTLS1_HM_HEADER_LENGTH| + |msg_len|.
2422 uint8_t *data = nullptr;
2423 // reassembly is a bitmask of |msg_len| bits corresponding to which parts of
2424 // the message have been received. It is NULL if the message is complete.
2425 uint8_t *reassembly = nullptr;
2428 struct OPENSSL_timeval {
2433 struct DTLS1_STATE {
2434 static constexpr bool kAllowUniquePtr = true;
2439 // has_change_cipher_spec is true if we have received a ChangeCipherSpec from
2440 // the peer in this epoch.
2441 bool has_change_cipher_spec:1;
2443 // outgoing_messages_complete is true if |outgoing_messages| has been
2444 // completed by an attempt to flush it. Future calls to |add_message| and
2445 // |add_change_cipher_spec| will start a new flight.
2446 bool outgoing_messages_complete:1;
2448 // flight_has_reply is true if the current outgoing flight is complete and has
2449 // processed at least one message. This is used to detect whether we or the
2450 // peer sent the final flight.
2451 bool flight_has_reply:1;
2453 uint8_t cookie[DTLS1_COOKIE_LENGTH] = {0};
2454 size_t cookie_len = 0;
2456 // The current data and handshake epoch. This is initially undefined, and
2457 // starts at zero once the initial handshake is completed.
2458 uint16_t r_epoch = 0;
2459 uint16_t w_epoch = 0;
2461 // records being received in the current epoch
2462 DTLS1_BITMAP bitmap;
2464 uint16_t handshake_write_seq = 0;
2465 uint16_t handshake_read_seq = 0;
2467 // save last sequence number for retransmissions
2468 uint8_t last_write_sequence[8] = {0};
2469 UniquePtr<SSLAEADContext> last_aead_write_ctx;
2471 // incoming_messages is a ring buffer of incoming handshake messages that have
2472 // yet to be processed. The front of the ring buffer is message number
2473 // |handshake_read_seq|, at position |handshake_read_seq| %
2474 // |SSL_MAX_HANDSHAKE_FLIGHT|.
2475 UniquePtr<hm_fragment> incoming_messages[SSL_MAX_HANDSHAKE_FLIGHT];
2477 // outgoing_messages is the queue of outgoing messages from the last handshake
2479 DTLS_OUTGOING_MESSAGE outgoing_messages[SSL_MAX_HANDSHAKE_FLIGHT];
2480 uint8_t outgoing_messages_len = 0;
2482 // outgoing_written is the number of outgoing messages that have been
2484 uint8_t outgoing_written = 0;
2485 // outgoing_offset is the number of bytes of the next outgoing message have
2487 uint32_t outgoing_offset = 0;
2489 unsigned mtu = 0; // max DTLS packet size
2491 // num_timeouts is the number of times the retransmit timer has fired since
2492 // the last time it was reset.
2493 unsigned num_timeouts = 0;
2495 // Indicates when the last handshake msg or heartbeat sent will
2497 struct OPENSSL_timeval next_timeout = {0, 0};
2499 // timeout_duration_ms is the timeout duration in milliseconds.
2500 unsigned timeout_duration_ms = 0;
2503 // SSLConnection backs the public |SSL| type. Due to compatibility constraints,
2504 // it is a base class for |ssl_st|.
2505 struct SSLConnection {
2506 // method is the method table corresponding to the current protocol (DTLS or
2508 const SSL_PROTOCOL_METHOD *method;
2510 // version is the protocol version.
2513 // conf_max_version is the maximum acceptable protocol version configured by
2514 // |SSL_set_max_proto_version|. Note this version is normalized in DTLS and is
2515 // further constrainted by |SSL_OP_NO_*|.
2516 uint16_t conf_max_version;
2518 // conf_min_version is the minimum acceptable protocol version configured by
2519 // |SSL_set_min_proto_version|. Note this version is normalized in DTLS and is
2520 // further constrainted by |SSL_OP_NO_*|.
2521 uint16_t conf_min_version;
2523 uint16_t max_send_fragment;
2525 // There are 2 BIO's even though they are normally both the same. This is so
2526 // data can be read and written to different handlers
2528 BIO *rbio; // used by SSL_read
2529 BIO *wbio; // used by SSL_write
2531 // do_handshake runs the handshake. On completion, it returns |ssl_hs_ok|.
2532 // Otherwise, it returns a value corresponding to what operation is needed to
2534 enum ssl_hs_wait_t (*do_handshake)(SSL_HANDSHAKE *hs);
2536 SSL3_STATE *s3; // SSLv3 variables
2537 DTLS1_STATE *d1; // DTLSv1 variables
2539 // callback that allows applications to peek at protocol messages
2540 void (*msg_callback)(int write_p, int version, int content_type,
2541 const void *buf, size_t len, SSL *ssl, void *arg);
2542 void *msg_callback_arg;
2544 X509_VERIFY_PARAM *param;
2547 struct ssl_cipher_preference_list_st *cipher_list;
2551 // This is used to hold the local certificate used (i.e. the server
2552 // certificate for a server or the client certificate for a client).
2555 // initial_timeout_duration_ms is the default DTLS timeout duration in
2556 // milliseconds. It's used to initialize the timer any time it's restarted.
2557 unsigned initial_timeout_duration_ms;
2559 // tls13_variant is the variant of TLS 1.3 we are using for this
2561 enum tls13_variant_t tls13_variant;
2563 // session is the configured session to be offered by the client. This session
2565 SSL_SESSION *session;
2567 int (*verify_callback)(int ok,
2568 X509_STORE_CTX *ctx); // fail if callback returns 0
2570 enum ssl_verify_result_t (*custom_verify_callback)(SSL *ssl,
2571 uint8_t *out_alert);
2573 void (*info_callback)(const SSL *ssl, int type, int value);
2575 // Server-only: psk_identity_hint is the identity hint to send in
2576 // PSK-based key exchanges.
2577 char *psk_identity_hint;
2579 unsigned int (*psk_client_callback)(SSL *ssl, const char *hint,
2581 unsigned int max_identity_len,
2582 uint8_t *psk, unsigned int max_psk_len);
2583 unsigned int (*psk_server_callback)(SSL *ssl, const char *identity,
2584 uint8_t *psk, unsigned int max_psk_len);
2588 // extra application data
2589 CRYPTO_EX_DATA ex_data;
2591 // for server side, keep the list of CA_dn we can use
2592 STACK_OF(CRYPTO_BUFFER) *client_CA;
2594 // cached_x509_client_CA is a cache of parsed versions of the elements of
2596 STACK_OF(X509_NAME) *cached_x509_client_CA;
2598 uint32_t options; // protocol behaviour
2599 uint32_t mode; // API behaviour
2600 uint32_t max_cert_list;
2601 uint16_t dummy_pq_padding_len;
2602 char *tlsext_hostname;
2603 size_t supported_group_list_len;
2604 uint16_t *supported_group_list; // our list
2606 // session_ctx is the |SSL_CTX| used for the session cache and related
2608 SSL_CTX *session_ctx;
2610 // srtp_profiles is the list of configured SRTP protection profiles for
2612 STACK_OF(SRTP_PROTECTION_PROFILE) *srtp_profiles;
2614 // srtp_profile is the selected SRTP protection profile for
2616 const SRTP_PROTECTION_PROFILE *srtp_profile;
2618 // The client's Channel ID private key.
2619 EVP_PKEY *tlsext_channel_id_private;
2621 // For a client, this contains the list of supported protocols in wire
2623 uint8_t *alpn_client_proto_list;
2624 unsigned alpn_client_proto_list_len;
2626 // Contains a list of supported Token Binding key parameters.
2627 uint8_t *token_binding_params;
2628 size_t token_binding_params_len;
2630 // The negotiated Token Binding key parameter. Only valid if
2631 // |token_binding_negotiated| is set.
2632 uint8_t negotiated_token_binding_param;
2634 // Contains the QUIC transport params that this endpoint will send.
2635 uint8_t *quic_transport_params;
2636 size_t quic_transport_params_len;
2638 // renegotiate_mode controls how peer renegotiation attempts are handled.
2639 enum ssl_renegotiate_mode_t renegotiate_mode;
2641 // verify_mode is a bitmask of |SSL_VERIFY_*| values.
2642 uint8_t verify_mode;
2644 // server is true iff the this SSL* is the server half. Note: before the SSL*
2645 // is initialized by either SSL_set_accept_state or SSL_set_connect_state,
2646 // the side is not determined. In this state, server is always false.
2649 // quiet_shutdown is true if the connection should not send a close_notify on
2651 bool quiet_shutdown:1;
2653 // Enable signed certificate time stamps. Currently client only.
2654 bool signed_cert_timestamps_enabled:1;
2656 // ocsp_stapling_enabled is only used by client connections and indicates
2657 // whether OCSP stapling will be requested.
2658 bool ocsp_stapling_enabled:1;
2660 // tlsext_channel_id_enabled is copied from the |SSL_CTX|. For a server,
2661 // means that we'll accept Channel IDs from clients. For a client, means that
2662 // we'll advertise support.
2663 bool tlsext_channel_id_enabled:1;
2665 // token_binding_negotiated is set if Token Binding was negotiated.
2666 bool token_binding_negotiated:1;
2668 // retain_only_sha256_of_client_certs is true if we should compute the SHA256
2669 // hash of the peer's certificate and then discard it to save memory and
2670 // session space. Only effective on the server side.
2671 bool retain_only_sha256_of_client_certs:1;
2673 // handoff indicates that a server should stop after receiving the
2674 // ClientHello and pause the handshake in such a way that |SSL_get_error|
2675 // returns |SSL_HANDOFF|. This is copied in |SSL_new| from the |SSL_CTX|
2676 // element of the same name and may be cleared if the handoff is declined.
2679 // did_dummy_pq_padding is only valid for a client. In that context, it is
2680 // true iff the client observed the server echoing a dummy PQ padding
2682 bool did_dummy_pq_padding:1;
2685 // From draft-ietf-tls-tls13-18, used in determining PSK modes.
2686 #define SSL_PSK_DHE_KE 0x1
2688 // From draft-ietf-tls-tls13-16, used in determining whether to respond with a
2690 #define SSL_KEY_UPDATE_NOT_REQUESTED 0
2691 #define SSL_KEY_UPDATE_REQUESTED 1
2693 // kMaxEarlyDataAccepted is the advertised number of plaintext bytes of early
2694 // data that will be accepted. This value should be slightly below
2695 // kMaxEarlyDataSkipped in tls_record.c, which is measured in ciphertext.
2696 static const size_t kMaxEarlyDataAccepted = 14336;
2698 CERT *ssl_cert_new(const SSL_X509_METHOD *x509_method);
2699 CERT *ssl_cert_dup(CERT *cert);
2700 void ssl_cert_clear_certs(CERT *cert);
2701 void ssl_cert_free(CERT *cert);
2702 int ssl_set_cert(CERT *cert, UniquePtr<CRYPTO_BUFFER> buffer);
2703 int ssl_is_key_type_supported(int key_type);
2704 // ssl_compare_public_and_private_key returns one if |pubkey| is the public
2705 // counterpart to |privkey|. Otherwise it returns zero and pushes a helpful
2706 // message on the error queue.
2707 int ssl_compare_public_and_private_key(const EVP_PKEY *pubkey,
2708 const EVP_PKEY *privkey);
2709 int ssl_cert_check_private_key(const CERT *cert, const EVP_PKEY *privkey);
2710 int ssl_get_new_session(SSL_HANDSHAKE *hs, int is_server);
2711 int ssl_encrypt_ticket(SSL *ssl, CBB *out, const SSL_SESSION *session);
2712 int ssl_ctx_rotate_ticket_encryption_key(SSL_CTX *ctx);
2714 // ssl_session_new returns a newly-allocated blank |SSL_SESSION| or nullptr on
2716 UniquePtr<SSL_SESSION> ssl_session_new(const SSL_X509_METHOD *x509_method);
2718 // SSL_SESSION_parse parses an |SSL_SESSION| from |cbs| and advances |cbs| over
2720 UniquePtr<SSL_SESSION> SSL_SESSION_parse(CBS *cbs,
2721 const SSL_X509_METHOD *x509_method,
2722 CRYPTO_BUFFER_POOL *pool);
2724 // ssl_session_serialize writes |in| to |cbb| as if it were serialising a
2725 // session for Session-ID resumption. It returns one on success and zero on
2727 int ssl_session_serialize(const SSL_SESSION *in, CBB *cbb);
2729 // ssl_session_is_context_valid returns one if |session|'s session ID context
2730 // matches the one set on |ssl| and zero otherwise.
2731 int ssl_session_is_context_valid(const SSL *ssl, const SSL_SESSION *session);
2733 // ssl_session_is_time_valid returns one if |session| is still valid and zero if
2735 int ssl_session_is_time_valid(const SSL *ssl, const SSL_SESSION *session);
2737 // ssl_session_is_resumable returns one if |session| is resumable for |hs| and
2739 int ssl_session_is_resumable(const SSL_HANDSHAKE *hs,
2740 const SSL_SESSION *session);
2742 // ssl_session_protocol_version returns the protocol version associated with
2743 // |session|. Note that despite the name, this is not the same as
2744 // |SSL_SESSION_get_protocol_version|. The latter is based on upstream's name.
2745 uint16_t ssl_session_protocol_version(const SSL_SESSION *session);
2747 // ssl_session_get_digest returns the digest used in |session|.
2748 const EVP_MD *ssl_session_get_digest(const SSL_SESSION *session);
2750 void ssl_set_session(SSL *ssl, SSL_SESSION *session);
2752 // ssl_get_prev_session looks up the previous session based on |client_hello|.
2753 // On success, it sets |*out_session| to the session or nullptr if none was
2754 // found. If the session could not be looked up synchronously, it returns
2755 // |ssl_hs_pending_session| and should be called again. If a ticket could not be
2756 // decrypted immediately it returns |ssl_hs_pending_ticket| and should also
2757 // be called again. Otherwise, it returns |ssl_hs_error|.
2758 enum ssl_hs_wait_t ssl_get_prev_session(SSL *ssl,
2759 UniquePtr<SSL_SESSION> *out_session,
2760 bool *out_tickets_supported,
2761 bool *out_renew_ticket,
2762 const SSL_CLIENT_HELLO *client_hello);
2764 // The following flags determine which parts of the session are duplicated.
2765 #define SSL_SESSION_DUP_AUTH_ONLY 0x0
2766 #define SSL_SESSION_INCLUDE_TICKET 0x1
2767 #define SSL_SESSION_INCLUDE_NONAUTH 0x2
2768 #define SSL_SESSION_DUP_ALL \
2769 (SSL_SESSION_INCLUDE_TICKET | SSL_SESSION_INCLUDE_NONAUTH)
2771 // SSL_SESSION_dup returns a newly-allocated |SSL_SESSION| with a copy of the
2772 // fields in |session| or nullptr on error. The new session is non-resumable and
2773 // must be explicitly marked resumable once it has been filled in.
2774 OPENSSL_EXPORT UniquePtr<SSL_SESSION> SSL_SESSION_dup(SSL_SESSION *session,
2777 // ssl_session_rebase_time updates |session|'s start time to the current time,
2778 // adjusting the timeout so the expiration time is unchanged.
2779 void ssl_session_rebase_time(SSL *ssl, SSL_SESSION *session);
2781 // ssl_session_renew_timeout calls |ssl_session_rebase_time| and renews
2782 // |session|'s timeout to |timeout| (measured from the current time). The
2783 // renewal is clamped to the session's auth_timeout.
2784 void ssl_session_renew_timeout(SSL *ssl, SSL_SESSION *session,
2787 void ssl_cipher_preference_list_free(
2788 struct ssl_cipher_preference_list_st *cipher_list);
2790 // ssl_get_cipher_preferences returns the cipher preference list for TLS 1.2 and
2792 const struct ssl_cipher_preference_list_st *ssl_get_cipher_preferences(
2795 void ssl_update_cache(SSL_HANDSHAKE *hs, int mode);
2797 int ssl_send_alert(SSL *ssl, int level, int desc);
2798 bool ssl3_get_message(SSL *ssl, SSLMessage *out);
2799 ssl_open_record_t ssl3_open_handshake(SSL *ssl, size_t *out_consumed,
2800 uint8_t *out_alert, Span<uint8_t> in);
2801 void ssl3_next_message(SSL *ssl);
2803 int ssl3_dispatch_alert(SSL *ssl);
2804 ssl_open_record_t ssl3_open_app_data(SSL *ssl, Span<uint8_t> *out,
2805 size_t *out_consumed, uint8_t *out_alert,
2807 ssl_open_record_t ssl3_open_change_cipher_spec(SSL *ssl, size_t *out_consumed,
2810 int ssl3_write_app_data(SSL *ssl, bool *out_needs_handshake, const uint8_t *buf,
2813 bool ssl3_new(SSL *ssl);
2814 void ssl3_free(SSL *ssl);
2816 bool ssl3_init_message(SSL *ssl, CBB *cbb, CBB *body, uint8_t type);
2817 bool ssl3_finish_message(SSL *ssl, CBB *cbb, Array<uint8_t> *out_msg);
2818 bool ssl3_add_message(SSL *ssl, Array<uint8_t> msg);
2819 bool ssl3_add_change_cipher_spec(SSL *ssl);
2820 bool ssl3_add_alert(SSL *ssl, uint8_t level, uint8_t desc);
2821 int ssl3_flush_flight(SSL *ssl);
2823 bool dtls1_init_message(SSL *ssl, CBB *cbb, CBB *body, uint8_t type);
2824 bool dtls1_finish_message(SSL *ssl, CBB *cbb, Array<uint8_t> *out_msg);
2825 bool dtls1_add_message(SSL *ssl, Array<uint8_t> msg);
2826 bool dtls1_add_change_cipher_spec(SSL *ssl);
2827 bool dtls1_add_alert(SSL *ssl, uint8_t level, uint8_t desc);
2828 int dtls1_flush_flight(SSL *ssl);
2830 // ssl_add_message_cbb finishes the handshake message in |cbb| and adds it to
2831 // the pending flight. It returns true on success and false on error.
2832 bool ssl_add_message_cbb(SSL *ssl, CBB *cbb);
2834 // ssl_hash_message incorporates |msg| into the handshake hash. It returns true
2835 // on success and false on allocation failure.
2836 bool ssl_hash_message(SSL_HANDSHAKE *hs, const SSLMessage &msg);
2838 ssl_open_record_t dtls1_open_app_data(SSL *ssl, Span<uint8_t> *out,
2839 size_t *out_consumed, uint8_t *out_alert,
2841 ssl_open_record_t dtls1_open_change_cipher_spec(SSL *ssl, size_t *out_consumed,
2845 int dtls1_write_app_data(SSL *ssl, bool *out_needs_handshake,
2846 const uint8_t *buf, int len);
2848 // dtls1_write_record sends a record. It returns one on success and <= 0 on
2850 int dtls1_write_record(SSL *ssl, int type, const uint8_t *buf, size_t len,
2851 enum dtls1_use_epoch_t use_epoch);
2853 int dtls1_retransmit_outgoing_messages(SSL *ssl);
2854 bool dtls1_parse_fragment(CBS *cbs, struct hm_header_st *out_hdr,
2856 bool dtls1_check_timeout_num(SSL *ssl);
2858 void dtls1_start_timer(SSL *ssl);
2859 void dtls1_stop_timer(SSL *ssl);
2860 bool dtls1_is_timer_expired(SSL *ssl);
2861 unsigned int dtls1_min_mtu(void);
2863 bool dtls1_new(SSL *ssl);
2864 void dtls1_free(SSL *ssl);
2866 bool dtls1_get_message(SSL *ssl, SSLMessage *out);
2867 ssl_open_record_t dtls1_open_handshake(SSL *ssl, size_t *out_consumed,
2868 uint8_t *out_alert, Span<uint8_t> in);
2869 void dtls1_next_message(SSL *ssl);
2870 int dtls1_dispatch_alert(SSL *ssl);
2872 // tls1_configure_aead configures either the read or write direction AEAD (as
2873 // determined by |direction|) using the keys generated by the TLS KDF. The
2874 // |key_block_cache| argument is used to store the generated key block, if
2875 // empty. Otherwise it's assumed that the key block is already contained within
2876 // it. Returns one on success or zero on error.
2877 int tls1_configure_aead(SSL *ssl, evp_aead_direction_t direction,
2878 Array<uint8_t> *key_block_cache,
2879 const SSL_CIPHER *cipher,
2880 Span<const uint8_t> iv_override);
2882 int tls1_change_cipher_state(SSL_HANDSHAKE *hs, evp_aead_direction_t direction);
2883 int tls1_generate_master_secret(SSL_HANDSHAKE *hs, uint8_t *out,
2884 Span<const uint8_t> premaster);
2886 // tls1_get_grouplist returns the locally-configured group preference list.
2887 Span<const uint16_t> tls1_get_grouplist(const SSL *ssl);
2889 // tls1_check_group_id returns one if |group_id| is consistent with
2890 // locally-configured group preferences.
2891 int tls1_check_group_id(const SSL *ssl, uint16_t group_id);
2893 // tls1_get_shared_group sets |*out_group_id| to the first preferred shared
2894 // group between client and server preferences and returns one. If none may be
2895 // found, it returns zero.
2896 int tls1_get_shared_group(SSL_HANDSHAKE *hs, uint16_t *out_group_id);
2898 // tls1_set_curves converts the array of |ncurves| NIDs pointed to by |curves|
2899 // into a newly allocated array of TLS group IDs. On success, the function
2900 // returns one and writes the array to |*out_group_ids| and its size to
2901 // |*out_group_ids_len|. Otherwise, it returns zero.
2902 int tls1_set_curves(uint16_t **out_group_ids, size_t *out_group_ids_len,
2903 const int *curves, size_t ncurves);
2905 // tls1_set_curves_list converts the string of curves pointed to by |curves|
2906 // into a newly allocated array of TLS group IDs. On success, the function
2907 // returns one and writes the array to |*out_group_ids| and its size to
2908 // |*out_group_ids_len|. Otherwise, it returns zero.
2909 int tls1_set_curves_list(uint16_t **out_group_ids, size_t *out_group_ids_len,
2910 const char *curves);
2912 // ssl_add_clienthello_tlsext writes ClientHello extensions to |out|. It
2913 // returns one on success and zero on failure. The |header_len| argument is the
2914 // length of the ClientHello written so far and is used to compute the padding
2915 // length. (It does not include the record header.)
2916 int ssl_add_clienthello_tlsext(SSL_HANDSHAKE *hs, CBB *out, size_t header_len);
2918 int ssl_add_serverhello_tlsext(SSL_HANDSHAKE *hs, CBB *out);
2919 int ssl_parse_clienthello_tlsext(SSL_HANDSHAKE *hs,
2920 const SSL_CLIENT_HELLO *client_hello);
2921 int ssl_parse_serverhello_tlsext(SSL_HANDSHAKE *hs, CBS *cbs);
2923 #define tlsext_tick_md EVP_sha256
2925 // ssl_process_ticket processes a session ticket from the client. It returns
2927 // |ssl_ticket_aead_success|: |*out_session| is set to the parsed session and
2928 // |*out_renew_ticket| is set to whether the ticket should be renewed.
2929 // |ssl_ticket_aead_ignore_ticket|: |*out_renew_ticket| is set to whether a
2930 // fresh ticket should be sent, but the given ticket cannot be used.
2931 // |ssl_ticket_aead_retry|: the ticket could not be immediately decrypted.
2933 // |ssl_ticket_aead_error|: an error occured that is fatal to the connection.
2934 enum ssl_ticket_aead_result_t ssl_process_ticket(
2935 SSL *ssl, UniquePtr<SSL_SESSION> *out_session, bool *out_renew_ticket,
2936 const uint8_t *ticket, size_t ticket_len, const uint8_t *session_id,
2937 size_t session_id_len);
2939 // tls1_verify_channel_id processes |msg| as a Channel ID message, and verifies
2940 // the signature. If the key is valid, it saves the Channel ID and returns
2941 // one. Otherwise, it returns zero.
2942 int tls1_verify_channel_id(SSL_HANDSHAKE *hs, const SSLMessage &msg);
2944 // tls1_write_channel_id generates a Channel ID message and puts the output in
2945 // |cbb|. |ssl->tlsext_channel_id_private| must already be set before calling.
2946 // This function returns true on success and false on error.
2947 bool tls1_write_channel_id(SSL_HANDSHAKE *hs, CBB *cbb);
2949 // tls1_channel_id_hash computes the hash to be signed by Channel ID and writes
2950 // it to |out|, which must contain at least |EVP_MAX_MD_SIZE| bytes. It returns
2951 // one on success and zero on failure.
2952 int tls1_channel_id_hash(SSL_HANDSHAKE *hs, uint8_t *out, size_t *out_len);
2954 int tls1_record_handshake_hashes_for_channel_id(SSL_HANDSHAKE *hs);
2956 // ssl_do_channel_id_callback checks runs |ssl->ctx->channel_id_cb| if
2957 // necessary. It returns one on success and zero on fatal error. Note that, on
2958 // success, |ssl->tlsext_channel_id_private| may be unset, in which case the
2959 // operation should be retried later.
2960 int ssl_do_channel_id_callback(SSL *ssl);
2962 // ssl_can_write returns one if |ssl| is allowed to write and zero otherwise.
2963 int ssl_can_write(const SSL *ssl);
2965 // ssl_can_read returns one if |ssl| is allowed to read and zero otherwise.
2966 int ssl_can_read(const SSL *ssl);
2968 void ssl_get_current_time(const SSL *ssl, struct OPENSSL_timeval *out_clock);
2969 void ssl_ctx_get_current_time(const SSL_CTX *ctx,
2970 struct OPENSSL_timeval *out_clock);
2972 // ssl_reset_error_state resets state for |SSL_get_error|.
2973 void ssl_reset_error_state(SSL *ssl);
2975 // ssl_set_read_error sets |ssl|'s read half into an error state, saving the
2976 // current state of the error queue.
2977 void ssl_set_read_error(SSL* ssl);
2984 // The following types are exported to C code as public typedefs, so they must
2985 // be defined outside of the namespace.
2987 // ssl_method_st backs the public |SSL_METHOD| type. It is a compatibility
2988 // structure to support the legacy version-locked methods.
2989 struct ssl_method_st {
2990 // version, if non-zero, is the only protocol version acceptable to an
2991 // SSL_CTX initialized from this method.
2993 // method is the underlying SSL_PROTOCOL_METHOD that initializes the
2995 const bssl::SSL_PROTOCOL_METHOD *method;
2996 // x509_method contains pointers to functions that might deal with |X509|
2997 // compatibility, or might be a no-op, depending on the application.
2998 const SSL_X509_METHOD *x509_method;
3001 struct ssl_x509_method_st {
3002 // check_client_CA_list returns one if |names| is a good list of X.509
3003 // distinguished names and zero otherwise. This is used to ensure that we can
3004 // reject unparsable values at handshake time when using crypto/x509.
3005 int (*check_client_CA_list)(STACK_OF(CRYPTO_BUFFER) *names);
3007 // cert_clear frees and NULLs all X509 certificate-related state.
3008 void (*cert_clear)(bssl::CERT *cert);
3009 // cert_free frees all X509-related state.
3010 void (*cert_free)(bssl::CERT *cert);
3011 // cert_flush_cached_chain drops any cached |X509|-based certificate chain
3013 // cert_dup duplicates any needed fields from |cert| to |new_cert|.
3014 void (*cert_dup)(bssl::CERT *new_cert, const bssl::CERT *cert);
3015 void (*cert_flush_cached_chain)(bssl::CERT *cert);
3016 // cert_flush_cached_chain drops any cached |X509|-based leaf certificate
3018 void (*cert_flush_cached_leaf)(bssl::CERT *cert);
3020 // session_cache_objects fills out |sess->x509_peer| and |sess->x509_chain|
3021 // from |sess->certs| and erases |sess->x509_chain_without_leaf|. It returns
3022 // one on success or zero on error.
3023 int (*session_cache_objects)(SSL_SESSION *session);
3024 // session_dup duplicates any needed fields from |session| to |new_session|.
3025 // It returns one on success or zero on error.
3026 int (*session_dup)(SSL_SESSION *new_session, const SSL_SESSION *session);
3027 // session_clear frees any X509-related state from |session|.
3028 void (*session_clear)(SSL_SESSION *session);
3029 // session_verify_cert_chain verifies the certificate chain in |session|,
3030 // sets |session->verify_result| and returns one on success or zero on
3032 int (*session_verify_cert_chain)(SSL_SESSION *session, SSL *ssl,
3033 uint8_t *out_alert);
3035 // hs_flush_cached_ca_names drops any cached |X509_NAME|s from |hs|.
3036 void (*hs_flush_cached_ca_names)(bssl::SSL_HANDSHAKE *hs);
3037 // ssl_new does any neccessary initialisation of |ssl|. It returns one on
3038 // success or zero on error.
3039 int (*ssl_new)(SSL *ssl);
3040 // ssl_free frees anything created by |ssl_new|.
3041 void (*ssl_free)(SSL *ssl);
3042 // ssl_flush_cached_client_CA drops any cached |X509_NAME|s from |ssl|.
3043 void (*ssl_flush_cached_client_CA)(SSL *ssl);
3044 // ssl_auto_chain_if_needed runs the deprecated auto-chaining logic if
3045 // necessary. On success, it updates |ssl|'s certificate configuration as
3046 // needed and returns one. Otherwise, it returns zero.
3047 int (*ssl_auto_chain_if_needed)(SSL *ssl);
3048 // ssl_ctx_new does any neccessary initialisation of |ctx|. It returns one on
3049 // success or zero on error.
3050 int (*ssl_ctx_new)(SSL_CTX *ctx);
3051 // ssl_ctx_free frees anything created by |ssl_ctx_new|.
3052 void (*ssl_ctx_free)(SSL_CTX *ctx);
3053 // ssl_ctx_flush_cached_client_CA drops any cached |X509_NAME|s from |ctx|.
3054 void (*ssl_ctx_flush_cached_client_CA)(SSL_CTX *ssl);
3057 // The following types back public C-exposed types which must live in the global
3058 // namespace. We use subclassing so the implementations may be C++ types with
3059 // methods and destructor without polluting the global namespace.
3060 struct ssl_ctx_st : public bssl::SSLContext {};
3061 struct ssl_st : public bssl::SSLConnection {};
3064 #endif // OPENSSL_HEADER_SSL_INTERNAL_H