internal.h source code [engine/third_party/boringssl/src/ssl/internal.h]

1	/ Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)*
2	* All rights reserved.
3	*
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.
7	*
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).
14	*
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.
21	*
22	* Redistribution and use in source and binary forms, with or without
23	* modification, are permitted provided that the following conditions
24	* are met:
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)"
39	*
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
50	* SUCH DAMAGE.
51	*
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.]
56	*/
57	/ ====================================================================*
58	* Copyright (c) 1998-2007 The OpenSSL Project. All rights reserved.
59	*
60	* Redistribution and use in source and binary forms, with or without
61	* modification, are permitted provided that the following conditions
62	* are met:
63	*
64	* 1. Redistributions of source code must retain the above copyright
65	* notice, this list of conditions and the following disclaimer.
66	*
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
70	* distribution.
71	*
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/)"
76	*
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.
81	*
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.
85	*
86	* 6. Redistributions of any form whatsoever must retain the following
87	* acknowledgment:
88	* "This product includes software developed by the OpenSSL Project
89	* for use in the OpenSSL Toolkit (http://www.openssl.org/)"
90	*
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	* ====================================================================
104	*
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).
108	*
109	*/
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.
114	*/
115	/ ====================================================================*
116	* Copyright 2005 Nokia. All rights reserved.
117	*
118	* The portions of the attached software ("Contribution") is developed by
119	* Nokia Corporation and is licensed pursuant to the OpenSSL open source
120	* license.
121	*
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.
125	*
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.
129	*
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.
134	*
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
139	* OTHERWISE.
140	*/
141
142	#ifndef OPENSSL_HEADER_SSL_INTERNAL_H
143	#define OPENSSL_HEADER_SSL_INTERNAL_H
144
145	#include <openssl/base.h>
146
147	#include <stdlib.h>
148
149	#include <limits>
150	#include <new>
151	#include <type_traits>
152	#include <utility>
153
154	#include <openssl/aead.h>
155	#include <openssl/err.h>
156	#include <openssl/lhash.h>
157	#include <openssl/mem.h>
158	#include <openssl/span.h>
159	#include <openssl/ssl.h>
160	#include <openssl/stack.h>
161
162	#include "../crypto/err/internal.h"
163	#include "../crypto/internal.h"
164
165
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))
171	#else
172	#include <sys/time.h>
173	#endif
174
175
176	BSSL_NAMESPACE_BEGIN
177
178	struct SSL_CONFIG;
179	struct SSL_HANDSHAKE;
180	struct SSL_PROTOCOL_METHOD;
181	struct SSL_X509_METHOD;
182
183	// C++ utilities.
184
185	// New behaves like \|new\| but uses \|OPENSSL_malloc\| for memory allocation. It
186	// returns nullptr on allocation error. It only implements single-object
187	// allocation and not new T[n].
188	//
189	// Note: unlike \|new\|, this does not support non-public constructors.
190	template <typename T, typename... Args>
191	T *New(Args &&... args) {
192	void t = OPENSSL_malloc(sizeof*(T));
193	if (t == nullptr) {
194	OPENSSL_PUT_ERROR(SSL, ERR_R_MALLOC_FAILURE);
195	return nullptr;
196	}
197	return new (t) T(std::forward<Args>(args)...);
198	}
199
200	// Delete behaves like \|delete\| but uses \|OPENSSL_free\| to release memory.
201	//
202	// Note: unlike \|delete\| this does not support non-public destructors.
203	template <typename T>
204	void Delete(T *t) {
205	if (t != nullptr) {
206	t->~T();
207	OPENSSL_free(t);
208	}
209	}
210
211	// All types with kAllowUniquePtr set may be used with UniquePtr. Other types
212	// may be C structs which require a \|BORINGSSL_MAKE_DELETER\| registration.
213	namespace internal {
214	template <typename T>
215	struct DeleterImpl<T, typename std::enable_if<T::kAllowUniquePtr>::type> {
216	static void Free(T *t) { Delete(t); }
217	};
218	} // namespace internal
219
220	// MakeUnique behaves like \|std::make_unique\| but returns nullptr on allocation
221	// error.
222	template <typename T, typename... Args>
223	UniquePtr<T> MakeUnique(Args &&... args) {
224	return UniquePtr<T>(New<T>(std::forward<Args>(args)...));
225	}
226
227	#if defined(BORINGSSL_ALLOW_CXX_RUNTIME)
228	#define HAS_VIRTUAL_DESTRUCTOR
229	#define PURE_VIRTUAL = 0
230	#else
231	// HAS_VIRTUAL_DESTRUCTOR should be declared in any base class which defines a
232	// virtual destructor. This avoids a dependency on \|_ZdlPv\| and prevents the
233	// class from being used with \|delete\|.
234	#define HAS_VIRTUAL_DESTRUCTOR \
235	void operator delete(void *) { abort(); }
236
237	// PURE_VIRTUAL should be used instead of = 0 when defining pure-virtual
238	// functions. This avoids a dependency on \|__cxa_pure_virtual\| but loses
239	// compile-time checking.
240	#define PURE_VIRTUAL \
241	{ abort(); }
242	#endif
243
244	// CONSTEXPR_ARRAY works around a VS 2015 bug where ranged for loops don't work
245	// on constexpr arrays.
246	#if defined(_MSC_VER) && !defined(__clang__) && _MSC_VER < 1910
247	#define CONSTEXPR_ARRAY const
248	#else
249	#define CONSTEXPR_ARRAY constexpr
250	#endif
251
252	// Array<T> is an owning array of elements of \|T\|.
253	template <typename T>
254	class Array {
255	public:
256	// Array's default constructor creates an empty array.
257	Array() {}
258	Array(const Array &) = delete;
259	Array(Array &&other) { *this = std::move(other); }
260
261	~Array() { Reset(); }
262
263	Array &operator=(const Array &) = delete;
264	Array &operator=(Array &&other) {
265	Reset();
266	other.Release(&data_, &size_);
267	return *this;
268	}
269
270	const T data() const* { return data_; }
271	T data() { return* data_; }
272	size_t size() const { return size_; }
273	bool empty() const { return size_ == `0`; }
274
275	const T &operator[](size_t i) const { return data_[i]; }
276	T &operator[](size_t i) { return data_[i]; }
277
278	T begin() { return* data_; }
279	const T cbegin() const* { return data_; }
280	T end() { return* data_ + size_; }
281	const T cend() const* { return data_ + size_; }
282
283	void Reset() { Reset(nullptr, `0`); }
284
285	// Reset releases the current contents of the array and takes ownership of the
286	// raw pointer supplied by the caller.
287	void Reset(T *new_data, size_t new_size) {
288	for (size_t i = `0`; i < size_; i++) {
289	data_[i].~T();
290	}
291	OPENSSL_free(data_);
292	data_ = new_data;
293	size_ = new_size;
294	}
295
296	// Release releases ownership of the array to a raw pointer supplied by the
297	// caller.
298	void Release(T *out, size_t out_size) {
299	*out = data_;
300	*out_size = size_;
301	data_ = nullptr;
302	size_ = `0`;
303	}
304
305	// Init replaces the array with a newly-allocated array of \|new_size\|
306	// default-constructed copies of \|T\|. It returns true on success and false on
307	// error.
308	//
309	// Note that if \|T\| is a primitive type like \|uint8_t\|, it is uninitialized.
310	bool Init(size_t new_size) {
311	Reset();
312	if (new_size == `0`) {
313	return true;
314	}
315
316	if (new_size > std::numeric_limits<size_t>::max() / sizeof(T)) {
317	OPENSSL_PUT_ERROR(SSL, ERR_R_OVERFLOW);
318	return false;
319	}
320	data_ = reinterpret_cast<T >(OPENSSL_malloc(new_size sizeof(T)));
321	if (data_ == nullptr) {
322	OPENSSL_PUT_ERROR(SSL, ERR_R_MALLOC_FAILURE);
323	return false;
324	}
325	size_ = new_size;
326	for (size_t i = `0`; i < size_; i++) {
327	new (&data_[i]) T;
328	}
329	return true;
330	}
331
332	// CopyFrom replaces the array with a newly-allocated copy of \|in\|. It returns
333	// true on success and false on error.
334	bool CopyFrom(Span<const T> in) {
335	if (!Init(in.size())) {
336	return false;
337	}
338	OPENSSL_memcpy(data_, in.data(), sizeof(T) * in.size());
339	return true;
340	}
341
342	// Shrink shrinks the stored size of the array to \|new_size\|. It crashes if
343	// the new size is larger. Note this does not shrink the allocation itself.
344	void Shrink(size_t new_size) {
345	if (new_size > size_) {
346	abort();
347	}
348	size_ = new_size;
349	}
350
351	private:
352	T data_ = nullptr*;
353	size_t size_ = `0`;
354	};
355
356	// CBBFinishArray behaves like \|CBB_finish\| but stores the result in an Array.
357	OPENSSL_EXPORT bool CBBFinishArray(CBB cbb, Array<uint8_t> out);
358
359
360	// Protocol versions.
361	//
362	// Due to DTLS's historical wire version differences, we maintain two notions of
363	// version.
364	//
365	// The "version" or "wire version" is the actual 16-bit value that appears on
366	// the wire. It uniquely identifies a version and is also used at API
367	// boundaries. The set of supported versions differs between TLS and DTLS. Wire
368	// versions are opaque values and may not be compared numerically.
369	//
370	// The "protocol version" identifies the high-level handshake variant being
371	// used. DTLS versions map to the corresponding TLS versions. Protocol versions
372	// are sequential and may be compared numerically.
373
374	// ssl_protocol_version_from_wire sets \|out\| to the protocol version*
375	// corresponding to wire version \|version\| and returns true. If \|version\| is not
376	// a valid TLS or DTLS version, it returns false.
377	//
378	// Note this simultaneously handles both DTLS and TLS. Use one of the
379	// higher-level functions below for most operations.
380	bool ssl_protocol_version_from_wire(uint16_t *out, uint16_t version);
381
382	// ssl_get_version_range sets \|out_min_version\| and \|out_max_version\| to the
383	// minimum and maximum enabled protocol versions, respectively.
384	bool ssl_get_version_range(const SSL_HANDSHAKE hs, uint16_t out_min_version,
385	uint16_t *out_max_version);
386
387	// ssl_supports_version returns whether \|hs\| supports \|version\|.
388	bool ssl_supports_version(SSL_HANDSHAKE *hs, uint16_t version);
389
390	// ssl_method_supports_version returns whether \|method\| supports \|version\|.
391	bool ssl_method_supports_version(const SSL_PROTOCOL_METHOD *method,
392	uint16_t version);
393
394	// ssl_add_supported_versions writes the supported versions of \|hs\| to \|cbb\|, in
395	// decreasing preference order.
396	bool ssl_add_supported_versions(SSL_HANDSHAKE hs, CBB cbb);
397
398	// ssl_negotiate_version negotiates a common version based on \|hs\|'s preferences
399	// and the peer preference list in \|peer_versions\|. On success, it returns true
400	// and sets \|out_version\| to the selected version. Otherwise, it returns false*
401	// and sets \|out_alert\| to an alert to send.*
402	bool ssl_negotiate_version(SSL_HANDSHAKE hs, uint8_t out_alert,
403	uint16_t out_version, const* CBS *peer_versions);
404
405	// ssl_protocol_version returns \|ssl\|'s protocol version. It is an error to
406	// call this function before the version is determined.
407	uint16_t ssl_protocol_version(const SSL *ssl);
408
409	// Cipher suites.
410
411	BSSL_NAMESPACE_END
412
413	struct ssl_cipher_st {
414	// name is the OpenSSL name for the cipher.
415	const char *name;
416	// standard_name is the IETF name for the cipher.
417	const char *standard_name;
418	// id is the cipher suite value bitwise OR-d with 0x03000000.
419	uint32_t id;
420
421	// algorithm_ determine the cipher suite. See constants below for the values.*
422	uint32_t algorithm_mkey;
423	uint32_t algorithm_auth;
424	uint32_t algorithm_enc;
425	uint32_t algorithm_mac;
426	uint32_t algorithm_prf;
427	};
428
429	BSSL_NAMESPACE_BEGIN
430
431	// Bits for \|algorithm_mkey\| (key exchange algorithm).
432	#define SSL_kRSA 0x00000001u
433	#define SSL_kECDHE 0x00000002u
434	// SSL_kPSK is only set for plain PSK, not ECDHE_PSK.
435	#define SSL_kPSK 0x00000004u
436	#define SSL_kGENERIC 0x00000008u
437
438	// Bits for \|algorithm_auth\| (server authentication).
439	#define SSL_aRSA 0x00000001u
440	#define SSL_aECDSA 0x00000002u
441	// SSL_aPSK is set for both PSK and ECDHE_PSK.
442	#define SSL_aPSK 0x00000004u
443	#define SSL_aGENERIC 0x00000008u
444
445	#define SSL_aCERT (SSL_aRSA \| SSL_aECDSA)
446
447	// Bits for \|algorithm_enc\| (symmetric encryption).
448	#define SSL_3DES 0x00000001u
449	#define SSL_AES128 0x00000002u
450	#define SSL_AES256 0x00000004u
451	#define SSL_AES128GCM 0x00000008u
452	#define SSL_AES256GCM 0x00000010u
453	#define SSL_eNULL 0x00000020u
454	#define SSL_CHACHA20POLY1305 0x00000040u
455
456	#define SSL_AES (SSL_AES128 \| SSL_AES256 \| SSL_AES128GCM \| SSL_AES256GCM)
457
458	// Bits for \|algorithm_mac\| (symmetric authentication).
459	#define SSL_SHA1 0x00000001u
460	// SSL_AEAD is set for all AEADs.
461	#define SSL_AEAD 0x00000002u
462
463	// Bits for \|algorithm_prf\| (handshake digest).
464	#define SSL_HANDSHAKE_MAC_DEFAULT 0x1
465	#define SSL_HANDSHAKE_MAC_SHA256 0x2
466	#define SSL_HANDSHAKE_MAC_SHA384 0x4
467
468	// An SSLCipherPreferenceList contains a list of SSL_CIPHERs with equal-
469	// preference groups. For TLS clients, the groups are moot because the server
470	// picks the cipher and groups cannot be expressed on the wire. However, for
471	// servers, the equal-preference groups allow the client's preferences to be
472	// partially respected. (This only has an effect with
473	// SSL_OP_CIPHER_SERVER_PREFERENCE).
474	//
475	// The equal-preference groups are expressed by grouping SSL_CIPHERs together.
476	// All elements of a group have the same priority: no ordering is expressed
477	// within a group.
478	//
479	// The values in \|ciphers\| are in one-to-one correspondence with
480	// \|in_group_flags\|. (That is, sk_SSL_CIPHER_num(ciphers) is the number of
481	// bytes in \|in_group_flags\|.) The bytes in \|in_group_flags\| are either 1, to
482	// indicate that the corresponding SSL_CIPHER is not the last element of a
483	// group, or 0 to indicate that it is.
484	//
485	// For example, if \|in_group_flags\| contains all zeros then that indicates a
486	// traditional, fully-ordered preference. Every SSL_CIPHER is the last element
487	// of the group (i.e. they are all in a one-element group).
488	//
489	// For a more complex example, consider:
490	// ciphers: A B C D E F
491	// in_group_flags: 1 1 0 0 1 0
492	//
493	// That would express the following, order:
494	//
495	// A E
496	// B -> D -> F
497	// C
498	struct SSLCipherPreferenceList {
499	static constexpr bool kAllowUniquePtr = true;
500
501	SSLCipherPreferenceList() = default;
502	~SSLCipherPreferenceList();
503
504	bool Init(UniquePtr<STACK_OF(SSL_CIPHER)> ciphers,
505	Span<const bool> in_group_flags);
506	bool Init(const SSLCipherPreferenceList &);
507
508	void Remove(const SSL_CIPHER *cipher);
509
510	UniquePtr<STACK_OF(SSL_CIPHER)> ciphers;
511	bool in_group_flags = nullptr*;
512	};
513
514	// AllCiphers returns an array of all supported ciphers, sorted by id.
515	Span<const SSL_CIPHER> AllCiphers();
516
517	// ssl_cipher_get_evp_aead sets \|out_aead\| to point to the correct EVP_AEAD*
518	// object for \|cipher\| protocol version \|version\|. It sets \|out_mac_secret_len\|*
519	// and \|out_fixed_iv_len\| to the MAC key length and fixed IV length,*
520	// respectively. The MAC key length is zero except for legacy block and stream
521	// ciphers. It returns true on success and false on error.
522	bool ssl_cipher_get_evp_aead(const EVP_AEAD **out_aead,
523	size_t *out_mac_secret_len,
524	size_t out_fixed_iv_len, const* SSL_CIPHER *cipher,
525	uint16_t version, bool is_dtls);
526
527	// ssl_get_handshake_digest returns the \|EVP_MD\| corresponding to \|version\| and
528	// \|cipher\|.
529	const EVP_MD *ssl_get_handshake_digest(uint16_t version,
530	const SSL_CIPHER *cipher);
531
532	// ssl_create_cipher_list evaluates \|rule_str\|. It sets \|out_cipher_list\| to a*
533	// newly-allocated \|SSLCipherPreferenceList\| containing the result. It returns
534	// true on success and false on failure. If \|strict\| is true, nonsense will be
535	// rejected. If false, nonsense will be silently ignored. An empty result is
536	// considered an error regardless of \|strict\|.
537	bool ssl_create_cipher_list(UniquePtr<SSLCipherPreferenceList> *out_cipher_list,
538	const char rule_str, bool* strict);
539
540	// ssl_cipher_get_value returns the cipher suite id of \|cipher\|.
541	uint16_t ssl_cipher_get_value(const SSL_CIPHER *cipher);
542
543	// ssl_cipher_auth_mask_for_key returns the mask of cipher \|algorithm_auth\|
544	// values suitable for use with \|key\| in TLS 1.2 and below.
545	uint32_t ssl_cipher_auth_mask_for_key(const EVP_PKEY *key);
546
547	// ssl_cipher_uses_certificate_auth returns whether \|cipher\| authenticates the
548	// server and, optionally, the client with a certificate.
549	bool ssl_cipher_uses_certificate_auth(const SSL_CIPHER *cipher);
550
551	// ssl_cipher_requires_server_key_exchange returns whether \|cipher\| requires a
552	// ServerKeyExchange message.
553	//
554	// This function may return false while still allowing \|cipher\| an optional
555	// ServerKeyExchange. This is the case for plain PSK ciphers.
556	bool ssl_cipher_requires_server_key_exchange(const SSL_CIPHER *cipher);
557
558	// ssl_cipher_get_record_split_len, for TLS 1.0 CBC mode ciphers, returns the
559	// length of an encrypted 1-byte record, for use in record-splitting. Otherwise
560	// it returns zero.
561	size_t ssl_cipher_get_record_split_len(const SSL_CIPHER *cipher);
562
563	// ssl_choose_tls13_cipher returns an \|SSL_CIPHER\| corresponding with the best
564	// available from \|cipher_suites\| compatible with \|version\| and \|group_id\|. It
565	// returns NULL if there isn't a compatible cipher.
566	const SSL_CIPHER *ssl_choose_tls13_cipher(CBS cipher_suites, uint16_t version,
567	uint16_t group_id);
568
569
570	// Transcript layer.
571
572	// SSLTranscript maintains the handshake transcript as a combination of a
573	// buffer and running hash.
574	class SSLTranscript {
575	public:
576	SSLTranscript();
577	~SSLTranscript();
578
579	// Init initializes the handshake transcript. If called on an existing
580	// transcript, it resets the transcript and hash. It returns true on success
581	// and false on failure.
582	bool Init();
583
584	// InitHash initializes the handshake hash based on the PRF and contents of
585	// the handshake transcript. Subsequent calls to \|Update\| will update the
586	// rolling hash. It returns one on success and zero on failure. It is an error
587	// to call this function after the handshake buffer is released.
588	bool InitHash(uint16_t version, const SSL_CIPHER *cipher);
589
590	// UpdateForHelloRetryRequest resets the rolling hash with the
591	// HelloRetryRequest construction. It returns true on success and false on
592	// failure. It is an error to call this function before the handshake buffer
593	// is released.
594	bool UpdateForHelloRetryRequest();
595
596	// CopyHashContext copies the hash context into \|ctx\| and returns true on
597	// success.
598	bool CopyHashContext(EVP_MD_CTX *ctx);
599
600	Span<const uint8_t> buffer() {
601	return MakeConstSpan(reinterpret_cast<const uint8_t *>(buffer_->data),
602	buffer_->length);
603	}
604
605	// FreeBuffer releases the handshake buffer. Subsequent calls to
606	// \|Update\| will not update the handshake buffer.
607	void FreeBuffer();
608
609	// DigestLen returns the length of the PRF hash.
610	size_t DigestLen() const;
611
612	// Digest returns the PRF hash. For TLS 1.1 and below, this is
613	// \|EVP_md5_sha1\|.
614	const EVP_MD Digest() const*;
615
616	// Update adds \|in\| to the handshake buffer and handshake hash, whichever is
617	// enabled. It returns true on success and false on failure.
618	bool Update(Span<const uint8_t> in);
619
620	// GetHash writes the handshake hash to \|out\| which must have room for at
621	// least \|DigestLen\| bytes. On success, it returns true and sets \|out_len\| to*
622	// the number of bytes written. Otherwise, it returns false.
623	bool GetHash(uint8_t out, size_t out_len);
624
625	// GetFinishedMAC computes the MAC for the Finished message into the bytes
626	// pointed by \|out\| and writes the number of bytes to \|out_len\|. \|out\| must*
627	// have room for \|EVP_MAX_MD_SIZE\| bytes. It returns true on success and false
628	// on failure.
629	bool GetFinishedMAC(uint8_t out, size_t out_len, const SSL_SESSION *session,
630	bool from_server);
631
632	private:
633	// buffer_, if non-null, contains the handshake transcript.
634	UniquePtr<BUF_MEM> buffer_;
635	// hash, if initialized with an \|EVP_MD\|, maintains the handshake hash.
636	ScopedEVP_MD_CTX hash_;
637	};
638
639	// tls1_prf computes the PRF function for \|ssl\|. It fills \|out\|, using \|secret\|
640	// as the secret and \|label\| as the label. \|seed1\| and \|seed2\| are concatenated
641	// to form the seed parameter. It returns true on success and false on failure.
642	bool tls1_prf(const EVP_MD *digest, Span<uint8_t> out,
643	Span<const uint8_t> secret, Span<const char> label,
644	Span<const uint8_t> seed1, Span<const uint8_t> seed2);
645
646
647	// Encryption layer.
648
649	// SSLAEADContext contains information about an AEAD that is being used to
650	// encrypt an SSL connection.
651	class SSLAEADContext {
652	public:
653	SSLAEADContext(uint16_t version, bool is_dtls, const SSL_CIPHER *cipher);
654	~SSLAEADContext();
655	static constexpr bool kAllowUniquePtr = true;
656
657	SSLAEADContext(const SSLAEADContext &&) = delete;
658	SSLAEADContext &operator=(const SSLAEADContext &&) = delete;
659
660	// CreateNullCipher creates an \|SSLAEADContext\| for the null cipher.
661	static UniquePtr<SSLAEADContext> CreateNullCipher(bool is_dtls);
662
663	// Create creates an \|SSLAEADContext\| using the supplied key material. It
664	// returns nullptr on error. Only one of \|Open\| or \|Seal\| may be used with the
665	// resulting object, depending on \|direction\|. \|version\| is the normalized
666	// protocol version, so DTLS 1.0 is represented as 0x0301, not 0xffef.
667	static UniquePtr<SSLAEADContext> Create(enum evp_aead_direction_t direction,
668	uint16_t version, bool is_dtls,
669	const SSL_CIPHER *cipher,
670	Span<const uint8_t> enc_key,
671	Span<const uint8_t> mac_key,
672	Span<const uint8_t> fixed_iv);
673
674	// CreatePlaceholderForQUIC creates a placeholder \|SSLAEADContext\| for the
675	// given cipher and version. The resulting object can be queried for various
676	// properties but cannot encrypt or decrypt data.
677	static UniquePtr<SSLAEADContext> CreatePlaceholderForQUIC(
678	uint16_t version, const SSL_CIPHER *cipher);
679
680	// SetVersionIfNullCipher sets the version the SSLAEADContext for the null
681	// cipher, to make version-specific determinations in the record layer prior
682	// to a cipher being selected.
683	void SetVersionIfNullCipher(uint16_t version);
684
685	// ProtocolVersion returns the protocol version associated with this
686	// SSLAEADContext. It can only be called once \|version_\| has been set to a
687	// valid value.
688	uint16_t ProtocolVersion() const;
689
690	// RecordVersion returns the record version that should be used with this
691	// SSLAEADContext for record construction and crypto.
692	uint16_t RecordVersion() const;
693
694	const SSL_CIPHER cipher() const* { return cipher_; }
695
696	// is_null_cipher returns true if this is the null cipher.
697	bool is_null_cipher() const { return !cipher_; }
698
699	// ExplicitNonceLen returns the length of the explicit nonce.
700	size_t ExplicitNonceLen() const;
701
702	// MaxOverhead returns the maximum overhead of calling \|Seal\|.
703	size_t MaxOverhead() const;
704
705	// SuffixLen calculates the suffix length written by \|SealScatter\| and writes
706	// it to \|out_suffix_len\|. It returns true on success and false on error.*
707	// \|in_len\| and \|extra_in_len\| should equal the argument of the same names
708	// passed to \|SealScatter\|.
709	bool SuffixLen(size_t *out_suffix_len, size_t in_len,
710	size_t extra_in_len) const;
711
712	// CiphertextLen calculates the total ciphertext length written by
713	// \|SealScatter\| and writes it to \|out_len\|. It returns true on success and*
714	// false on error. \|in_len\| and \|extra_in_len\| should equal the argument of
715	// the same names passed to \|SealScatter\|.
716	bool CiphertextLen(size_t out_len, size_t in_len, size_t extra_in_len) const*;
717
718	// Open authenticates and decrypts \|in\| in-place. On success, it sets \|out\|*
719	// to the plaintext in \|in\| and returns true. Otherwise, it returns
720	// false. The output will always be \|ExplicitNonceLen\| bytes ahead of \|in\|.
721	bool Open(Span<uint8_t> *out, uint8_t type, uint16_t record_version,
722	const uint8_t seqnum[`8`], Span<const uint8_t> header,
723	Span<uint8_t> in);
724
725	// Seal encrypts and authenticates \|in_len\| bytes from \|in\| and writes the
726	// result to \|out\|. It returns true on success and false on error.
727	//
728	// If \|in\| and \|out\| alias then \|out\| + \|ExplicitNonceLen\| must be == \|in\|.
729	bool Seal(uint8_t out, size_t out_len, size_t max_out, uint8_t type,
730	uint16_t record_version, const uint8_t seqnum[`8`],
731	Span<const uint8_t> header, const uint8_t *in, size_t in_len);
732
733	// SealScatter encrypts and authenticates \|in_len\| bytes from \|in\| and splits
734	// the result between \|out_prefix\|, \|out\| and \|out_suffix\|. It returns one on
735	// success and zero on error.
736	//
737	// On successful return, exactly \|ExplicitNonceLen\| bytes are written to
738	// \|out_prefix\|, \|in_len\| bytes to \|out\|, and \|SuffixLen\| bytes to
739	// \|out_suffix\|.
740	//
741	// \|extra_in\| may point to an additional plaintext buffer. If present,
742	// \|extra_in_len\| additional bytes are encrypted and authenticated, and the
743	// ciphertext is written to the beginning of \|out_suffix\|. \|SuffixLen\| should
744	// be used to size \|out_suffix\| accordingly.
745	//
746	// If \|in\| and \|out\| alias then \|out\| must be == \|in\|. Other arguments may not
747	// alias anything.
748	bool SealScatter(uint8_t out_prefix, uint8_t out, uint8_t *out_suffix,
749	uint8_t type, uint16_t record_version,
750	const uint8_t seqnum[`8`], Span<const uint8_t> header,
751	const uint8_t in, size_t in_len, const* uint8_t *extra_in,
752	size_t extra_in_len);
753
754	bool GetIV(const uint8_t *out_iv, size_t out_iv_len) const;
755
756	private:
757	// GetAdditionalData returns the additional data, writing into \|storage\| if
758	// necessary.
759	Span<const uint8_t> GetAdditionalData(uint8_t storage[`13`], uint8_t type,
760	uint16_t record_version,
761	const uint8_t seqnum[`8`],
762	size_t plaintext_len,
763	Span<const uint8_t> header);
764
765	const SSL_CIPHER *cipher_;
766	ScopedEVP_AEAD_CTX ctx_;
767	// fixed_nonce_ contains any bytes of the nonce that are fixed for all
768	// records.
769	uint8_t fixed_nonce_[`12`];
770	uint8_t fixed_nonce_len_ = `0`, variable_nonce_len_ = `0`;
771	// version_ is the wire version that should be used with this AEAD.
772	uint16_t version_;
773	// is_dtls_ is whether DTLS is being used with this AEAD.
774	bool is_dtls_;
775	// variable_nonce_included_in_record_ is true if the variable nonce
776	// for a record is included as a prefix before the ciphertext.
777	bool variable_nonce_included_in_record_ : `1`;
778	// random_variable_nonce_ is true if the variable nonce is
779	// randomly generated, rather than derived from the sequence
780	// number.
781	bool random_variable_nonce_ : `1`;
782	// xor_fixed_nonce_ is true if the fixed nonce should be XOR'd into the
783	// variable nonce rather than prepended.
784	bool xor_fixed_nonce_ : `1`;
785	// omit_length_in_ad_ is true if the length should be omitted in the
786	// AEAD's ad parameter.
787	bool omit_length_in_ad_ : `1`;
788	// ad_is_header_ is true if the AEAD's ad parameter is the record header.
789	bool ad_is_header_ : `1`;
790	};
791
792
793	// DTLS replay bitmap.
794
795	// DTLS1_BITMAP maintains a sliding window of 64 sequence numbers to detect
796	// replayed packets. It should be initialized by zeroing every field.
797	struct DTLS1_BITMAP {
798	// map is a bit mask of the last 64 sequence numbers. Bit
799	// \|1<<i\| corresponds to \|max_seq_num - i\|.
800	uint64_t map = `0`;
801	// max_seq_num is the largest sequence number seen so far as a 64-bit
802	// integer.
803	uint64_t max_seq_num = `0`;
804	};
805
806
807	// Record layer.
808
809	// ssl_record_sequence_update increments the sequence number in \|seq\|. It
810	// returns true on success and false on wraparound.
811	bool ssl_record_sequence_update(uint8_t *seq, size_t seq_len);
812
813	// ssl_record_prefix_len returns the length of the prefix before the ciphertext
814	// of a record for \|ssl\|.
815	//
816	// TODO(davidben): Expose this as part of public API once the high-level
817	// buffer-free APIs are available.
818	size_t ssl_record_prefix_len(const SSL *ssl);
819
820	enum ssl_open_record_t {
821	ssl_open_record_success,
822	ssl_open_record_discard,
823	ssl_open_record_partial,
824	ssl_open_record_close_notify,
825	ssl_open_record_error,
826	};
827
828	// tls_open_record decrypts a record from \|in\| in-place.
829	//
830	// If the input did not contain a complete record, it returns
831	// \|ssl_open_record_partial\|. It sets \|out_consumed\| to the total number of*
832	// bytes necessary. It is guaranteed that a successful call to \|tls_open_record\|
833	// will consume at least that many bytes.
834	//
835	// Otherwise, it sets \|out_consumed\| to the number of bytes of input*
836	// consumed. Note that input may be consumed on all return codes if a record was
837	// decrypted.
838	//
839	// On success, it returns \|ssl_open_record_success\|. It sets \|out_type\| to the*
840	// record type and \|out\| to the record body in \|in\|. Note that \|out\| may be
841	// empty.
842	//
843	// If a record was successfully processed but should be discarded, it returns
844	// \|ssl_open_record_discard\|.
845	//
846	// If a record was successfully processed but is a close_notify, it returns
847	// \|ssl_open_record_close_notify\|.
848	//
849	// On failure or fatal alert, it returns \|ssl_open_record_error\| and sets
850	// \|out_alert\| to an alert to emit, or zero if no alert should be emitted.*
851	enum ssl_open_record_t tls_open_record(SSL ssl, uint8_t out_type,
852	Span<uint8_t> out, size_t out_consumed,
853	uint8_t *out_alert, Span<uint8_t> in);
854
855	// dtls_open_record implements \|tls_open_record\| for DTLS. It only returns
856	// \|ssl_open_record_partial\| if \|in\| was empty and sets \|out_consumed\| to*
857	// zero. The caller should read one packet and try again.
858	enum ssl_open_record_t dtls_open_record(SSL ssl, uint8_t out_type,
859	Span<uint8_t> *out,
860	size_t *out_consumed,
861	uint8_t *out_alert, Span<uint8_t> in);
862
863	// ssl_seal_align_prefix_len returns the length of the prefix before the start
864	// of the bulk of the ciphertext when sealing a record with \|ssl\|. Callers may
865	// use this to align buffers.
866	//
867	// Note when TLS 1.0 CBC record-splitting is enabled, this includes the one byte
868	// record and is the offset into second record's ciphertext. Thus sealing a
869	// small record may result in a smaller output than this value.
870	//
871	// TODO(davidben): Is this alignment valuable? Record-splitting makes this a
872	// mess.
873	size_t ssl_seal_align_prefix_len(const SSL *ssl);
874
875	// tls_seal_record seals a new record of type \|type\| and body \|in\| and writes it
876	// to \|out\|. At most \|max_out\| bytes will be written. It returns true on success
877	// and false on error. If enabled, \|tls_seal_record\| implements TLS 1.0 CBC
878	// 1/n-1 record splitting and may write two records concatenated.
879	//
880	// For a large record, the bulk of the ciphertext will begin
881	// \|ssl_seal_align_prefix_len\| bytes into out. Aligning \|out\| appropriately may
882	// improve performance. It writes at most \|in_len\| + \|SSL_max_seal_overhead\|
883	// bytes to \|out\|.
884	//
885	// \|in\| and \|out\| may not alias.
886	bool tls_seal_record(SSL ssl, uint8_t out, size_t *out_len, size_t max_out,
887	uint8_t type, const uint8_t *in, size_t in_len);
888
889	enum dtls1_use_epoch_t {
890	dtls1_use_previous_epoch,
891	dtls1_use_current_epoch,
892	};
893
894	// dtls_max_seal_overhead returns the maximum overhead, in bytes, of sealing a
895	// record.
896	size_t dtls_max_seal_overhead(const SSL ssl, enum* dtls1_use_epoch_t use_epoch);
897
898	// dtls_seal_prefix_len returns the number of bytes of prefix to reserve in
899	// front of the plaintext when sealing a record in-place.
900	size_t dtls_seal_prefix_len(const SSL ssl, enum* dtls1_use_epoch_t use_epoch);
901
902	// dtls_seal_record implements \|tls_seal_record\| for DTLS. \|use_epoch\| selects
903	// which epoch's cipher state to use. Unlike \|tls_seal_record\|, \|in\| and \|out\|
904	// may alias but, if they do, \|in\| must be exactly \|dtls_seal_prefix_len\| bytes
905	// ahead of \|out\|.
906	bool dtls_seal_record(SSL ssl, uint8_t out, size_t *out_len, size_t max_out,
907	uint8_t type, const uint8_t *in, size_t in_len,
908	enum dtls1_use_epoch_t use_epoch);
909
910	// ssl_process_alert processes \|in\| as an alert and updates \|ssl\|'s shutdown
911	// state. It returns one of \|ssl_open_record_discard\|, \|ssl_open_record_error\|,
912	// \|ssl_open_record_close_notify\|, or \|ssl_open_record_fatal_alert\| as
913	// appropriate.
914	enum ssl_open_record_t ssl_process_alert(SSL ssl, uint8_t out_alert,
915	Span<const uint8_t> in);
916
917
918	// Private key operations.
919
920	// ssl_has_private_key returns whether \|hs\| has a private key configured.
921	bool ssl_has_private_key(const SSL_HANDSHAKE *hs);
922
923	// ssl_private_key_ perform the corresponding operation on*
924	// \|SSL_PRIVATE_KEY_METHOD\|. If there is a custom private key configured, they
925	// call the corresponding function or \|complete\| depending on whether there is a
926	// pending operation. Otherwise, they implement the operation with
927	// \|EVP_PKEY\|.
928
929	enum ssl_private_key_result_t ssl_private_key_sign(
930	SSL_HANDSHAKE hs, uint8_t out, size_t *out_len, size_t max_out,
931	uint16_t sigalg, Span<const uint8_t> in);
932
933	enum ssl_private_key_result_t ssl_private_key_decrypt(SSL_HANDSHAKE *hs,
934	uint8_t *out,
935	size_t *out_len,
936	size_t max_out,
937	Span<const uint8_t> in);
938
939	// ssl_private_key_supports_signature_algorithm returns whether \|hs\|'s private
940	// key supports \|sigalg\|.
941	bool ssl_private_key_supports_signature_algorithm(SSL_HANDSHAKE *hs,
942	uint16_t sigalg);
943
944	// ssl_public_key_verify verifies that the \|signature\| is valid for the public
945	// key \|pkey\| and input \|in\|, using the signature algorithm \|sigalg\|.
946	bool ssl_public_key_verify(SSL ssl, Span<const* uint8_t> signature,
947	uint16_t sigalg, EVP_PKEY *pkey,
948	Span<const uint8_t> in);
949
950
951	// Key shares.
952
953	// SSLKeyShare abstracts over Diffie-Hellman-like key exchanges.
954	class SSLKeyShare {
955	public:
956	virtual ~SSLKeyShare() {}
957	static constexpr bool kAllowUniquePtr = true;
958	HAS_VIRTUAL_DESTRUCTOR
959
960	// Create returns a SSLKeyShare instance for use with group \|group_id\| or
961	// nullptr on error.
962	static UniquePtr<SSLKeyShare> Create(uint16_t group_id);
963
964	// Create deserializes an SSLKeyShare instance previously serialized by
965	// \|Serialize\|.
966	static UniquePtr<SSLKeyShare> Create(CBS *in);
967
968	// GroupID returns the group ID.
969	virtual uint16_t GroupID() const PURE_VIRTUAL;
970
971	// Offer generates a keypair and writes the public value to
972	// \|out_public_key\|. It returns true on success and false on error.
973	virtual bool Offer(CBB *out_public_key) PURE_VIRTUAL;
974
975	// Accept performs a key exchange against the \|peer_key\| generated by \|Offer\|.
976	// On success, it returns true, writes the public value to \|out_public_key\|,
977	// and sets \|out_secret\| to the shared secret. On failure, it returns false*
978	// and sets \|out_alert\| to an alert to send to the peer.*
979	//
980	// The default implementation calls \|Offer\| and then \|Finish\|, assuming a key
981	// exchange protocol where the peers are symmetric.
982	virtual bool Accept(CBB out_public_key, Array<uint8_t> out_secret,
983	uint8_t out_alert, Span<const* uint8_t> peer_key);
984
985	// Finish performs a key exchange against the \|peer_key\| generated by
986	// \|Accept\|. On success, it returns true and sets \|out_secret\| to the shared*
987	// secret. On failure, it returns false and sets \|out_alert\| to an alert to*
988	// send to the peer.
989	virtual bool Finish(Array<uint8_t> out_secret, uint8_t out_alert,
990	Span<const uint8_t> peer_key) PURE_VIRTUAL;
991
992	// Serialize writes the state of the key exchange to \|out\|, returning true if
993	// successful and false otherwise.
994	virtual bool Serialize(CBB out) { return* false; }
995
996	// Deserialize initializes the state of the key exchange from \|in\|, returning
997	// true if successful and false otherwise. It is called by \|Create\|.
998	virtual bool Deserialize(CBS in) { return* false; }
999	};
1000
1001	struct NamedGroup {
1002	int nid;
1003	uint16_t group_id;
1004	const char name[`8`], alias[`11`];
1005	};
1006
1007	// NamedGroups returns all supported groups.
1008	Span<const NamedGroup> NamedGroups();
1009
1010	// ssl_nid_to_group_id looks up the group corresponding to \|nid\|. On success, it
1011	// sets \|out_group_id\| to the group ID and returns true. Otherwise, it returns*
1012	// false.
1013	bool ssl_nid_to_group_id(uint16_t out_group_id, int* nid);
1014
1015	// ssl_name_to_group_id looks up the group corresponding to the \|name\| string of
1016	// length \|len\|. On success, it sets \|out_group_id\| to the group ID and returns*
1017	// true. Otherwise, it returns false.
1018	bool ssl_name_to_group_id(uint16_t out_group_id, const* char *name, size_t len);
1019
1020
1021	// Handshake messages.
1022
1023	struct SSLMessage {
1024	bool is_v2_hello;
1025	uint8_t type;
1026	CBS body;
1027	// raw is the entire serialized handshake message, including the TLS or DTLS
1028	// message header.
1029	CBS raw;
1030	};
1031
1032	// SSL_MAX_HANDSHAKE_FLIGHT is the number of messages, including
1033	// ChangeCipherSpec, in the longest handshake flight. Currently this is the
1034	// client's second leg in a full handshake when client certificates, NPN, and
1035	// Channel ID, are all enabled.
1036	#define SSL_MAX_HANDSHAKE_FLIGHT 7
1037
1038	extern const uint8_t kHelloRetryRequest[SSL3_RANDOM_SIZE];
1039	extern const uint8_t kTLS12DowngradeRandom[`8`];
1040	extern const uint8_t kTLS13DowngradeRandom[`8`];
1041	extern const uint8_t kJDK11DowngradeRandom[`8`];
1042
1043	// ssl_max_handshake_message_len returns the maximum number of bytes permitted
1044	// in a handshake message for \|ssl\|.
1045	size_t ssl_max_handshake_message_len(const SSL *ssl);
1046
1047	// tls_can_accept_handshake_data returns whether \|ssl\| is able to accept more
1048	// data into handshake buffer.
1049	bool tls_can_accept_handshake_data(const SSL ssl, uint8_t out_alert);
1050
1051	// tls_has_unprocessed_handshake_data returns whether there is buffered
1052	// handshake data that has not been consumed by \|get_message\|.
1053	bool tls_has_unprocessed_handshake_data(const SSL *ssl);
1054
1055	// tls_append_handshake_data appends \|data\| to the handshake buffer. It returns
1056	// true on success and false on allocation failure.
1057	bool tls_append_handshake_data(SSL ssl, Span<const* uint8_t> data);
1058
1059	// dtls_has_unprocessed_handshake_data behaves like
1060	// \|tls_has_unprocessed_handshake_data\| for DTLS.
1061	bool dtls_has_unprocessed_handshake_data(const SSL *ssl);
1062
1063	// tls_flush_pending_hs_data flushes any handshake plaintext data.
1064	bool tls_flush_pending_hs_data(SSL *ssl);
1065
1066	struct DTLS_OUTGOING_MESSAGE {
1067	DTLS_OUTGOING_MESSAGE() {}
1068	DTLS_OUTGOING_MESSAGE(const DTLS_OUTGOING_MESSAGE &) = delete;
1069	DTLS_OUTGOING_MESSAGE &operator=(const DTLS_OUTGOING_MESSAGE &) = delete;
1070	~DTLS_OUTGOING_MESSAGE() { Clear(); }
1071
1072	void Clear();
1073
1074	uint8_t data = nullptr*;
1075	uint32_t len = `0`;
1076	uint16_t epoch = `0`;
1077	bool is_ccs = false;
1078	};
1079
1080	// dtls_clear_outgoing_messages releases all buffered outgoing messages.
1081	void dtls_clear_outgoing_messages(SSL *ssl);
1082
1083
1084	// Callbacks.
1085
1086	// ssl_do_info_callback calls \|ssl\|'s info callback, if set.
1087	void ssl_do_info_callback(const SSL ssl, int* type, int value);
1088
1089	// ssl_do_msg_callback calls \|ssl\|'s message callback, if set.
1090	void ssl_do_msg_callback(const SSL ssl, int* is_write, int content_type,
1091	Span<const uint8_t> in);
1092
1093
1094	// Transport buffers.
1095
1096	class SSLBuffer {
1097	public:
1098	SSLBuffer() {}
1099	~SSLBuffer() { Clear(); }
1100
1101	SSLBuffer(const SSLBuffer &) = delete;
1102	SSLBuffer &operator=(const SSLBuffer &) = delete;
1103
1104	uint8_t data() { return* buf_ + offset_; }
1105	size_t size() const { return size_; }
1106	bool empty() const { return size_ == `0`; }
1107	size_t cap() const { return cap_; }
1108
1109	Span<uint8_t> span() { return MakeSpan(data(), size()); }
1110
1111	Span<uint8_t> remaining() {
1112	return MakeSpan(data() + size(), cap() - size());
1113	}
1114
1115	// Clear releases the buffer.
1116	void Clear();
1117
1118	// EnsureCap ensures the buffer has capacity at least \|new_cap\|, aligned such
1119	// that data written after \|header_len\| is aligned to a
1120	// \|SSL3_ALIGN_PAYLOAD\|-byte boundary. It returns true on success and false
1121	// on error.
1122	bool EnsureCap(size_t header_len, size_t new_cap);
1123
1124	// DidWrite extends the buffer by \|len\|. The caller must have filled in to
1125	// this point.
1126	void DidWrite(size_t len);
1127
1128	// Consume consumes \|len\| bytes from the front of the buffer. The memory
1129	// consumed will remain valid until the next call to \|DiscardConsumed\| or
1130	// \|Clear\|.
1131	void Consume(size_t len);
1132
1133	// DiscardConsumed discards the consumed bytes from the buffer. If the buffer
1134	// is now empty, it releases memory used by it.
1135	void DiscardConsumed();
1136
1137	private:
1138	// buf_ is the memory allocated for this buffer.
1139	uint8_t buf_ = nullptr*;
1140	// offset_ is the offset into \|buf_\| which the buffer contents start at.
1141	uint16_t offset_ = `0`;
1142	// size_ is the size of the buffer contents from \|buf_\| + \|offset_\|.
1143	uint16_t size_ = `0`;
1144	// cap_ is how much memory beyond \|buf_\| + \|offset_\| is available.
1145	uint16_t cap_ = `0`;
1146	};
1147
1148	// ssl_read_buffer_extend_to extends the read buffer to the desired length. For
1149	// TLS, it reads to the end of the buffer until the buffer is \|len\| bytes
1150	// long. For DTLS, it reads a new packet and ignores \|len\|. It returns one on
1151	// success, zero on EOF, and a negative number on error.
1152	//
1153	// It is an error to call \|ssl_read_buffer_extend_to\| in DTLS when the buffer is
1154	// non-empty.
1155	int ssl_read_buffer_extend_to(SSL *ssl, size_t len);
1156
1157	// ssl_handle_open_record handles the result of passing \|ssl->s3->read_buffer\|
1158	// to a record-processing function. If \|ret\| is a success or if the caller
1159	// should retry, it returns one and sets \|out_retry\|. Otherwise, it returns <=*
1160	// 0.
1161	int ssl_handle_open_record(SSL ssl, bool* *out_retry, ssl_open_record_t ret,
1162	size_t consumed, uint8_t alert);
1163
1164	// ssl_write_buffer_flush flushes the write buffer to the transport. It returns
1165	// one on success and <= 0 on error. For DTLS, whether or not the write
1166	// succeeds, the write buffer will be cleared.
1167	int ssl_write_buffer_flush(SSL *ssl);
1168
1169
1170	// Certificate functions.
1171
1172	// ssl_has_certificate returns whether a certificate and private key are
1173	// configured.
1174	bool ssl_has_certificate(const SSL_HANDSHAKE *hs);
1175
1176	// ssl_parse_cert_chain parses a certificate list from \|cbs\| in the format used
1177	// by a TLS Certificate message. On success, it advances \|cbs\| and returns
1178	// true. Otherwise, it returns false and sets \|out_alert\| to an alert to send*
1179	// to the peer.
1180	//
1181	// If the list is non-empty then \|out_chain\| and \|out_pubkey\| will be set to
1182	// the certificate chain and the leaf certificate's public key
1183	// respectively. Otherwise, both will be set to nullptr.
1184	//
1185	// If the list is non-empty and \|out_leaf_sha256\| is non-NULL, it writes the
1186	// SHA-256 hash of the leaf to \|out_leaf_sha256\|.
1187	bool ssl_parse_cert_chain(uint8_t *out_alert,
1188	UniquePtr<STACK_OF(CRYPTO_BUFFER)> *out_chain,
1189	UniquePtr<EVP_PKEY> *out_pubkey,
1190	uint8_t out_leaf_sha256, CBS cbs,
1191	CRYPTO_BUFFER_POOL *pool);
1192
1193	// ssl_add_cert_chain adds \|hs->ssl\|'s certificate chain to \|cbb\| in the format
1194	// used by a TLS Certificate message. If there is no certificate chain, it emits
1195	// an empty certificate list. It returns true on success and false on error.
1196	bool ssl_add_cert_chain(SSL_HANDSHAKE hs, CBB cbb);
1197
1198	enum ssl_key_usage_t {
1199	key_usage_digital_signature = `0`,
1200	key_usage_encipherment = `2`,
1201	};
1202
1203	// ssl_cert_check_key_usage parses the DER-encoded, X.509 certificate in \|in\|
1204	// and returns true if doesn't specify a key usage or, if it does, if it
1205	// includes \|bit\|. Otherwise it pushes to the error queue and returns false.
1206	bool ssl_cert_check_key_usage(const CBS in, enum* ssl_key_usage_t bit);
1207
1208	// ssl_cert_parse_pubkey extracts the public key from the DER-encoded, X.509
1209	// certificate in \|in\|. It returns an allocated \|EVP_PKEY\| or else returns
1210	// nullptr and pushes to the error queue.
1211	UniquePtr<EVP_PKEY> ssl_cert_parse_pubkey(const CBS *in);
1212
1213	// ssl_parse_client_CA_list parses a CA list from \|cbs\| in the format used by a
1214	// TLS CertificateRequest message. On success, it returns a newly-allocated
1215	// \|CRYPTO_BUFFER\| list and advances \|cbs\|. Otherwise, it returns nullptr and
1216	// sets \|out_alert\| to an alert to send to the peer.*
1217	UniquePtr<STACK_OF(CRYPTO_BUFFER)> ssl_parse_client_CA_list(SSL *ssl,
1218	uint8_t *out_alert,
1219	CBS *cbs);
1220
1221	// ssl_has_client_CAs returns there are configured CAs.
1222	bool ssl_has_client_CAs(const SSL_CONFIG *cfg);
1223
1224	// ssl_add_client_CA_list adds the configured CA list to \|cbb\| in the format
1225	// used by a TLS CertificateRequest message. It returns true on success and
1226	// false on error.
1227	bool ssl_add_client_CA_list(SSL_HANDSHAKE hs, CBB cbb);
1228
1229	// ssl_check_leaf_certificate returns one if \|pkey\| and \|leaf\| are suitable as
1230	// a server's leaf certificate for \|hs\|. Otherwise, it returns zero and pushes
1231	// an error on the error queue.
1232	bool ssl_check_leaf_certificate(SSL_HANDSHAKE hs, EVP_PKEY pkey,
1233	const CRYPTO_BUFFER *leaf);
1234
1235	// ssl_on_certificate_selected is called once the certificate has been selected.
1236	// It finalizes the certificate and initializes \|hs->local_pubkey\|. It returns
1237	// true on success and false on error.
1238	bool ssl_on_certificate_selected(SSL_HANDSHAKE *hs);
1239
1240
1241	// TLS 1.3 key derivation.
1242
1243	// tls13_init_key_schedule initializes the handshake hash and key derivation
1244	// state, and incorporates the PSK. The cipher suite and PRF hash must have been
1245	// selected at this point. It returns true on success and false on error.
1246	bool tls13_init_key_schedule(SSL_HANDSHAKE hs, const* uint8_t *psk,
1247	size_t psk_len);
1248
1249	// tls13_init_early_key_schedule initializes the handshake hash and key
1250	// derivation state from the resumption secret and incorporates the PSK to
1251	// derive the early secrets. It returns one on success and zero on error.
1252	bool tls13_init_early_key_schedule(SSL_HANDSHAKE hs, const* uint8_t *psk,
1253	size_t psk_len);
1254
1255	// tls13_advance_key_schedule incorporates \|in\| into the key schedule with
1256	// HKDF-Extract. It returns true on success and false on error.
1257	bool tls13_advance_key_schedule(SSL_HANDSHAKE hs, const* uint8_t *in,
1258	size_t len);
1259
1260	// tls13_set_traffic_key sets the read or write traffic keys to
1261	// \|traffic_secret\|. It returns true on success and false on error.
1262	bool tls13_set_traffic_key(SSL ssl, enum* ssl_encryption_level_t level,
1263	enum evp_aead_direction_t direction,
1264	const uint8_t *traffic_secret,
1265	size_t traffic_secret_len);
1266
1267	// tls13_derive_early_secrets derives the early traffic secret. It returns true
1268	// on success and false on error.
1269	bool tls13_derive_early_secrets(SSL_HANDSHAKE *hs);
1270
1271	// tls13_derive_handshake_secrets derives the handshake traffic secret. It
1272	// returns true on success and false on error.
1273	bool tls13_derive_handshake_secrets(SSL_HANDSHAKE *hs);
1274
1275	// tls13_rotate_traffic_key derives the next read or write traffic secret. It
1276	// returns true on success and false on error.
1277	bool tls13_rotate_traffic_key(SSL ssl, enum* evp_aead_direction_t direction);
1278
1279	// tls13_derive_application_secrets derives the initial application data traffic
1280	// and exporter secrets based on the handshake transcripts and \|master_secret\|.
1281	// It returns true on success and false on error.
1282	bool tls13_derive_application_secrets(SSL_HANDSHAKE *hs);
1283
1284	// tls13_derive_resumption_secret derives the \|resumption_secret\|.
1285	bool tls13_derive_resumption_secret(SSL_HANDSHAKE *hs);
1286
1287	// tls13_export_keying_material provides an exporter interface to use the
1288	// \|exporter_secret\|.
1289	bool tls13_export_keying_material(SSL *ssl, Span<uint8_t> out,
1290	Span<const uint8_t> secret,
1291	Span<const char> label,
1292	Span<const uint8_t> context);
1293
1294	// tls13_finished_mac calculates the MAC of the handshake transcript to verify
1295	// the integrity of the Finished message, and stores the result in \|out\| and
1296	// length in \|out_len\|. \|is_server\| is true if this is for the Server Finished
1297	// and false for the Client Finished.
1298	bool tls13_finished_mac(SSL_HANDSHAKE hs, uint8_t out, size_t *out_len,
1299	bool is_server);
1300
1301	// tls13_derive_session_psk calculates the PSK for this session based on the
1302	// resumption master secret and \|nonce\|. It returns true on success, and false
1303	// on failure.
1304	bool tls13_derive_session_psk(SSL_SESSION session, Span<const* uint8_t> nonce);
1305
1306	// tls13_write_psk_binder calculates the PSK binder value and replaces the last
1307	// bytes of \|msg\| with the resulting value. It returns true on success, and
1308	// false on failure.
1309	bool tls13_write_psk_binder(SSL_HANDSHAKE hs, uint8_t msg, size_t len);
1310
1311	// tls13_verify_psk_binder verifies that the handshake transcript, truncated up
1312	// to the binders has a valid signature using the value of \|session\|'s
1313	// resumption secret. It returns true on success, and false on failure.
1314	bool tls13_verify_psk_binder(SSL_HANDSHAKE hs, SSL_SESSION session,
1315	const SSLMessage &msg, CBS *binders);
1316
1317
1318	// Handshake functions.
1319
1320	enum ssl_hs_wait_t {
1321	ssl_hs_error,
1322	ssl_hs_ok,
1323	ssl_hs_read_server_hello,
1324	ssl_hs_read_message,
1325	ssl_hs_flush,
1326	ssl_hs_certificate_selection_pending,
1327	ssl_hs_handoff,
1328	ssl_hs_handback,
1329	ssl_hs_x509_lookup,
1330	ssl_hs_channel_id_lookup,
1331	ssl_hs_private_key_operation,
1332	ssl_hs_pending_session,
1333	ssl_hs_pending_ticket,
1334	ssl_hs_early_return,
1335	ssl_hs_early_data_rejected,
1336	ssl_hs_read_end_of_early_data,
1337	ssl_hs_read_change_cipher_spec,
1338	ssl_hs_certificate_verify,
1339	};
1340
1341	enum ssl_grease_index_t {
1342	ssl_grease_cipher = `0`,
1343	ssl_grease_group,
1344	ssl_grease_extension1,
1345	ssl_grease_extension2,
1346	ssl_grease_version,
1347	ssl_grease_ticket_extension,
1348	ssl_grease_last_index = ssl_grease_ticket_extension,
1349	};
1350
1351	enum tls12_server_hs_state_t {
1352	state12_start_accept = `0`,
1353	state12_read_client_hello,
1354	state12_select_certificate,
1355	state12_tls13,
1356	state12_select_parameters,
1357	state12_send_server_hello,
1358	state12_send_server_certificate,
1359	state12_send_server_key_exchange,
1360	state12_send_server_hello_done,
1361	state12_read_client_certificate,
1362	state12_verify_client_certificate,
1363	state12_read_client_key_exchange,
1364	state12_read_client_certificate_verify,
1365	state12_read_change_cipher_spec,
1366	state12_process_change_cipher_spec,
1367	state12_read_next_proto,
1368	state12_read_channel_id,
1369	state12_read_client_finished,
1370	state12_send_server_finished,
1371	state12_finish_server_handshake,
1372	state12_done,
1373	};
1374
1375	// handback_t lists the points in the state machine where a handback can occur.
1376	// These are the different points at which key material is no longer needed.
1377	enum handback_t {
1378	handback_after_session_resumption,
1379	handback_after_ecdhe,
1380	handback_after_handshake,
1381	};
1382
1383
1384	// Delegated credentials.
1385
1386	// This structure stores a delegated credential (DC) as defined by
1387	// draft-ietf-tls-subcerts-03.
1388	struct DC {
1389	static constexpr bool kAllowUniquePtr = true;
1390	~DC();
1391
1392	// Dup returns a copy of this DC and takes references to \|raw\| and \|pkey\|.
1393	UniquePtr<DC> Dup();
1394
1395	// Parse parses the delegated credential stored in \|in\|. If successful it
1396	// returns the parsed structure, otherwise it returns \|nullptr\| and sets
1397	// \|out_alert\|.*
1398	static UniquePtr<DC> Parse(CRYPTO_BUFFER in, uint8_t out_alert);
1399
1400	// raw is the delegated credential encoded as specified in draft-ietf-tls-
1401	// subcerts-03.
1402	UniquePtr<CRYPTO_BUFFER> raw;
1403
1404	// expected_cert_verify_algorithm is the signature scheme of the DC public
1405	// key.
1406	uint16_t expected_cert_verify_algorithm = `0`;
1407
1408	// pkey is the public key parsed from \|public_key\|.
1409	UniquePtr<EVP_PKEY> pkey;
1410
1411	private:
1412	friend DC* New<DC>();
1413	DC();
1414	};
1415
1416	// ssl_signing_with_dc returns true if the peer has indicated support for
1417	// delegated credentials and this host has sent a delegated credential in
1418	// response. If this is true then we've committed to using the DC in the
1419	// handshake.
1420	bool ssl_signing_with_dc(const SSL_HANDSHAKE *hs);
1421
1422
1423	struct SSL_HANDSHAKE {
1424	explicit SSL_HANDSHAKE(SSL *ssl);
1425	~SSL_HANDSHAKE();
1426	static constexpr bool kAllowUniquePtr = true;
1427
1428	// ssl is a non-owning pointer to the parent \|SSL\| object.
1429	SSL *ssl;
1430
1431	// config is a non-owning pointer to the handshake configuration.
1432	SSL_CONFIG *config;
1433
1434	// wait contains the operation the handshake is currently blocking on or
1435	// \|ssl_hs_ok\| if none.
1436	enum ssl_hs_wait_t wait = ssl_hs_ok;
1437
1438	// state is the internal state for the TLS 1.2 and below handshake. Its
1439	// values depend on \|do_handshake\| but the starting state is always zero.
1440	int state = `0`;
1441
1442	// tls13_state is the internal state for the TLS 1.3 handshake. Its values
1443	// depend on \|do_handshake\| but the starting state is always zero.
1444	int tls13_state = `0`;
1445
1446	// min_version is the minimum accepted protocol version, taking account both
1447	// \|SSL_OP_NO_\| and \|SSL_CTX_set_min_proto_version\| APIs.*
1448	uint16_t min_version = `0`;
1449
1450	// max_version is the maximum accepted protocol version, taking account both
1451	// \|SSL_OP_NO_\| and \|SSL_CTX_set_max_proto_version\| APIs.*
1452	uint16_t max_version = `0`;
1453
1454	size_t hash_len = `0`;
1455	uint8_t secret[EVP_MAX_MD_SIZE] = {`0`};
1456	uint8_t early_traffic_secret[EVP_MAX_MD_SIZE] = {`0`};
1457	uint8_t client_handshake_secret[EVP_MAX_MD_SIZE] = {`0`};
1458	uint8_t server_handshake_secret[EVP_MAX_MD_SIZE] = {`0`};
1459	uint8_t client_traffic_secret_0[EVP_MAX_MD_SIZE] = {`0`};
1460	uint8_t server_traffic_secret_0[EVP_MAX_MD_SIZE] = {`0`};
1461	uint8_t expected_client_finished[EVP_MAX_MD_SIZE] = {`0`};
1462
1463	union {
1464	// sent is a bitset where the bits correspond to elements of kExtensions
1465	// in t1_lib.c. Each bit is set if that extension was sent in a
1466	// ClientHello. It's not used by servers.
1467	uint32_t sent = `0`;
1468	// received is a bitset, like \|sent\|, but is used by servers to record
1469	// which extensions were received from a client.
1470	uint32_t received;
1471	} extensions;
1472
1473	// retry_group is the group ID selected by the server in HelloRetryRequest in
1474	// TLS 1.3.
1475	uint16_t retry_group = `0`;
1476
1477	// error, if \|wait\| is \|ssl_hs_error\|, is the error the handshake failed on.
1478	UniquePtr<ERR_SAVE_STATE> error;
1479
1480	// key_shares are the current key exchange instances. The second is only used
1481	// as a client if we believe that we should offer two key shares in a
1482	// ClientHello.
1483	UniquePtr<SSLKeyShare> key_shares[`2`];
1484
1485	// transcript is the current handshake transcript.
1486	SSLTranscript transcript;
1487
1488	// cookie is the value of the cookie received from the server, if any.
1489	Array<uint8_t> cookie;
1490
1491	// key_share_bytes is the value of the previously sent KeyShare extension by
1492	// the client in TLS 1.3.
1493	Array<uint8_t> key_share_bytes;
1494
1495	// ecdh_public_key, for servers, is the key share to be sent to the client in
1496	// TLS 1.3.
1497	Array<uint8_t> ecdh_public_key;
1498
1499	// peer_sigalgs are the signature algorithms that the peer supports. These are
1500	// taken from the contents of the signature algorithms extension for a server
1501	// or from the CertificateRequest for a client.
1502	Array<uint16_t> peer_sigalgs;
1503
1504	// peer_supported_group_list contains the supported group IDs advertised by
1505	// the peer. This is only set on the server's end. The server does not
1506	// advertise this extension to the client.
1507	Array<uint16_t> peer_supported_group_list;
1508
1509	// peer_key is the peer's ECDH key for a TLS 1.2 client.
1510	Array<uint8_t> peer_key;
1511
1512	// negotiated_token_binding_version is used by a server to store the
1513	// on-the-wire encoding of the Token Binding protocol version to advertise in
1514	// the ServerHello/EncryptedExtensions if the Token Binding extension is to be
1515	// sent.
1516	uint16_t negotiated_token_binding_version;
1517
1518	// cert_compression_alg_id, for a server, contains the negotiated certificate
1519	// compression algorithm for this client. It is only valid if
1520	// \|cert_compression_negotiated\| is true.
1521	uint16_t cert_compression_alg_id;
1522
1523	// server_params, in a TLS 1.2 server, stores the ServerKeyExchange
1524	// parameters. It has client and server randoms prepended for signing
1525	// convenience.
1526	Array<uint8_t> server_params;
1527
1528	// peer_psk_identity_hint, on the client, is the psk_identity_hint sent by the
1529	// server when using a TLS 1.2 PSK key exchange.
1530	UniquePtr<char> peer_psk_identity_hint;
1531
1532	// ca_names, on the client, contains the list of CAs received in a
1533	// CertificateRequest message.
1534	UniquePtr<STACK_OF(CRYPTO_BUFFER)> ca_names;
1535
1536	// cached_x509_ca_names contains a cache of parsed versions of the elements of
1537	// \|ca_names\|. This pointer is left non-owning so only
1538	// \|ssl_crypto_x509_method\| needs to link against crypto/x509.
1539	STACK_OF(X509_NAME) cached_x509_ca_names = nullptr*;
1540
1541	// certificate_types, on the client, contains the set of certificate types
1542	// received in a CertificateRequest message.
1543	Array<uint8_t> certificate_types;
1544
1545	// local_pubkey is the public key we are authenticating as.
1546	UniquePtr<EVP_PKEY> local_pubkey;
1547
1548	// peer_pubkey is the public key parsed from the peer's leaf certificate.
1549	UniquePtr<EVP_PKEY> peer_pubkey;
1550
1551	// new_session is the new mutable session being established by the current
1552	// handshake. It should not be cached.
1553	UniquePtr<SSL_SESSION> new_session;
1554
1555	// early_session is the session corresponding to the current 0-RTT state on
1556	// the client if \|in_early_data\| is true.
1557	UniquePtr<SSL_SESSION> early_session;
1558
1559	// new_cipher is the cipher being negotiated in this handshake.
1560	const SSL_CIPHER new_cipher = nullptr*;
1561
1562	// key_block is the record-layer key block for TLS 1.2 and earlier.
1563	Array<uint8_t> key_block;
1564
1565	// scts_requested is true if the SCT extension is in the ClientHello.
1566	bool scts_requested : `1`;
1567
1568	// needs_psk_binder is true if the ClientHello has a placeholder PSK binder to
1569	// be filled in.
1570	bool needs_psk_binder : `1`;
1571
1572	bool received_hello_retry_request : `1`;
1573	bool sent_hello_retry_request : `1`;
1574
1575	// handshake_finalized is true once the handshake has completed, at which
1576	// point accessors should use the established state.
1577	bool handshake_finalized : `1`;
1578
1579	// accept_psk_mode stores whether the client's PSK mode is compatible with our
1580	// preferences.
1581	bool accept_psk_mode : `1`;
1582
1583	// cert_request is true if a client certificate was requested.
1584	bool cert_request : `1`;
1585
1586	// certificate_status_expected is true if OCSP stapling was negotiated and the
1587	// server is expected to send a CertificateStatus message. (This is used on
1588	// both the client and server sides.)
1589	bool certificate_status_expected : `1`;
1590
1591	// ocsp_stapling_requested is true if a client requested OCSP stapling.
1592	bool ocsp_stapling_requested : `1`;
1593
1594	// delegated_credential_requested is true if the peer indicated support for
1595	// the delegated credential extension.
1596	bool delegated_credential_requested : `1`;
1597
1598	// should_ack_sni is used by a server and indicates that the SNI extension
1599	// should be echoed in the ServerHello.
1600	bool should_ack_sni : `1`;
1601
1602	// in_false_start is true if there is a pending client handshake in False
1603	// Start. The client may write data at this point.
1604	bool in_false_start : `1`;
1605
1606	// in_early_data is true if there is a pending handshake that has progressed
1607	// enough to send and receive early data.
1608	bool in_early_data : `1`;
1609
1610	// early_data_offered is true if the client sent the early_data extension.
1611	bool early_data_offered : `1`;
1612
1613	// can_early_read is true if application data may be read at this point in the
1614	// handshake.
1615	bool can_early_read : `1`;
1616
1617	// can_early_write is true if application data may be written at this point in
1618	// the handshake.
1619	bool can_early_write : `1`;
1620
1621	// next_proto_neg_seen is one of NPN was negotiated.
1622	bool next_proto_neg_seen : `1`;
1623
1624	// ticket_expected is true if a TLS 1.2 NewSessionTicket message is to be sent
1625	// or received.
1626	bool ticket_expected : `1`;
1627
1628	// extended_master_secret is true if the extended master secret extension is
1629	// negotiated in this handshake.
1630	bool extended_master_secret : `1`;
1631
1632	// pending_private_key_op is true if there is a pending private key operation
1633	// in progress.
1634	bool pending_private_key_op : `1`;
1635
1636	// grease_seeded is true if \|grease_seed\| has been initialized.
1637	bool grease_seeded : `1`;
1638
1639	// handback indicates that a server should pause the handshake after
1640	// finishing operations that require private key material, in such a way that
1641	// \|SSL_get_error\| returns \|SSL_HANDBACK\|. It is set by \|SSL_apply_handoff\|.
1642	bool handback : `1`;
1643
1644	// cert_compression_negotiated is true iff \|cert_compression_alg_id\| is valid.
1645	bool cert_compression_negotiated : `1`;
1646
1647	// apply_jdk11_workaround is true if the peer is probably a JDK 11 client
1648	// which implemented TLS 1.3 incorrectly.
1649	bool apply_jdk11_workaround : `1`;
1650
1651	// client_version is the value sent or received in the ClientHello version.
1652	uint16_t client_version = `0`;
1653
1654	// early_data_read is the amount of early data that has been read by the
1655	// record layer.
1656	uint16_t early_data_read = `0`;
1657
1658	// early_data_written is the amount of early data that has been written by the
1659	// record layer.
1660	uint16_t early_data_written = `0`;
1661
1662	// session_id is the session ID in the ClientHello.
1663	uint8_t session_id[SSL_MAX_SSL_SESSION_ID_LENGTH] = {`0`};
1664	uint8_t session_id_len = `0`;
1665
1666	// grease_seed is the entropy for GREASE values. It is valid if
1667	// \|grease_seeded\| is true.
1668	uint8_t grease_seed[ssl_grease_last_index + `1`] = {`0`};
1669	};
1670
1671	UniquePtr<SSL_HANDSHAKE> ssl_handshake_new(SSL *ssl);
1672
1673	// ssl_check_message_type checks if \|msg\| has type \|type\|. If so it returns
1674	// one. Otherwise, it sends an alert and returns zero.
1675	bool ssl_check_message_type(SSL ssl, const* SSLMessage &msg, int type);
1676
1677	// ssl_run_handshake runs the TLS handshake. It returns one on success and <= 0
1678	// on error. It sets \|out_early_return\| to one if we've completed the handshake
1679	// early.
1680	int ssl_run_handshake(SSL_HANDSHAKE hs, bool* *out_early_return);
1681
1682	// The following are implementations of \|do_handshake\| for the client and
1683	// server.
1684	enum ssl_hs_wait_t ssl_client_handshake(SSL_HANDSHAKE *hs);
1685	enum ssl_hs_wait_t ssl_server_handshake(SSL_HANDSHAKE *hs);
1686	enum ssl_hs_wait_t tls13_client_handshake(SSL_HANDSHAKE *hs);
1687	enum ssl_hs_wait_t tls13_server_handshake(SSL_HANDSHAKE *hs);
1688
1689	// The following functions return human-readable representations of the TLS
1690	// handshake states for debugging.
1691	const char ssl_client_handshake_state(SSL_HANDSHAKE hs);
1692	const char ssl_server_handshake_state(SSL_HANDSHAKE hs);
1693	const char tls13_client_handshake_state(SSL_HANDSHAKE hs);
1694	const char tls13_server_handshake_state(SSL_HANDSHAKE hs);
1695
1696	// tls13_add_key_update queues a KeyUpdate message on \|ssl\|. The
1697	// \|update_requested\| argument must be one of \|SSL_KEY_UPDATE_REQUESTED\| or
1698	// \|SSL_KEY_UPDATE_NOT_REQUESTED\|.
1699	bool tls13_add_key_update(SSL ssl, int* update_requested);
1700
1701	// tls13_post_handshake processes a post-handshake message. It returns true on
1702	// success and false on failure.
1703	bool tls13_post_handshake(SSL ssl, const* SSLMessage &msg);
1704
1705	bool tls13_process_certificate(SSL_HANDSHAKE hs, const* SSLMessage &msg,
1706	bool allow_anonymous);
1707	bool tls13_process_certificate_verify(SSL_HANDSHAKE hs, const* SSLMessage &msg);
1708
1709	// tls13_process_finished processes \|msg\| as a Finished message from the
1710	// peer. If \|use_saved_value\| is true, the verify_data is compared against
1711	// \|hs->expected_client_finished\| rather than computed fresh.
1712	bool tls13_process_finished(SSL_HANDSHAKE hs, const* SSLMessage &msg,
1713	bool use_saved_value);
1714
1715	bool tls13_add_certificate(SSL_HANDSHAKE *hs);
1716
1717	// tls13_add_certificate_verify adds a TLS 1.3 CertificateVerify message to the
1718	// handshake. If it returns \|ssl_private_key_retry\|, it should be called again
1719	// to retry when the signing operation is completed.
1720	enum ssl_private_key_result_t tls13_add_certificate_verify(SSL_HANDSHAKE *hs);
1721
1722	bool tls13_add_finished(SSL_HANDSHAKE *hs);
1723	bool tls13_process_new_session_ticket(SSL ssl, const* SSLMessage &msg);
1724
1725	bool ssl_ext_key_share_parse_serverhello(SSL_HANDSHAKE *hs,
1726	Array<uint8_t> *out_secret,
1727	uint8_t out_alert, CBS contents);
1728	bool ssl_ext_key_share_parse_clienthello(SSL_HANDSHAKE hs, bool* *out_found,
1729	Array<uint8_t> *out_secret,
1730	uint8_t out_alert, CBS contents);
1731	bool ssl_ext_key_share_add_serverhello(SSL_HANDSHAKE hs, CBB out);
1732
1733	bool ssl_ext_pre_shared_key_parse_serverhello(SSL_HANDSHAKE *hs,
1734	uint8_t *out_alert,
1735	CBS *contents);
1736	bool ssl_ext_pre_shared_key_parse_clienthello(
1737	SSL_HANDSHAKE hs, CBS out_ticket, CBS *out_binders,
1738	uint32_t out_obfuscated_ticket_age, uint8_t out_alert, CBS *contents);
1739	bool ssl_ext_pre_shared_key_add_serverhello(SSL_HANDSHAKE hs, CBB out);
1740
1741	// ssl_is_sct_list_valid does a shallow parse of the SCT list in \|contents\| and
1742	// returns whether it's valid.
1743	bool ssl_is_sct_list_valid(const CBS *contents);
1744
1745	bool ssl_write_client_hello(SSL_HANDSHAKE *hs);
1746
1747	enum ssl_cert_verify_context_t {
1748	ssl_cert_verify_server,
1749	ssl_cert_verify_client,
1750	ssl_cert_verify_channel_id,
1751	};
1752
1753	// tls13_get_cert_verify_signature_input generates the message to be signed for
1754	// TLS 1.3's CertificateVerify message. \|cert_verify_context\| determines the
1755	// type of signature. It sets \|out\| to a newly allocated buffer containing the*
1756	// result. This function returns true on success and false on failure.
1757	bool tls13_get_cert_verify_signature_input(
1758	SSL_HANDSHAKE hs, Array<uint8_t> out,
1759	enum ssl_cert_verify_context_t cert_verify_context);
1760
1761	// ssl_is_alpn_protocol_allowed returns whether \|protocol\| is a valid server
1762	// selection for \|hs->ssl\|'s client preferences.
1763	bool ssl_is_alpn_protocol_allowed(const SSL_HANDSHAKE *hs,
1764	Span<const uint8_t> protocol);
1765
1766	// ssl_negotiate_alpn negotiates the ALPN extension, if applicable. It returns
1767	// true on successful negotiation or if nothing was negotiated. It returns false
1768	// and sets \|out_alert\| to an alert on error.*
1769	bool ssl_negotiate_alpn(SSL_HANDSHAKE hs, uint8_t out_alert,
1770	const SSL_CLIENT_HELLO *client_hello);
1771
1772	struct SSL_EXTENSION_TYPE {
1773	uint16_t type;
1774	bool *out_present;
1775	CBS *out_data;
1776	};
1777
1778	// ssl_parse_extensions parses a TLS extensions block out of \|cbs\| and advances
1779	// it. It writes the parsed extensions to pointers denoted by \|ext_types\|. On
1780	// success, it fills in the \|out_present\| and \|out_data\| fields and returns one.
1781	// Otherwise, it sets \|out_alert\| to an alert to send and returns zero. Unknown*
1782	// extensions are rejected unless \|ignore_unknown\| is 1.
1783	int ssl_parse_extensions(const CBS cbs, uint8_t out_alert,
1784	const SSL_EXTENSION_TYPE *ext_types,
1785	size_t num_ext_types, int ignore_unknown);
1786
1787	// ssl_verify_peer_cert verifies the peer certificate for \|hs\|.
1788	enum ssl_verify_result_t ssl_verify_peer_cert(SSL_HANDSHAKE *hs);
1789	// ssl_reverify_peer_cert verifies the peer certificate for \|hs\| when resuming a
1790	// session.
1791	enum ssl_verify_result_t ssl_reverify_peer_cert(SSL_HANDSHAKE *hs);
1792
1793	enum ssl_hs_wait_t ssl_get_finished(SSL_HANDSHAKE *hs);
1794	bool ssl_send_finished(SSL_HANDSHAKE *hs);
1795	bool ssl_output_cert_chain(SSL_HANDSHAKE *hs);
1796
1797	// SSLKEYLOGFILE functions.
1798
1799	// ssl_log_secret logs \|secret\| with label \|label\|, if logging is enabled for
1800	// \|ssl\|. It returns one on success and zero on failure.
1801	int ssl_log_secret(const SSL ssl, const* char label, const* uint8_t *secret,
1802	size_t secret_len);
1803
1804
1805	// ClientHello functions.
1806
1807	bool ssl_client_hello_init(const SSL ssl, SSL_CLIENT_HELLO out,
1808	const SSLMessage &msg);
1809
1810	bool ssl_client_hello_get_extension(const SSL_CLIENT_HELLO *client_hello,
1811	CBS *out, uint16_t extension_type);
1812
1813	bool ssl_client_cipher_list_contains_cipher(
1814	const SSL_CLIENT_HELLO *client_hello, uint16_t id);
1815
1816
1817	// GREASE.
1818
1819	// ssl_get_grease_value returns a GREASE value for \|hs\|. For a given
1820	// connection, the values for each index will be deterministic. This allows the
1821	// same ClientHello be sent twice for a HelloRetryRequest or the same group be
1822	// advertised in both supported_groups and key_shares.
1823	uint16_t ssl_get_grease_value(SSL_HANDSHAKE hs, enum* ssl_grease_index_t index);
1824
1825
1826	// Signature algorithms.
1827
1828	// tls1_parse_peer_sigalgs parses \|sigalgs\| as the list of peer signature
1829	// algorithms and saves them on \|hs\|. It returns true on success and false on
1830	// error.
1831	bool tls1_parse_peer_sigalgs(SSL_HANDSHAKE hs, const* CBS *sigalgs);
1832
1833	// tls1_get_legacy_signature_algorithm sets \|out\| to the signature algorithm*
1834	// that should be used with \|pkey\| in TLS 1.1 and earlier. It returns true on
1835	// success and false if \|pkey\| may not be used at those versions.
1836	bool tls1_get_legacy_signature_algorithm(uint16_t out, const* EVP_PKEY *pkey);
1837
1838	// tls1_choose_signature_algorithm sets \|out\| to a signature algorithm for use*
1839	// with \|hs\|'s private key based on the peer's preferences and the algorithms
1840	// supported. It returns true on success and false on error.
1841	bool tls1_choose_signature_algorithm(SSL_HANDSHAKE hs, uint16_t out);
1842
1843	// tls1_get_peer_verify_algorithms returns the signature schemes for which the
1844	// peer indicated support.
1845	//
1846	// NOTE: The related function \|SSL_get0_peer_verify_algorithms\| only has
1847	// well-defined behavior during the callbacks set by \|SSL_CTX_set_cert_cb\| and
1848	// \|SSL_CTX_set_client_cert_cb\|, or when the handshake is paused because of
1849	// them.
1850	Span<const uint16_t> tls1_get_peer_verify_algorithms(const SSL_HANDSHAKE *hs);
1851
1852	// tls12_add_verify_sigalgs adds the signature algorithms acceptable for the
1853	// peer signature to \|out\|. It returns true on success and false on error. If
1854	// \|for_certs\| is true, the potentially more restrictive list of algorithms for
1855	// certificates is used. Otherwise, the online signature one is used.
1856	bool tls12_add_verify_sigalgs(const SSL ssl, CBB out, bool for_certs);
1857
1858	// tls12_check_peer_sigalg checks if \|sigalg\| is acceptable for the peer
1859	// signature. It returns true on success and false on error, setting
1860	// \|out_alert\| to an alert to send.*
1861	bool tls12_check_peer_sigalg(const SSL ssl, uint8_t out_alert,
1862	uint16_t sigalg);
1863
1864	// tls12_has_different_verify_sigalgs_for_certs returns whether \|ssl\| has a
1865	// different, more restrictive, list of signature algorithms acceptable for the
1866	// certificate than the online signature.
1867	bool tls12_has_different_verify_sigalgs_for_certs(const SSL *ssl);
1868
1869
1870	// Underdocumented functions.
1871	//
1872	// Functions below here haven't been touched up and may be underdocumented.
1873
1874	#define TLSEXT_CHANNEL_ID_SIZE 128
1875
1876	// From RFC4492, used in encoding the curve type in ECParameters
1877	#define NAMED_CURVE_TYPE 3
1878
1879	struct CERT {
1880	static constexpr bool kAllowUniquePtr = true;
1881
1882	explicit CERT(const SSL_X509_METHOD *x509_method);
1883	~CERT();
1884
1885	UniquePtr<EVP_PKEY> privatekey;
1886
1887	// chain contains the certificate chain, with the leaf at the beginning. The
1888	// first element of \|chain\| may be NULL to indicate that the leaf certificate
1889	// has not yet been set.
1890	// If \|chain\| != NULL -> len(chain) >= 1
1891	// If \|chain[0]\| == NULL -> len(chain) >= 2.
1892	// \|chain[1..]\| != NULL
1893	UniquePtr<STACK_OF(CRYPTO_BUFFER)> chain;
1894
1895	// x509_chain may contain a parsed copy of \|chain[1..]\|. This is only used as
1896	// a cache in order to implement “get0” functions that return a non-owning
1897	// pointer to the certificate chain.
1898	STACK_OF(X509) x509_chain = nullptr*;
1899
1900	// x509_leaf may contain a parsed copy of the first element of \|chain\|. This
1901	// is only used as a cache in order to implement “get0” functions that return
1902	// a non-owning pointer to the certificate chain.
1903	X509 x509_leaf = nullptr*;
1904
1905	// x509_stash contains the last \|X509\| object append to the chain. This is a
1906	// workaround for some third-party code that continue to use an \|X509\| object
1907	// even after passing ownership with an “add0” function.
1908	X509 x509_stash = nullptr*;
1909
1910	// key_method, if non-NULL, is a set of callbacks to call for private key
1911	// operations.
1912	const SSL_PRIVATE_KEY_METHOD key_method = nullptr*;
1913
1914	// x509_method contains pointers to functions that might deal with \|X509\|
1915	// compatibility, or might be a no-op, depending on the application.
1916	const SSL_X509_METHOD x509_method = nullptr*;
1917
1918	// sigalgs, if non-empty, is the set of signature algorithms supported by
1919	// \|privatekey\| in decreasing order of preference.
1920	Array<uint16_t> sigalgs;
1921
1922	// Certificate setup callback: if set is called whenever a
1923	// certificate may be required (client or server). the callback
1924	// can then examine any appropriate parameters and setup any
1925	// certificates required. This allows advanced applications
1926	// to select certificates on the fly: for example based on
1927	// supported signature algorithms or curves.
1928	int (cert_cb)(SSL ssl, void arg) = nullptr*;
1929	void cert_cb_arg = nullptr*;
1930
1931	// Optional X509_STORE for certificate validation. If NULL the parent SSL_CTX
1932	// store is used instead.
1933	X509_STORE verify_store = nullptr*;
1934
1935	// Signed certificate timestamp list to be sent to the client, if requested
1936	UniquePtr<CRYPTO_BUFFER> signed_cert_timestamp_list;
1937
1938	// OCSP response to be sent to the client, if requested.
1939	UniquePtr<CRYPTO_BUFFER> ocsp_response;
1940
1941	// sid_ctx partitions the session space within a shared session cache or
1942	// ticket key. Only sessions with a matching value will be accepted.
1943	uint8_t sid_ctx_length = `0`;
1944	uint8_t sid_ctx[SSL_MAX_SID_CTX_LENGTH] = {`0`};
1945
1946	// Delegated credentials.
1947
1948	// dc is the delegated credential to send to the peer (if requested).
1949	UniquePtr<DC> dc = nullptr;
1950
1951	// dc_privatekey is used instead of \|privatekey\| or \|key_method\| to
1952	// authenticate the host if a delegated credential is used in the handshake.
1953	UniquePtr<EVP_PKEY> dc_privatekey = nullptr;
1954
1955	// dc_key_method, if not NULL, is used instead of \|dc_privatekey\| to
1956	// authenticate the host.
1957	const SSL_PRIVATE_KEY_METHOD dc_key_method = nullptr*;
1958	};
1959
1960	// \|SSL_PROTOCOL_METHOD\| abstracts between TLS and DTLS.
1961	struct SSL_PROTOCOL_METHOD {
1962	bool is_dtls;
1963	bool (ssl_new)(SSL ssl);
1964	void (ssl_free)(SSL ssl);
1965	// get_message sets \|out\| to the current handshake message and returns true*
1966	// if one has been received. It returns false if more input is needed.
1967	bool (get_message)(const* SSL ssl, SSLMessage out);
1968	// next_message is called to release the current handshake message.
1969	void (next_message)(SSL ssl);
1970	// Use the \|ssl_open_handshake\| wrapper.
1971	ssl_open_record_t (open_handshake)(SSL ssl, size_t *out_consumed,
1972	uint8_t *out_alert, Span<uint8_t> in);
1973	// Use the \|ssl_open_change_cipher_spec\| wrapper.
1974	ssl_open_record_t (open_change_cipher_spec)(SSL ssl, size_t *out_consumed,
1975	uint8_t *out_alert,
1976	Span<uint8_t> in);
1977	// Use the \|ssl_open_app_data\| wrapper.
1978	ssl_open_record_t (open_app_data)(SSL ssl, Span<uint8_t> *out,
1979	size_t out_consumed, uint8_t out_alert,
1980	Span<uint8_t> in);
1981	int (write_app_data)(SSL ssl, bool out_needs_handshake, const* uint8_t *buf,
1982	int len);
1983	int (dispatch_alert)(SSL ssl);
1984	// init_message begins a new handshake message of type \|type\|. \|cbb\| is the
1985	// root CBB to be passed into \|finish_message\|. \|body\| is set to a child CBB*
1986	// the caller should write to. It returns true on success and false on error.
1987	bool (init_message)(SSL ssl, CBB cbb, CBB body, uint8_t type);
1988	// finish_message finishes a handshake message. It sets \|out_msg\| to the*
1989	// serialized message. It returns true on success and false on error.
1990	bool (finish_message)(SSL ssl, CBB cbb, bssl::Array<uint8_t> out_msg);
1991	// add_message adds a handshake message to the pending flight. It returns
1992	// true on success and false on error.
1993	bool (add_message)(SSL ssl, bssl::Array<uint8_t> msg);
1994	// add_change_cipher_spec adds a ChangeCipherSpec record to the pending
1995	// flight. It returns true on success and false on error.
1996	bool (add_change_cipher_spec)(SSL ssl);
1997	// flush_flight flushes the pending flight to the transport. It returns one on
1998	// success and <= 0 on error.
1999	int (flush_flight)(SSL ssl);
2000	// on_handshake_complete is called when the handshake is complete.
2001	void (on_handshake_complete)(SSL ssl);
2002	// set_read_state sets \|ssl\|'s read cipher state to \|aead_ctx\|. It returns
2003	// true on success and false if changing the read state is forbidden at this
2004	// point.
2005	bool (set_read_state)(SSL ssl, UniquePtr<SSLAEADContext> aead_ctx);
2006	// set_write_state sets \|ssl\|'s write cipher state to \|aead_ctx\|. It returns
2007	// true on success and false if changing the write state is forbidden at this
2008	// point.
2009	bool (set_write_state)(SSL ssl, UniquePtr<SSLAEADContext> aead_ctx);
2010	};
2011
2012	// The following wrappers call \|open_\| but handle \|read_shutdown\| correctly.*
2013
2014	// ssl_open_handshake processes a record from \|in\| for reading a handshake
2015	// message.
2016	ssl_open_record_t ssl_open_handshake(SSL ssl, size_t out_consumed,
2017	uint8_t *out_alert, Span<uint8_t> in);
2018
2019	// ssl_open_change_cipher_spec processes a record from \|in\| for reading a
2020	// ChangeCipherSpec.
2021	ssl_open_record_t ssl_open_change_cipher_spec(SSL ssl, size_t out_consumed,
2022	uint8_t *out_alert,
2023	Span<uint8_t> in);
2024
2025	// ssl_open_app_data processes a record from \|in\| for reading application data.
2026	// On success, it returns \|ssl_open_record_success\| and sets \|out\| to the*
2027	// input. If it encounters a post-handshake message, it returns
2028	// \|ssl_open_record_discard\|. The caller should then retry, after processing any
2029	// messages received with \|get_message\|.
2030	ssl_open_record_t ssl_open_app_data(SSL ssl, Span<uint8_t> out,
2031	size_t out_consumed, uint8_t out_alert,
2032	Span<uint8_t> in);
2033
2034	struct SSL_X509_METHOD {
2035	// check_client_CA_list returns one if \|names\| is a good list of X.509
2036	// distinguished names and zero otherwise. This is used to ensure that we can
2037	// reject unparsable values at handshake time when using crypto/x509.
2038	bool (check_client_CA_list)(STACK_OF(CRYPTO_BUFFER) names);
2039
2040	// cert_clear frees and NULLs all X509 certificate-related state.
2041	void (cert_clear)(CERT cert);
2042	// cert_free frees all X509-related state.
2043	void (cert_free)(CERT cert);
2044	// cert_flush_cached_chain drops any cached \|X509\|-based certificate chain
2045	// from \|cert\|.
2046	// cert_dup duplicates any needed fields from \|cert\| to \|new_cert\|.
2047	void (cert_dup)(CERT new_cert, const CERT *cert);
2048	void (cert_flush_cached_chain)(CERT cert);
2049	// cert_flush_cached_chain drops any cached \|X509\|-based leaf certificate
2050	// from \|cert\|.
2051	void (cert_flush_cached_leaf)(CERT cert);
2052
2053	// session_cache_objects fills out \|sess->x509_peer\| and \|sess->x509_chain\|
2054	// from \|sess->certs\| and erases \|sess->x509_chain_without_leaf\|. It returns
2055	// true on success or false on error.
2056	bool (session_cache_objects)(SSL_SESSION session);
2057	// session_dup duplicates any needed fields from \|session\| to \|new_session\|.
2058	// It returns true on success or false on error.
2059	bool (session_dup)(SSL_SESSION new_session, const SSL_SESSION *session);
2060	// session_clear frees any X509-related state from \|session\|.
2061	void (session_clear)(SSL_SESSION session);
2062	// session_verify_cert_chain verifies the certificate chain in \|session\|,
2063	// sets \|session->verify_result\| and returns true on success or false on
2064	// error.
2065	bool (session_verify_cert_chain)(SSL_SESSION session, SSL_HANDSHAKE *ssl,
2066	uint8_t *out_alert);
2067
2068	// hs_flush_cached_ca_names drops any cached \|X509_NAME\|s from \|hs\|.
2069	void (hs_flush_cached_ca_names)(SSL_HANDSHAKE hs);
2070	// ssl_new does any necessary initialisation of \|hs\|. It returns true on
2071	// success or false on error.
2072	bool (ssl_new)(SSL_HANDSHAKE hs);
2073	// ssl_free frees anything created by \|ssl_new\|.
2074	void (ssl_config_free)(SSL_CONFIG cfg);
2075	// ssl_flush_cached_client_CA drops any cached \|X509_NAME\|s from \|ssl\|.
2076	void (ssl_flush_cached_client_CA)(SSL_CONFIG cfg);
2077	// ssl_auto_chain_if_needed runs the deprecated auto-chaining logic if
2078	// necessary. On success, it updates \|ssl\|'s certificate configuration as
2079	// needed and returns true. Otherwise, it returns false.
2080	bool (ssl_auto_chain_if_needed)(SSL_HANDSHAKE hs);
2081	// ssl_ctx_new does any necessary initialisation of \|ctx\|. It returns true on
2082	// success or false on error.
2083	bool (ssl_ctx_new)(SSL_CTX ctx);
2084	// ssl_ctx_free frees anything created by \|ssl_ctx_new\|.
2085	void (ssl_ctx_free)(SSL_CTX ctx);
2086	// ssl_ctx_flush_cached_client_CA drops any cached \|X509_NAME\|s from \|ctx\|.
2087	void (ssl_ctx_flush_cached_client_CA)(SSL_CTX ssl);
2088	};
2089
2090	// ssl_crypto_x509_method provides the \|SSL_X509_METHOD\| functions using
2091	// crypto/x509.
2092	extern const SSL_X509_METHOD ssl_crypto_x509_method;
2093
2094	// ssl_noop_x509_method provides the \|SSL_X509_METHOD\| functions that avoid
2095	// crypto/x509.
2096	extern const SSL_X509_METHOD ssl_noop_x509_method;
2097
2098	struct TicketKey {
2099	static constexpr bool kAllowUniquePtr = true;
2100
2101	uint8_t name[SSL_TICKET_KEY_NAME_LEN] = {`0`};
2102	uint8_t hmac_key[`16`] = {`0`};
2103	uint8_t aes_key[`16`] = {`0`};
2104	// next_rotation_tv_sec is the time (in seconds from the epoch) when the
2105	// current key should be superseded by a new key, or the time when a previous
2106	// key should be dropped. If zero, then the key should not be automatically
2107	// rotated.
2108	uint64_t next_rotation_tv_sec = `0`;
2109	};
2110
2111	struct CertCompressionAlg {
2112	static constexpr bool kAllowUniquePtr = true;
2113
2114	ssl_cert_compression_func_t compress = nullptr;
2115	ssl_cert_decompression_func_t decompress = nullptr;
2116	uint16_t alg_id = `0`;
2117	};
2118
2119	BSSL_NAMESPACE_END
2120
2121	DEFINE_LHASH_OF(SSL_SESSION)
2122
2123	DEFINE_NAMED_STACK_OF(CertCompressionAlg, bssl::CertCompressionAlg)
2124
2125	BSSL_NAMESPACE_BEGIN
2126
2127	// An ssl_shutdown_t describes the shutdown state of one end of the connection,
2128	// whether it is alive or has been shutdown via close_notify or fatal alert.
2129	enum ssl_shutdown_t {
2130	ssl_shutdown_none = `0`,
2131	ssl_shutdown_close_notify = `1`,
2132	ssl_shutdown_error = `2`,
2133	};
2134
2135	struct SSL3_STATE {
2136	static constexpr bool kAllowUniquePtr = true;
2137
2138	SSL3_STATE();
2139	~SSL3_STATE();
2140
2141	uint8_t read_sequence[`8`] = {`0`};
2142	uint8_t write_sequence[`8`] = {`0`};
2143
2144	uint8_t server_random[SSL3_RANDOM_SIZE] = {`0`};
2145	uint8_t client_random[SSL3_RANDOM_SIZE] = {`0`};
2146
2147	// read_buffer holds data from the transport to be processed.
2148	SSLBuffer read_buffer;
2149	// write_buffer holds data to be written to the transport.
2150	SSLBuffer write_buffer;
2151
2152	// pending_app_data is the unconsumed application data. It points into
2153	// \|read_buffer\|.
2154	Span<uint8_t> pending_app_data;
2155
2156	// partial write - check the numbers match
2157	unsigned int wnum = `0`; // number of bytes sent so far
2158	int wpend_tot = `0`; // number bytes written
2159	int wpend_type = `0`;
2160	int wpend_ret = `0`; // number of bytes submitted
2161	const uint8_t wpend_buf = nullptr*;
2162
2163	// read_shutdown is the shutdown state for the read half of the connection.
2164	enum ssl_shutdown_t read_shutdown = ssl_shutdown_none;
2165
2166	// write_shutdown is the shutdown state for the write half of the connection.
2167	enum ssl_shutdown_t write_shutdown = ssl_shutdown_none;
2168
2169	// read_error, if \|read_shutdown\| is \|ssl_shutdown_error\|, is the error for
2170	// the receive half of the connection.
2171	UniquePtr<ERR_SAVE_STATE> read_error;
2172
2173	int alert_dispatch = `0`;
2174
2175	int total_renegotiations = `0`;
2176
2177	// This holds a variable that indicates what we were doing when a 0 or -1 is
2178	// returned. This is needed for non-blocking IO so we know what request
2179	// needs re-doing when in SSL_accept or SSL_connect
2180	int rwstate = SSL_NOTHING;
2181
2182	enum ssl_encryption_level_t read_level = ssl_encryption_initial;
2183	enum ssl_encryption_level_t write_level = ssl_encryption_initial;
2184
2185	// early_data_skipped is the amount of early data that has been skipped by the
2186	// record layer.
2187	uint16_t early_data_skipped = `0`;
2188
2189	// empty_record_count is the number of consecutive empty records received.
2190	uint8_t empty_record_count = `0`;
2191
2192	// warning_alert_count is the number of consecutive warning alerts
2193	// received.
2194	uint8_t warning_alert_count = `0`;
2195
2196	// key_update_count is the number of consecutive KeyUpdates received.
2197	uint8_t key_update_count = `0`;
2198
2199	// The negotiated Token Binding key parameter. Only valid if
2200	// \|token_binding_negotiated\| is set.
2201	uint8_t negotiated_token_binding_param = `0`;
2202
2203	// skip_early_data instructs the record layer to skip unexpected early data
2204	// messages when 0RTT is rejected.
2205	bool skip_early_data : `1`;
2206
2207	// have_version is true if the connection's final version is known. Otherwise
2208	// the version has not been negotiated yet.
2209	bool have_version : `1`;
2210
2211	// v2_hello_done is true if the peer's V2ClientHello, if any, has been handled
2212	// and future messages should use the record layer.
2213	bool v2_hello_done : `1`;
2214
2215	// is_v2_hello is true if the current handshake message was derived from a
2216	// V2ClientHello rather than received from the peer directly.
2217	bool is_v2_hello : `1`;
2218
2219	// has_message is true if the current handshake message has been returned
2220	// at least once by \|get_message\| and false otherwise.
2221	bool has_message : `1`;
2222
2223	// initial_handshake_complete is true if the initial handshake has
2224	// completed.
2225	bool initial_handshake_complete : `1`;
2226
2227	// session_reused indicates whether a session was resumed.
2228	bool session_reused : `1`;
2229
2230	// delegated_credential_used is whether we presented a delegated credential to
2231	// the peer.
2232	bool delegated_credential_used : `1`;
2233
2234	bool send_connection_binding : `1`;
2235
2236	// In a client, this means that the server supported Channel ID and that a
2237	// Channel ID was sent. In a server it means that we echoed support for
2238	// Channel IDs and that \|channel_id\| will be valid after the handshake.
2239	bool channel_id_valid : `1`;
2240
2241	// key_update_pending is true if we have a KeyUpdate acknowledgment
2242	// outstanding.
2243	bool key_update_pending : `1`;
2244
2245	// wpend_pending is true if we have a pending write outstanding.
2246	bool wpend_pending : `1`;
2247
2248	// early_data_accepted is true if early data was accepted by the server.
2249	bool early_data_accepted : `1`;
2250
2251	// tls13_downgrade is whether the TLS 1.3 anti-downgrade logic fired.
2252	bool tls13_downgrade : `1`;
2253
2254	// token_binding_negotiated is set if Token Binding was negotiated.
2255	bool token_binding_negotiated : `1`;
2256
2257	// pq_experimental_signal_seen is true if the peer was observed
2258	// sending/echoing the post-quantum experiment signal.
2259	bool pq_experiment_signal_seen : `1`;
2260
2261	// hs_buf is the buffer of handshake data to process.
2262	UniquePtr<BUF_MEM> hs_buf;
2263
2264	// pending_hs_data contains the pending handshake data that has not yet
2265	// been encrypted to \|pending_flight\|. This allows packing the handshake into
2266	// fewer records.
2267	UniquePtr<BUF_MEM> pending_hs_data;
2268
2269	// pending_flight is the pending outgoing flight. This is used to flush each
2270	// handshake flight in a single write. \|write_buffer\| must be written out
2271	// before this data.
2272	UniquePtr<BUF_MEM> pending_flight;
2273
2274	// pending_flight_offset is the number of bytes of \|pending_flight\| which have
2275	// been successfully written.
2276	uint32_t pending_flight_offset = `0`;
2277
2278	// ticket_age_skew is the difference, in seconds, between the client-sent
2279	// ticket age and the server-computed value in TLS 1.3 server connections
2280	// which resumed a session.
2281	int32_t ticket_age_skew = `0`;
2282
2283	// ssl_early_data_reason stores details on why 0-RTT was accepted or rejected.
2284	enum ssl_early_data_reason_t early_data_reason = ssl_early_data_unknown;
2285
2286	// aead_read_ctx is the current read cipher state.
2287	UniquePtr<SSLAEADContext> aead_read_ctx;
2288
2289	// aead_write_ctx is the current write cipher state.
2290	UniquePtr<SSLAEADContext> aead_write_ctx;
2291
2292	// hs is the handshake state for the current handshake or NULL if there isn't
2293	// one.
2294	UniquePtr<SSL_HANDSHAKE> hs;
2295
2296	uint8_t write_traffic_secret[EVP_MAX_MD_SIZE] = {`0`};
2297	uint8_t read_traffic_secret[EVP_MAX_MD_SIZE] = {`0`};
2298	uint8_t exporter_secret[EVP_MAX_MD_SIZE] = {`0`};
2299	uint8_t early_exporter_secret[EVP_MAX_MD_SIZE] = {`0`};
2300	uint8_t write_traffic_secret_len = `0`;
2301	uint8_t read_traffic_secret_len = `0`;
2302	uint8_t exporter_secret_len = `0`;
2303	uint8_t early_exporter_secret_len = `0`;
2304
2305	// Connection binding to prevent renegotiation attacks
2306	uint8_t previous_client_finished[`12`] = {`0`};
2307	uint8_t previous_client_finished_len = `0`;
2308	uint8_t previous_server_finished_len = `0`;
2309	uint8_t previous_server_finished[`12`] = {`0`};
2310
2311	uint8_t send_alert[`2`] = {`0`};
2312
2313	// established_session is the session established by the connection. This
2314	// session is only filled upon the completion of the handshake and is
2315	// immutable.
2316	UniquePtr<SSL_SESSION> established_session;
2317
2318	// Next protocol negotiation. For the client, this is the protocol that we
2319	// sent in NextProtocol and is set when handling ServerHello extensions.
2320	//
2321	// For a server, this is the client's selected_protocol from NextProtocol and
2322	// is set when handling the NextProtocol message, before the Finished
2323	// message.
2324	Array<uint8_t> next_proto_negotiated;
2325
2326	// ALPN information
2327	// (we are in the process of transitioning from NPN to ALPN.)
2328
2329	// In a server these point to the selected ALPN protocol after the
2330	// ClientHello has been processed. In a client these contain the protocol
2331	// that the server selected once the ServerHello has been processed.
2332	Array<uint8_t> alpn_selected;
2333
2334	// hostname, on the server, is the value of the SNI extension.
2335	UniquePtr<char> hostname;
2336
2337	// For a server:
2338	// If \|channel_id_valid\| is true, then this contains the
2339	// verified Channel ID from the client: a P256 point, (x,y), where
2340	// each are big-endian values.
2341	uint8_t channel_id[`64`] = {`0`};
2342
2343	// Contains the QUIC transport params received by the peer.
2344	Array<uint8_t> peer_quic_transport_params;
2345
2346	// srtp_profile is the selected SRTP protection profile for
2347	// DTLS-SRTP.
2348	const SRTP_PROTECTION_PROFILE srtp_profile = nullptr*;
2349	};
2350
2351	// lengths of messages
2352	#define DTLS1_COOKIE_LENGTH 256
2353
2354	#define DTLS1_RT_HEADER_LENGTH 13
2355
2356	#define DTLS1_HM_HEADER_LENGTH 12
2357
2358	#define DTLS1_CCS_HEADER_LENGTH 1
2359
2360	#define DTLS1_AL_HEADER_LENGTH 2
2361
2362	struct hm_header_st {
2363	uint8_t type;
2364	uint32_t msg_len;
2365	uint16_t seq;
2366	uint32_t frag_off;
2367	uint32_t frag_len;
2368	};
2369
2370	// An hm_fragment is an incoming DTLS message, possibly not yet assembled.
2371	struct hm_fragment {
2372	static constexpr bool kAllowUniquePtr = true;
2373
2374	hm_fragment() {}
2375	hm_fragment(const hm_fragment &) = delete;
2376	hm_fragment &operator=(const hm_fragment &) = delete;
2377
2378	~hm_fragment();
2379
2380	// type is the type of the message.
2381	uint8_t type = `0`;
2382	// seq is the sequence number of this message.
2383	uint16_t seq = `0`;
2384	// msg_len is the length of the message body.
2385	uint32_t msg_len = `0`;
2386	// data is a pointer to the message, including message header. It has length
2387	// \|DTLS1_HM_HEADER_LENGTH\| + \|msg_len\|.
2388	uint8_t data = nullptr*;
2389	// reassembly is a bitmask of \|msg_len\| bits corresponding to which parts of
2390	// the message have been received. It is NULL if the message is complete.
2391	uint8_t reassembly = nullptr*;
2392	};
2393
2394	struct OPENSSL_timeval {
2395	uint64_t tv_sec;
2396	uint32_t tv_usec;
2397	};
2398
2399	struct DTLS1_STATE {
2400	static constexpr bool kAllowUniquePtr = true;
2401
2402	DTLS1_STATE();
2403	~DTLS1_STATE();
2404
2405	// has_change_cipher_spec is true if we have received a ChangeCipherSpec from
2406	// the peer in this epoch.
2407	bool has_change_cipher_spec : `1`;
2408
2409	// outgoing_messages_complete is true if \|outgoing_messages\| has been
2410	// completed by an attempt to flush it. Future calls to \|add_message\| and
2411	// \|add_change_cipher_spec\| will start a new flight.
2412	bool outgoing_messages_complete : `1`;
2413
2414	// flight_has_reply is true if the current outgoing flight is complete and has
2415	// processed at least one message. This is used to detect whether we or the
2416	// peer sent the final flight.
2417	bool flight_has_reply : `1`;
2418
2419	uint8_t cookie[DTLS1_COOKIE_LENGTH] = {`0`};
2420	size_t cookie_len = `0`;
2421
2422	// The current data and handshake epoch. This is initially undefined, and
2423	// starts at zero once the initial handshake is completed.
2424	uint16_t r_epoch = `0`;
2425	uint16_t w_epoch = `0`;
2426
2427	// records being received in the current epoch
2428	DTLS1_BITMAP bitmap;
2429
2430	uint16_t handshake_write_seq = `0`;
2431	uint16_t handshake_read_seq = `0`;
2432
2433	// save last sequence number for retransmissions
2434	uint8_t last_write_sequence[`8`] = {`0`};
2435	UniquePtr<SSLAEADContext> last_aead_write_ctx;
2436
2437	// incoming_messages is a ring buffer of incoming handshake messages that have
2438	// yet to be processed. The front of the ring buffer is message number
2439	// \|handshake_read_seq\|, at position \|handshake_read_seq\| %
2440	// \|SSL_MAX_HANDSHAKE_FLIGHT\|.
2441	UniquePtr<hm_fragment> incoming_messages[SSL_MAX_HANDSHAKE_FLIGHT];
2442
2443	// outgoing_messages is the queue of outgoing messages from the last handshake
2444	// flight.
2445	DTLS_OUTGOING_MESSAGE outgoing_messages[SSL_MAX_HANDSHAKE_FLIGHT];
2446	uint8_t outgoing_messages_len = `0`;
2447
2448	// outgoing_written is the number of outgoing messages that have been
2449	// written.
2450	uint8_t outgoing_written = `0`;
2451	// outgoing_offset is the number of bytes of the next outgoing message have
2452	// been written.
2453	uint32_t outgoing_offset = `0`;
2454
2455	unsigned mtu = `0`; // max DTLS packet size
2456
2457	// num_timeouts is the number of times the retransmit timer has fired since
2458	// the last time it was reset.
2459	unsigned num_timeouts = `0`;
2460
2461	// Indicates when the last handshake msg or heartbeat sent will
2462	// timeout.
2463	struct OPENSSL_timeval next_timeout = {`0`, `0`};
2464
2465	// timeout_duration_ms is the timeout duration in milliseconds.
2466	unsigned timeout_duration_ms = `0`;
2467	};
2468
2469	// SSL_CONFIG contains configuration bits that can be shed after the handshake
2470	// completes. Objects of this type are not shared; they are unique to a
2471	// particular \|SSL\|.
2472	//
2473	// See SSL_shed_handshake_config() for more about the conditions under which
2474	// configuration can be shed.
2475	struct SSL_CONFIG {
2476	static constexpr bool kAllowUniquePtr = true;
2477
2478	explicit SSL_CONFIG(SSL *ssl_arg);
2479	~SSL_CONFIG();
2480
2481	// ssl is a non-owning pointer to the parent \|SSL\| object.
2482	SSL *const ssl = nullptr;
2483
2484	// conf_max_version is the maximum acceptable version configured by
2485	// \|SSL_set_max_proto_version\|. Note this version is not normalized in DTLS
2486	// and is further constrained by \|SSL_OP_NO_\|.*
2487	uint16_t conf_max_version = `0`;
2488
2489	// conf_min_version is the minimum acceptable version configured by
2490	// \|SSL_set_min_proto_version\|. Note this version is not normalized in DTLS
2491	// and is further constrained by \|SSL_OP_NO_\|.*
2492	uint16_t conf_min_version = `0`;
2493
2494	X509_VERIFY_PARAM param = nullptr*;
2495
2496	// crypto
2497	UniquePtr<SSLCipherPreferenceList> cipher_list;
2498
2499	// This is used to hold the local certificate used (i.e. the server
2500	// certificate for a server or the client certificate for a client).
2501	UniquePtr<CERT> cert;
2502
2503	int (verify_callback)(int* ok,
2504	X509_STORE_CTX *ctx) =
2505	nullptr; // fail if callback returns 0
2506
2507	enum ssl_verify_result_t (*custom_verify_callback)(
2508	SSL ssl, uint8_t out_alert) = nullptr;
2509	// Server-only: psk_identity_hint is the identity hint to send in
2510	// PSK-based key exchanges.
2511	UniquePtr<char> psk_identity_hint;
2512
2513	unsigned (psk_client_callback)(SSL ssl, const char hint, char* *identity,
2514	unsigned max_identity_len, uint8_t *psk,
2515	unsigned max_psk_len) = nullptr;
2516	unsigned (psk_server_callback)(SSL ssl, const char identity, uint8_t psk,
2517	unsigned max_psk_len) = nullptr;
2518
2519	// for server side, keep the list of CA_dn we can use
2520	UniquePtr<STACK_OF(CRYPTO_BUFFER)> client_CA;
2521
2522	// cached_x509_client_CA is a cache of parsed versions of the elements of
2523	// \|client_CA\|.
2524	STACK_OF(X509_NAME) cached_x509_client_CA = nullptr*;
2525
2526	Array<uint16_t> supported_group_list; // our list
2527
2528	// The client's Channel ID private key.
2529	UniquePtr<EVP_PKEY> channel_id_private;
2530
2531	// For a client, this contains the list of supported protocols in wire
2532	// format.
2533	Array<uint8_t> alpn_client_proto_list;
2534
2535	// Contains a list of supported Token Binding key parameters.
2536	Array<uint8_t> token_binding_params;
2537
2538	// Contains the QUIC transport params that this endpoint will send.
2539	Array<uint8_t> quic_transport_params;
2540
2541	// verify_sigalgs, if not empty, is the set of signature algorithms
2542	// accepted from the peer in decreasing order of preference.
2543	Array<uint16_t> verify_sigalgs;
2544
2545	// srtp_profiles is the list of configured SRTP protection profiles for
2546	// DTLS-SRTP.
2547	UniquePtr<STACK_OF(SRTP_PROTECTION_PROFILE)> srtp_profiles;
2548
2549	// verify_mode is a bitmask of \|SSL_VERIFY_\| values.*
2550	uint8_t verify_mode = SSL_VERIFY_NONE;
2551
2552	// Enable signed certificate time stamps. Currently client only.
2553	bool signed_cert_timestamps_enabled : `1`;
2554
2555	// ocsp_stapling_enabled is only used by client connections and indicates
2556	// whether OCSP stapling will be requested.
2557	bool ocsp_stapling_enabled : `1`;
2558
2559	// channel_id_enabled is copied from the \|SSL_CTX\|. For a server, means that
2560	// we'll accept Channel IDs from clients. For a client, means that we'll
2561	// advertise support.
2562	bool channel_id_enabled : `1`;
2563
2564	// If enforce_rsa_key_usage is true, the handshake will fail if the
2565	// keyUsage extension is present and incompatible with the TLS usage.
2566	// This field is not read until after certificate verification.
2567	bool enforce_rsa_key_usage : `1`;
2568
2569	// retain_only_sha256_of_client_certs is true if we should compute the SHA256
2570	// hash of the peer's certificate and then discard it to save memory and
2571	// session space. Only effective on the server side.
2572	bool retain_only_sha256_of_client_certs : `1`;
2573
2574	// handoff indicates that a server should stop after receiving the
2575	// ClientHello and pause the handshake in such a way that \|SSL_get_error\|
2576	// returns \|SSL_HANDOFF\|. This is copied in \|SSL_new\| from the \|SSL_CTX\|
2577	// element of the same name and may be cleared if the handoff is declined.
2578	bool handoff : `1`;
2579
2580	// shed_handshake_config indicates that the handshake config (this object!)
2581	// should be freed after the handshake completes.
2582	bool shed_handshake_config : `1`;
2583
2584	// ignore_tls13_downgrade is whether the connection should continue when the
2585	// server random signals a downgrade.
2586	bool ignore_tls13_downgrade : `1`;
2587
2588	// jdk11_workaround is whether to disable TLS 1.3 for JDK 11 clients, as a
2589	// workaround for https://bugs.openjdk.java.net/browse/JDK-8211806.
2590	bool jdk11_workaround : `1`;
2591	};
2592
2593	// From RFC 8446, used in determining PSK modes.
2594	#define SSL_PSK_DHE_KE 0x1
2595
2596	// kMaxEarlyDataAccepted is the advertised number of plaintext bytes of early
2597	// data that will be accepted. This value should be slightly below
2598	// kMaxEarlyDataSkipped in tls_record.c, which is measured in ciphertext.
2599	static const size_t kMaxEarlyDataAccepted = `14336`;
2600
2601	UniquePtr<CERT> ssl_cert_dup(CERT *cert);
2602	void ssl_cert_clear_certs(CERT *cert);
2603	bool ssl_set_cert(CERT *cert, UniquePtr<CRYPTO_BUFFER> buffer);
2604	bool ssl_is_key_type_supported(int key_type);
2605	// ssl_compare_public_and_private_key returns true if \|pubkey\| is the public
2606	// counterpart to \|privkey\|. Otherwise it returns false and pushes a helpful
2607	// message on the error queue.
2608	bool ssl_compare_public_and_private_key(const EVP_PKEY *pubkey,
2609	const EVP_PKEY *privkey);
2610	bool ssl_cert_check_private_key(const CERT cert, const* EVP_PKEY *privkey);
2611	int ssl_get_new_session(SSL_HANDSHAKE hs, int* is_server);
2612	int ssl_encrypt_ticket(SSL_HANDSHAKE hs, CBB out, const SSL_SESSION *session);
2613	int ssl_ctx_rotate_ticket_encryption_key(SSL_CTX *ctx);
2614
2615	// ssl_session_new returns a newly-allocated blank \|SSL_SESSION\| or nullptr on
2616	// error.
2617	UniquePtr<SSL_SESSION> ssl_session_new(const SSL_X509_METHOD *x509_method);
2618
2619	// ssl_hash_session_id returns a hash of \|session_id\|, suitable for a hash table
2620	// keyed on session IDs.
2621	uint32_t ssl_hash_session_id(Span<const uint8_t> session_id);
2622
2623	// SSL_SESSION_parse parses an \|SSL_SESSION\| from \|cbs\| and advances \|cbs\| over
2624	// the parsed data.
2625	OPENSSL_EXPORT UniquePtr<SSL_SESSION> SSL_SESSION_parse(
2626	CBS cbs, const* SSL_X509_METHOD x509_method, CRYPTO_BUFFER_POOL pool);
2627
2628	// ssl_session_serialize writes \|in\| to \|cbb\| as if it were serialising a
2629	// session for Session-ID resumption. It returns one on success and zero on
2630	// error.
2631	OPENSSL_EXPORT int ssl_session_serialize(const SSL_SESSION in, CBB cbb);
2632
2633	// ssl_session_is_context_valid returns one if \|session\|'s session ID context
2634	// matches the one set on \|hs\| and zero otherwise.
2635	int ssl_session_is_context_valid(const SSL_HANDSHAKE *hs,
2636	const SSL_SESSION *session);
2637
2638	// ssl_session_is_time_valid returns one if \|session\| is still valid and zero if
2639	// it has expired.
2640	int ssl_session_is_time_valid(const SSL ssl, const* SSL_SESSION *session);
2641
2642	// ssl_session_is_resumable returns one if \|session\| is resumable for \|hs\| and
2643	// zero otherwise.
2644	int ssl_session_is_resumable(const SSL_HANDSHAKE *hs,
2645	const SSL_SESSION *session);
2646
2647	// ssl_session_protocol_version returns the protocol version associated with
2648	// \|session\|. Note that despite the name, this is not the same as
2649	// \|SSL_SESSION_get_protocol_version\|. The latter is based on upstream's name.
2650	uint16_t ssl_session_protocol_version(const SSL_SESSION *session);
2651
2652	// ssl_session_get_digest returns the digest used in \|session\|.
2653	const EVP_MD ssl_session_get_digest(const* SSL_SESSION *session);
2654
2655	void ssl_set_session(SSL ssl, SSL_SESSION session);
2656
2657	// ssl_get_prev_session looks up the previous session based on \|client_hello\|.
2658	// On success, it sets \|out_session\| to the session or nullptr if none was*
2659	// found. If the session could not be looked up synchronously, it returns
2660	// \|ssl_hs_pending_session\| and should be called again. If a ticket could not be
2661	// decrypted immediately it returns \|ssl_hs_pending_ticket\| and should also
2662	// be called again. Otherwise, it returns \|ssl_hs_error\|.
2663	enum ssl_hs_wait_t ssl_get_prev_session(SSL_HANDSHAKE *hs,
2664	UniquePtr<SSL_SESSION> *out_session,
2665	bool *out_tickets_supported,
2666	bool *out_renew_ticket,
2667	const SSL_CLIENT_HELLO *client_hello);
2668
2669	// The following flags determine which parts of the session are duplicated.
2670	#define SSL_SESSION_DUP_AUTH_ONLY 0x0
2671	#define SSL_SESSION_INCLUDE_TICKET 0x1
2672	#define SSL_SESSION_INCLUDE_NONAUTH 0x2
2673	#define SSL_SESSION_DUP_ALL \
2674	(SSL_SESSION_INCLUDE_TICKET \| SSL_SESSION_INCLUDE_NONAUTH)
2675
2676	// SSL_SESSION_dup returns a newly-allocated \|SSL_SESSION\| with a copy of the
2677	// fields in \|session\| or nullptr on error. The new session is non-resumable and
2678	// must be explicitly marked resumable once it has been filled in.
2679	OPENSSL_EXPORT UniquePtr<SSL_SESSION> SSL_SESSION_dup(SSL_SESSION *session,
2680	int dup_flags);
2681
2682	// ssl_session_rebase_time updates \|session\|'s start time to the current time,
2683	// adjusting the timeout so the expiration time is unchanged.
2684	void ssl_session_rebase_time(SSL ssl, SSL_SESSION session);
2685
2686	// ssl_session_renew_timeout calls \|ssl_session_rebase_time\| and renews
2687	// \|session\|'s timeout to \|timeout\| (measured from the current time). The
2688	// renewal is clamped to the session's auth_timeout.
2689	void ssl_session_renew_timeout(SSL ssl, SSL_SESSION session,
2690	uint32_t timeout);
2691
2692	void ssl_update_cache(SSL_HANDSHAKE hs, int* mode);
2693
2694	void ssl_send_alert(SSL ssl, int* level, int desc);
2695	int ssl_send_alert_impl(SSL ssl, int* level, int desc);
2696	bool ssl3_get_message(const SSL ssl, SSLMessage out);
2697	ssl_open_record_t ssl3_open_handshake(SSL ssl, size_t out_consumed,
2698	uint8_t *out_alert, Span<uint8_t> in);
2699	void ssl3_next_message(SSL *ssl);
2700
2701	int ssl3_dispatch_alert(SSL *ssl);
2702	ssl_open_record_t ssl3_open_app_data(SSL ssl, Span<uint8_t> out,
2703	size_t out_consumed, uint8_t out_alert,
2704	Span<uint8_t> in);
2705	ssl_open_record_t ssl3_open_change_cipher_spec(SSL ssl, size_t out_consumed,
2706	uint8_t *out_alert,
2707	Span<uint8_t> in);
2708	int ssl3_write_app_data(SSL ssl, bool* out_needs_handshake, const* uint8_t *buf,
2709	int len);
2710
2711	bool ssl3_new(SSL *ssl);
2712	void ssl3_free(SSL *ssl);
2713
2714	bool ssl3_init_message(SSL ssl, CBB cbb, CBB *body, uint8_t type);
2715	bool ssl3_finish_message(SSL ssl, CBB cbb, Array<uint8_t> *out_msg);
2716	bool ssl3_add_message(SSL *ssl, Array<uint8_t> msg);
2717	bool ssl3_add_change_cipher_spec(SSL *ssl);
2718	int ssl3_flush_flight(SSL *ssl);
2719
2720	bool dtls1_init_message(SSL ssl, CBB cbb, CBB *body, uint8_t type);
2721	bool dtls1_finish_message(SSL ssl, CBB cbb, Array<uint8_t> *out_msg);
2722	bool dtls1_add_message(SSL *ssl, Array<uint8_t> msg);
2723	bool dtls1_add_change_cipher_spec(SSL *ssl);
2724	int dtls1_flush_flight(SSL *ssl);
2725
2726	// ssl_add_message_cbb finishes the handshake message in \|cbb\| and adds it to
2727	// the pending flight. It returns true on success and false on error.
2728	bool ssl_add_message_cbb(SSL ssl, CBB cbb);
2729
2730	// ssl_hash_message incorporates \|msg\| into the handshake hash. It returns true
2731	// on success and false on allocation failure.
2732	bool ssl_hash_message(SSL_HANDSHAKE hs, const* SSLMessage &msg);
2733
2734	ssl_open_record_t dtls1_open_app_data(SSL ssl, Span<uint8_t> out,
2735	size_t out_consumed, uint8_t out_alert,
2736	Span<uint8_t> in);
2737	ssl_open_record_t dtls1_open_change_cipher_spec(SSL ssl, size_t out_consumed,
2738	uint8_t *out_alert,
2739	Span<uint8_t> in);
2740
2741	int dtls1_write_app_data(SSL ssl, bool* *out_needs_handshake,
2742	const uint8_t buf, int* len);
2743
2744	// dtls1_write_record sends a record. It returns one on success and <= 0 on
2745	// error.
2746	int dtls1_write_record(SSL ssl, int* type, const uint8_t *buf, size_t len,
2747	enum dtls1_use_epoch_t use_epoch);
2748
2749	int dtls1_retransmit_outgoing_messages(SSL *ssl);
2750	bool dtls1_parse_fragment(CBS cbs, struct* hm_header_st *out_hdr,
2751	CBS *out_body);
2752	bool dtls1_check_timeout_num(SSL *ssl);
2753
2754	void dtls1_start_timer(SSL *ssl);
2755	void dtls1_stop_timer(SSL *ssl);
2756	bool dtls1_is_timer_expired(SSL *ssl);
2757	unsigned int dtls1_min_mtu(void);
2758
2759	bool dtls1_new(SSL *ssl);
2760	void dtls1_free(SSL *ssl);
2761
2762	bool dtls1_get_message(const SSL ssl, SSLMessage out);
2763	ssl_open_record_t dtls1_open_handshake(SSL ssl, size_t out_consumed,
2764	uint8_t *out_alert, Span<uint8_t> in);
2765	void dtls1_next_message(SSL *ssl);
2766	int dtls1_dispatch_alert(SSL *ssl);
2767
2768	// tls1_configure_aead configures either the read or write direction AEAD (as
2769	// determined by \|direction\|) using the keys generated by the TLS KDF. The
2770	// \|key_block_cache\| argument is used to store the generated key block, if
2771	// empty. Otherwise it's assumed that the key block is already contained within
2772	// it. Returns one on success or zero on error.
2773	int tls1_configure_aead(SSL *ssl, evp_aead_direction_t direction,
2774	Array<uint8_t> *key_block_cache,
2775	const SSL_CIPHER *cipher,
2776	Span<const uint8_t> iv_override);
2777
2778	int tls1_change_cipher_state(SSL_HANDSHAKE *hs, evp_aead_direction_t direction);
2779	int tls1_generate_master_secret(SSL_HANDSHAKE hs, uint8_t out,
2780	Span<const uint8_t> premaster);
2781
2782	// tls1_get_grouplist returns the locally-configured group preference list.
2783	Span<const uint16_t> tls1_get_grouplist(const SSL_HANDSHAKE *ssl);
2784
2785	// tls1_check_group_id returns whether \|group_id\| is consistent with locally-
2786	// configured group preferences.
2787	bool tls1_check_group_id(const SSL_HANDSHAKE *ssl, uint16_t group_id);
2788
2789	// tls1_get_shared_group sets \|out_group_id\| to the first preferred shared*
2790	// group between client and server preferences and returns true. If none may be
2791	// found, it returns false.
2792	bool tls1_get_shared_group(SSL_HANDSHAKE hs, uint16_t out_group_id);
2793
2794	// tls1_set_curves converts the array of NIDs in \|curves\| into a newly allocated
2795	// array of TLS group IDs. On success, the function returns true and writes the
2796	// array to \|out_group_ids\|. Otherwise, it returns false.*
2797	bool tls1_set_curves(Array<uint16_t> out_group_ids, Span<const* int> curves);
2798
2799	// tls1_set_curves_list converts the string of curves pointed to by \|curves\|
2800	// into a newly allocated array of TLS group IDs. On success, the function
2801	// returns true and writes the array to \|out_group_ids\|. Otherwise, it returns*
2802	// false.
2803	bool tls1_set_curves_list(Array<uint16_t> out_group_ids, const* char *curves);
2804
2805	// ssl_add_clienthello_tlsext writes ClientHello extensions to \|out\|. It returns
2806	// true on success and false on failure. The \|header_len\| argument is the length
2807	// of the ClientHello written so far and is used to compute the padding length.
2808	// (It does not include the record header.)
2809	bool ssl_add_clienthello_tlsext(SSL_HANDSHAKE hs, CBB out, size_t header_len);
2810
2811	bool ssl_add_serverhello_tlsext(SSL_HANDSHAKE hs, CBB out);
2812	bool ssl_parse_clienthello_tlsext(SSL_HANDSHAKE *hs,
2813	const SSL_CLIENT_HELLO *client_hello);
2814	bool ssl_parse_serverhello_tlsext(SSL_HANDSHAKE hs, CBS cbs);
2815
2816	#define tlsext_tick_md EVP_sha256
2817
2818	// ssl_process_ticket processes a session ticket from the client. It returns
2819	// one of:
2820	// \|ssl_ticket_aead_success\|: \|out_session\| is set to the parsed session and*
2821	// \|out_renew_ticket\| is set to whether the ticket should be renewed.*
2822	// \|ssl_ticket_aead_ignore_ticket\|: \|out_renew_ticket\| is set to whether a*
2823	// fresh ticket should be sent, but the given ticket cannot be used.
2824	// \|ssl_ticket_aead_retry\|: the ticket could not be immediately decrypted.
2825	// Retry later.
2826	// \|ssl_ticket_aead_error\|: an error occured that is fatal to the connection.
2827	enum ssl_ticket_aead_result_t ssl_process_ticket(
2828	SSL_HANDSHAKE hs, UniquePtr<SSL_SESSION> out_session,
2829	bool out_renew_ticket, Span<const* uint8_t> ticket,
2830	Span<const uint8_t> session_id);
2831
2832	// tls1_verify_channel_id processes \|msg\| as a Channel ID message, and verifies
2833	// the signature. If the key is valid, it saves the Channel ID and returns true.
2834	// Otherwise, it returns false.
2835	bool tls1_verify_channel_id(SSL_HANDSHAKE hs, const* SSLMessage &msg);
2836
2837	// tls1_write_channel_id generates a Channel ID message and puts the output in
2838	// \|cbb\|. \|ssl->channel_id_private\| must already be set before calling. This
2839	// function returns true on success and false on error.
2840	bool tls1_write_channel_id(SSL_HANDSHAKE hs, CBB cbb);
2841
2842	// tls1_channel_id_hash computes the hash to be signed by Channel ID and writes
2843	// it to \|out\|, which must contain at least \|EVP_MAX_MD_SIZE\| bytes. It returns
2844	// true on success and false on failure.
2845	bool tls1_channel_id_hash(SSL_HANDSHAKE hs, uint8_t out, size_t *out_len);
2846
2847	// tls1_record_handshake_hashes_for_channel_id records the current handshake
2848	// hashes in \|hs->new_session\| so that Channel ID resumptions can sign that
2849	// data.
2850	bool tls1_record_handshake_hashes_for_channel_id(SSL_HANDSHAKE *hs);
2851
2852	// ssl_do_channel_id_callback checks runs \|hs->ssl->ctx->channel_id_cb\| if
2853	// necessary. It returns true on success and false on fatal error. Note that, on
2854	// success, \|hs->ssl->channel_id_private\| may be unset, in which case the
2855	// operation should be retried later.
2856	bool ssl_do_channel_id_callback(SSL_HANDSHAKE *hs);
2857
2858	// ssl_can_write returns whether \|ssl\| is allowed to write.
2859	bool ssl_can_write(const SSL *ssl);
2860
2861	// ssl_can_read returns wheter \|ssl\| is allowed to read.
2862	bool ssl_can_read(const SSL *ssl);
2863
2864	void ssl_get_current_time(const SSL ssl, struct* OPENSSL_timeval *out_clock);
2865	void ssl_ctx_get_current_time(const SSL_CTX *ctx,
2866	struct OPENSSL_timeval *out_clock);
2867
2868	// ssl_reset_error_state resets state for \|SSL_get_error\|.
2869	void ssl_reset_error_state(SSL *ssl);
2870
2871	// ssl_set_read_error sets \|ssl\|'s read half into an error state, saving the
2872	// current state of the error queue.
2873	void ssl_set_read_error(SSL *ssl);
2874
2875	BSSL_NAMESPACE_END
2876
2877
2878	// Opaque C types.
2879	//
2880	// The following types are exported to C code as public typedefs, so they must
2881	// be defined outside of the namespace.
2882
2883	// ssl_method_st backs the public \|SSL_METHOD\| type. It is a compatibility
2884	// structure to support the legacy version-locked methods.
2885	struct ssl_method_st {
2886	// version, if non-zero, is the only protocol version acceptable to an
2887	// SSL_CTX initialized from this method.
2888	uint16_t version;
2889	// method is the underlying SSL_PROTOCOL_METHOD that initializes the
2890	// SSL_CTX.
2891	const bssl::SSL_PROTOCOL_METHOD *method;
2892	// x509_method contains pointers to functions that might deal with \|X509\|
2893	// compatibility, or might be a no-op, depending on the application.
2894	const bssl::SSL_X509_METHOD *x509_method;
2895	};
2896
2897	struct ssl_ctx_st {
2898	explicit ssl_ctx_st(const SSL_METHOD *ssl_method);
2899	ssl_ctx_st(const ssl_ctx_st &) = delete;
2900	ssl_ctx_st &operator=(const ssl_ctx_st &) = delete;
2901
2902	const bssl::SSL_PROTOCOL_METHOD method = nullptr*;
2903	const bssl::SSL_X509_METHOD x509_method = nullptr*;
2904
2905	// lock is used to protect various operations on this object.
2906	CRYPTO_MUTEX lock;
2907
2908	// conf_max_version is the maximum acceptable protocol version configured by
2909	// \|SSL_CTX_set_max_proto_version\|. Note this version is normalized in DTLS
2910	// and is further constrainted by \|SSL_OP_NO_\|.*
2911	uint16_t conf_max_version = `0`;
2912
2913	// conf_min_version is the minimum acceptable protocol version configured by
2914	// \|SSL_CTX_set_min_proto_version\|. Note this version is normalized in DTLS
2915	// and is further constrainted by \|SSL_OP_NO_\|.*
2916	uint16_t conf_min_version = `0`;
2917
2918	// quic_method is the method table corresponding to the QUIC hooks.
2919	const SSL_QUIC_METHOD quic_method = nullptr*;
2920
2921	bssl::UniquePtr<bssl::SSLCipherPreferenceList> cipher_list;
2922
2923	X509_STORE cert_store = nullptr*;
2924	LHASH_OF(SSL_SESSION) sessions = nullptr*;
2925	// Most session-ids that will be cached, default is
2926	// SSL_SESSION_CACHE_MAX_SIZE_DEFAULT. 0 is unlimited.
2927	unsigned long session_cache_size = SSL_SESSION_CACHE_MAX_SIZE_DEFAULT;
2928	SSL_SESSION session_cache_head = nullptr*;
2929	SSL_SESSION session_cache_tail = nullptr*;
2930
2931	// handshakes_since_cache_flush is the number of successful handshakes since
2932	// the last cache flush.
2933	int handshakes_since_cache_flush = `0`;
2934
2935	// This can have one of 2 values, ored together,
2936	// SSL_SESS_CACHE_CLIENT,
2937	// SSL_SESS_CACHE_SERVER,
2938	// Default is SSL_SESSION_CACHE_SERVER, which means only
2939	// SSL_accept which cache SSL_SESSIONS.
2940	int session_cache_mode = SSL_SESS_CACHE_SERVER;
2941
2942	// session_timeout is the default lifetime for new sessions in TLS 1.2 and
2943	// earlier, in seconds.
2944	uint32_t session_timeout = SSL_DEFAULT_SESSION_TIMEOUT;
2945
2946	// session_psk_dhe_timeout is the default lifetime for new sessions in TLS
2947	// 1.3, in seconds.
2948	uint32_t session_psk_dhe_timeout = SSL_DEFAULT_SESSION_PSK_DHE_TIMEOUT;
2949
2950	// If this callback is not null, it will be called each time a session id is
2951	// added to the cache. If this function returns 1, it means that the
2952	// callback will do a SSL_SESSION_free() when it has finished using it.
2953	// Otherwise, on 0, it means the callback has finished with it. If
2954	// remove_session_cb is not null, it will be called when a session-id is
2955	// removed from the cache. After the call, OpenSSL will SSL_SESSION_free()
2956	// it.
2957	int (new_session_cb)(SSL ssl, SSL_SESSION sess) = nullptr*;
2958	void (remove_session_cb)(SSL_CTX ctx, SSL_SESSION sess) = nullptr*;
2959	SSL_SESSION (get_session_cb)(SSL ssl, const* uint8_t data, int* len,
2960	int copy) = nullptr*;
2961
2962	CRYPTO_refcount_t references = `1`;
2963
2964	// if defined, these override the X509_verify_cert() calls
2965	int (app_verify_callback)(X509_STORE_CTX store_ctx, void arg) = nullptr*;
2966	void app_verify_arg = nullptr*;
2967
2968	ssl_verify_result_t (custom_verify_callback)(SSL ssl,
2969	uint8_t out_alert) = nullptr*;
2970
2971	// Default password callback.
2972	pem_password_cb default_passwd_callback = nullptr*;
2973
2974	// Default password callback user data.
2975	void default_passwd_callback_userdata = nullptr*;
2976
2977	// get client cert callback
2978	int (client_cert_cb)(SSL ssl, X509 **out_x509,
2979	EVP_PKEY out_pkey) = nullptr**;
2980
2981	// get channel id callback
2982	void (channel_id_cb)(SSL ssl, EVP_PKEY out_pkey) = nullptr**;
2983
2984	CRYPTO_EX_DATA ex_data;
2985
2986	// Default values used when no per-SSL value is defined follow
2987
2988	void (info_callback)(const* SSL ssl, int* type, int value) = nullptr;
2989
2990	// what we put in client cert requests
2991	bssl::UniquePtr<STACK_OF(CRYPTO_BUFFER)> client_CA;
2992
2993	// cached_x509_client_CA is a cache of parsed versions of the elements of
2994	// \|client_CA\|.
2995	STACK_OF(X509_NAME) cached_x509_client_CA = nullptr*;
2996
2997
2998	// Default values to use in SSL structures follow (these are copied by
2999	// SSL_new)
3000
3001	uint32_t options = `0`;
3002	// Disable the auto-chaining feature by default. wpa_supplicant relies on this
3003	// feature, but require callers opt into it.
3004	uint32_t mode = SSL_MODE_NO_AUTO_CHAIN;
3005	uint32_t max_cert_list = SSL_MAX_CERT_LIST_DEFAULT;
3006
3007	bssl::UniquePtr<bssl::CERT> cert;
3008
3009	// callback that allows applications to peek at protocol messages
3010	void (msg_callback)(int* write_p, int version, int content_type,
3011	const void buf, size_t len, SSL ssl,
3012	void arg) = nullptr*;
3013	void msg_callback_arg = nullptr*;
3014
3015	int verify_mode = SSL_VERIFY_NONE;
3016	int (default_verify_callback)(int* ok, X509_STORE_CTX *ctx) =
3017	nullptr; // called 'verify_callback' in the SSL
3018
3019	X509_VERIFY_PARAM param = nullptr*;
3020
3021	// select_certificate_cb is called before most ClientHello processing and
3022	// before the decision whether to resume a session is made. See
3023	// \|ssl_select_cert_result_t\| for details of the return values.
3024	ssl_select_cert_result_t (select_certificate_cb)(const* SSL_CLIENT_HELLO *) =
3025	nullptr;
3026
3027	// dos_protection_cb is called once the resumption decision for a ClientHello
3028	// has been made. It returns one to continue the handshake or zero to
3029	// abort.
3030	int (dos_protection_cb)(const* SSL_CLIENT_HELLO ) = nullptr*;
3031
3032	// Controls whether to verify certificates when resuming connections. They
3033	// were already verified when the connection was first made, so the default is
3034	// false. For now, this is only respected on clients, not servers.
3035	bool reverify_on_resume = false;
3036
3037	// Maximum amount of data to send in one fragment. actual record size can be
3038	// more than this due to padding and MAC overheads.
3039	uint16_t max_send_fragment = SSL3_RT_MAX_PLAIN_LENGTH;
3040
3041	// TLS extensions servername callback
3042	int (servername_callback)(SSL , int , void* ) = nullptr*;
3043	void servername_arg = nullptr*;
3044
3045	// RFC 4507 session ticket keys. \|ticket_key_current\| may be NULL before the
3046	// first handshake and \|ticket_key_prev\| may be NULL at any time.
3047	// Automatically generated ticket keys are rotated as needed at handshake
3048	// time. Hence, all access must be synchronized through \|lock\|.
3049	bssl::UniquePtr<bssl::TicketKey> ticket_key_current;
3050	bssl::UniquePtr<bssl::TicketKey> ticket_key_prev;
3051
3052	// Callback to support customisation of ticket key setting
3053	int (ticket_key_cb)(SSL ssl, uint8_t name, uint8_t iv,
3054	EVP_CIPHER_CTX ectx, HMAC_CTX hctx, int enc) = nullptr;
3055
3056	// Server-only: psk_identity_hint is the default identity hint to send in
3057	// PSK-based key exchanges.
3058	bssl::UniquePtr<char> psk_identity_hint;
3059
3060	unsigned (psk_client_callback)(SSL ssl, const char hint, char* *identity,
3061	unsigned max_identity_len, uint8_t *psk,
3062	unsigned max_psk_len) = nullptr;
3063	unsigned (psk_server_callback)(SSL ssl, const char identity, uint8_t psk,
3064	unsigned max_psk_len) = nullptr;
3065
3066
3067	// Next protocol negotiation information
3068	// (for experimental NPN extension).
3069
3070	// For a server, this contains a callback function by which the set of
3071	// advertised protocols can be provided.
3072	int (next_protos_advertised_cb)(SSL ssl, const uint8_t **out,
3073	unsigned out_len, void* arg) = nullptr*;
3074	void next_protos_advertised_cb_arg = nullptr*;
3075	// For a client, this contains a callback function that selects the
3076	// next protocol from the list provided by the server.
3077	int (next_proto_select_cb)(SSL ssl, uint8_t *out, uint8_t out_len,
3078	const uint8_t in, unsigned* in_len,
3079	void arg) = nullptr*;
3080	void next_proto_select_cb_arg = nullptr*;
3081
3082	// ALPN information
3083	// (we are in the process of transitioning from NPN to ALPN.)
3084
3085	// For a server, this contains a callback function that allows the
3086	// server to select the protocol for the connection.
3087	// out: on successful return, this must point to the raw protocol
3088	// name (without the length prefix).
3089	// outlen: on successful return, this contains the length of \|out\|.*
3090	// in: points to the client's list of supported protocols in
3091	// wire-format.
3092	// inlen: the length of \|in\|.
3093	int (alpn_select_cb)(SSL ssl, const uint8_t *out, uint8_t out_len,
3094	const uint8_t in, unsigned* in_len,
3095	void arg) = nullptr*;
3096	void alpn_select_cb_arg = nullptr*;
3097
3098	// For a client, this contains the list of supported protocols in wire
3099	// format.
3100	bssl::Array<uint8_t> alpn_client_proto_list;
3101
3102	// SRTP profiles we are willing to do from RFC 5764
3103	bssl::UniquePtr<STACK_OF(SRTP_PROTECTION_PROFILE)> srtp_profiles;
3104
3105	// Defined compression algorithms for certificates.
3106	bssl::UniquePtr<STACK_OF(CertCompressionAlg)> cert_compression_algs;
3107
3108	// Supported group values inherited by SSL structure
3109	bssl::Array<uint16_t> supported_group_list;
3110
3111	// The client's Channel ID private key.
3112	bssl::UniquePtr<EVP_PKEY> channel_id_private;
3113
3114	// keylog_callback, if not NULL, is the key logging callback. See
3115	// \|SSL_CTX_set_keylog_callback\|.
3116	void (keylog_callback)(const* SSL ssl, const* char line) = nullptr*;
3117
3118	// current_time_cb, if not NULL, is the function to use to get the current
3119	// time. It sets \|out_clock\| to the current time. The \|ssl\| argument is*
3120	// always NULL. See \|SSL_CTX_set_current_time_cb\|.
3121	void (current_time_cb)(const* SSL ssl, struct* timeval out_clock) = nullptr*;
3122
3123	// pool is used for all \|CRYPTO_BUFFER\|s in case we wish to share certificate
3124	// memory.
3125	CRYPTO_BUFFER_POOL pool = nullptr*;
3126
3127	// ticket_aead_method contains function pointers for opening and sealing
3128	// session tickets.
3129	const SSL_TICKET_AEAD_METHOD ticket_aead_method = nullptr*;
3130
3131	// legacy_ocsp_callback implements an OCSP-related callback for OpenSSL
3132	// compatibility.
3133	int (legacy_ocsp_callback)(SSL ssl, void arg) = nullptr*;
3134	void legacy_ocsp_callback_arg = nullptr*;
3135
3136	// verify_sigalgs, if not empty, is the set of signature algorithms
3137	// accepted from the peer in decreasing order of preference.
3138	bssl::Array<uint16_t> verify_sigalgs;
3139
3140	// retain_only_sha256_of_client_certs is true if we should compute the SHA256
3141	// hash of the peer's certificate and then discard it to save memory and
3142	// session space. Only effective on the server side.
3143	bool retain_only_sha256_of_client_certs : `1`;
3144
3145	// quiet_shutdown is true if the connection should not send a close_notify on
3146	// shutdown.
3147	bool quiet_shutdown : `1`;
3148
3149	// ocsp_stapling_enabled is only used by client connections and indicates
3150	// whether OCSP stapling will be requested.
3151	bool ocsp_stapling_enabled : `1`;
3152
3153	// If true, a client will request certificate timestamps.
3154	bool signed_cert_timestamps_enabled : `1`;
3155
3156	// channel_id_enabled is whether Channel ID is enabled. For a server, means
3157	// that we'll accept Channel IDs from clients. For a client, means that we'll
3158	// advertise support.
3159	bool channel_id_enabled : `1`;
3160
3161	// grease_enabled is whether draft-davidben-tls-grease-01 is enabled.
3162	bool grease_enabled : `1`;
3163
3164	// allow_unknown_alpn_protos is whether the client allows unsolicited ALPN
3165	// protocols from the peer.
3166	bool allow_unknown_alpn_protos : `1`;
3167
3168	// ed25519_enabled is whether Ed25519 is advertised in the handshake.
3169	bool ed25519_enabled : `1`;
3170
3171	// rsa_pss_rsae_certs_enabled is whether rsa_pss_rsae_ are supported by the*
3172	// certificate verifier.
3173	bool rsa_pss_rsae_certs_enabled : `1`;
3174
3175	// false_start_allowed_without_alpn is whether False Start (if
3176	// \|SSL_MODE_ENABLE_FALSE_START\| is enabled) is allowed without ALPN.
3177	bool false_start_allowed_without_alpn : `1`;
3178
3179	// ignore_tls13_downgrade is whether a connection should continue when the
3180	// server random signals a downgrade.
3181	bool ignore_tls13_downgrade:`1`;
3182
3183	// handoff indicates that a server should stop after receiving the
3184	// ClientHello and pause the handshake in such a way that \|SSL_get_error\|
3185	// returns \|SSL_HANDOFF\|.
3186	bool handoff : `1`;
3187
3188	// If enable_early_data is true, early data can be sent and accepted.
3189	bool enable_early_data : `1`;
3190
3191	// pq_experiment_signal indicates that an empty extension should be sent
3192	// (for clients) or echoed (for servers) to indicate participation in an
3193	// experiment of post-quantum key exchanges.
3194	bool pq_experiment_signal : `1`;
3195
3196	private:
3197	~ssl_ctx_st();
3198	friend void SSL_CTX_free(SSL_CTX *);
3199	};
3200
3201	struct ssl_st {
3202	explicit ssl_st(SSL_CTX *ctx_arg);
3203	ssl_st(const ssl_st &) = delete;
3204	ssl_st &operator=(const ssl_st &) = delete;
3205	~ssl_st();
3206
3207	// method is the method table corresponding to the current protocol (DTLS or
3208	// TLS).
3209	const bssl::SSL_PROTOCOL_METHOD method = nullptr*;
3210
3211	// config is a container for handshake configuration. Accesses to this field
3212	// should check for nullptr, since configuration may be shed after the
3213	// handshake completes. (If you have the \|SSL_HANDSHAKE\| object at hand, use
3214	// that instead, and skip the null check.)
3215	bssl::UniquePtr<bssl::SSL_CONFIG> config;
3216
3217	// version is the protocol version.
3218	uint16_t version = `0`;
3219
3220	uint16_t max_send_fragment = `0`;
3221
3222	// There are 2 BIO's even though they are normally both the same. This is so
3223	// data can be read and written to different handlers
3224
3225	bssl::UniquePtr<BIO> rbio; // used by SSL_read
3226	bssl::UniquePtr<BIO> wbio; // used by SSL_write
3227
3228	// do_handshake runs the handshake. On completion, it returns \|ssl_hs_ok\|.
3229	// Otherwise, it returns a value corresponding to what operation is needed to
3230	// progress.
3231	bssl::ssl_hs_wait_t (do_handshake)(bssl::SSL_HANDSHAKE hs) = nullptr;
3232
3233	bssl::SSL3_STATE s3 = nullptr; // TLS variables*
3234	bssl::DTLS1_STATE d1 = nullptr; // DTLS variables*
3235
3236	// callback that allows applications to peek at protocol messages
3237	void (msg_callback)(int* write_p, int version, int content_type,
3238	const void buf, size_t len, SSL ssl,
3239	void arg) = nullptr*;
3240	void msg_callback_arg = nullptr*;
3241
3242	// session info
3243
3244	// initial_timeout_duration_ms is the default DTLS timeout duration in
3245	// milliseconds. It's used to initialize the timer any time it's restarted.
3246	//
3247	// RFC 6347 states that implementations SHOULD use an initial timer value of 1
3248	// second.
3249	unsigned initial_timeout_duration_ms = `1000`;
3250
3251	// session is the configured session to be offered by the client. This session
3252	// is immutable.
3253	bssl::UniquePtr<SSL_SESSION> session;
3254
3255	void (info_callback)(const* SSL ssl, int* type, int value) = nullptr;
3256
3257	bssl::UniquePtr<SSL_CTX> ctx;
3258
3259	// session_ctx is the \|SSL_CTX\| used for the session cache and related
3260	// settings.
3261	bssl::UniquePtr<SSL_CTX> session_ctx;
3262
3263	// extra application data
3264	CRYPTO_EX_DATA ex_data;
3265
3266	uint32_t options = `0`; // protocol behaviour
3267	uint32_t mode = `0`; // API behaviour
3268	uint32_t max_cert_list = `0`;
3269	bssl::UniquePtr<char> hostname;
3270
3271	// quic_method is the method table corresponding to the QUIC hooks.
3272	const SSL_QUIC_METHOD quic_method = nullptr*;
3273
3274	// renegotiate_mode controls how peer renegotiation attempts are handled.
3275	ssl_renegotiate_mode_t renegotiate_mode = ssl_renegotiate_never;
3276
3277	// server is true iff the this SSL* is the server half. Note: before the SSL*
3278	// is initialized by either SSL_set_accept_state or SSL_set_connect_state,
3279	// the side is not determined. In this state, server is always false.
3280	bool server : `1`;
3281
3282	// quiet_shutdown is true if the connection should not send a close_notify on
3283	// shutdown.
3284	bool quiet_shutdown : `1`;
3285
3286	// If enable_early_data is true, early data can be sent and accepted.
3287	bool enable_early_data : `1`;
3288	};
3289
3290	struct ssl_session_st {
3291	explicit ssl_session_st(const bssl::SSL_X509_METHOD *method);
3292	ssl_session_st(const ssl_session_st &) = delete;
3293	ssl_session_st &operator=(const ssl_session_st &) = delete;
3294
3295	CRYPTO_refcount_t references = `1`;
3296
3297	// ssl_version is the (D)TLS version that established the session.
3298	uint16_t ssl_version = `0`;
3299
3300	// group_id is the ID of the ECDH group used to establish this session or zero
3301	// if not applicable or unknown.
3302	uint16_t group_id = `0`;
3303
3304	// peer_signature_algorithm is the signature algorithm used to authenticate
3305	// the peer, or zero if not applicable or unknown.
3306	uint16_t peer_signature_algorithm = `0`;
3307
3308	// master_key, in TLS 1.2 and below, is the master secret associated with the
3309	// session. In TLS 1.3 and up, it is the resumption secret.
3310	int master_key_length = `0`;
3311	uint8_t master_key[SSL_MAX_MASTER_KEY_LENGTH] = {`0`};
3312
3313	// session_id - valid?
3314	unsigned session_id_length = `0`;
3315	uint8_t session_id[SSL_MAX_SSL_SESSION_ID_LENGTH] = {`0`};
3316	// this is used to determine whether the session is being reused in
3317	// the appropriate context. It is up to the application to set this,
3318	// via SSL_new
3319	uint8_t sid_ctx_length = `0`;
3320	uint8_t sid_ctx[SSL_MAX_SID_CTX_LENGTH] = {`0`};
3321
3322	bssl::UniquePtr<char> psk_identity;
3323
3324	// certs contains the certificate chain from the peer, starting with the leaf
3325	// certificate.
3326	bssl::UniquePtr<STACK_OF(CRYPTO_BUFFER)> certs;
3327
3328	const bssl::SSL_X509_METHOD x509_method = nullptr*;
3329
3330	// x509_peer is the peer's certificate.
3331	X509 x509_peer = nullptr*;
3332
3333	// x509_chain is the certificate chain sent by the peer. NOTE: for historical
3334	// reasons, when a client (so the peer is a server), the chain includes
3335	// \|peer\|, but when a server it does not.
3336	STACK_OF(X509) x509_chain = nullptr*;
3337
3338	// x509_chain_without_leaf is a lazily constructed copy of \|x509_chain\| that
3339	// omits the leaf certificate. This exists because OpenSSL, historically,
3340	// didn't include the leaf certificate in the chain for a server, but did for
3341	// a client. The \|x509_chain\| always includes it and, if an API call requires
3342	// a chain without, it is stored here.
3343	STACK_OF(X509) x509_chain_without_leaf = nullptr*;
3344
3345	// verify_result is the result of certificate verification in the case of
3346	// non-fatal certificate errors.
3347	long verify_result = X509_V_ERR_INVALID_CALL;
3348
3349	// timeout is the lifetime of the session in seconds, measured from \|time\|.
3350	// This is renewable up to \|auth_timeout\|.
3351	uint32_t timeout = SSL_DEFAULT_SESSION_TIMEOUT;
3352
3353	// auth_timeout is the non-renewable lifetime of the session in seconds,
3354	// measured from \|time\|.
3355	uint32_t auth_timeout = SSL_DEFAULT_SESSION_TIMEOUT;
3356
3357	// time is the time the session was issued, measured in seconds from the UNIX
3358	// epoch.
3359	uint64_t time = `0`;
3360
3361	const SSL_CIPHER cipher = nullptr*;
3362
3363	CRYPTO_EX_DATA ex_data; // application specific data
3364
3365	// These are used to make removal of session-ids more efficient and to
3366	// implement a maximum cache size.
3367	SSL_SESSION prev = nullptr, next = nullptr;
3368
3369	bssl::Array<uint8_t> ticket;
3370
3371	bssl::UniquePtr<CRYPTO_BUFFER> signed_cert_timestamp_list;
3372
3373	// The OCSP response that came with the session.
3374	bssl::UniquePtr<CRYPTO_BUFFER> ocsp_response;
3375
3376	// peer_sha256 contains the SHA-256 hash of the peer's certificate if
3377	// \|peer_sha256_valid\| is true.
3378	uint8_t peer_sha256[SHA256_DIGEST_LENGTH] = {`0`};
3379
3380	// original_handshake_hash contains the handshake hash (either SHA-1+MD5 or
3381	// SHA-2, depending on TLS version) for the original, full handshake that
3382	// created a session. This is used by Channel IDs during resumption.
3383	uint8_t original_handshake_hash[EVP_MAX_MD_SIZE] = {`0`};
3384	uint8_t original_handshake_hash_len = `0`;
3385
3386	uint32_t ticket_lifetime_hint = `0`; // Session lifetime hint in seconds
3387
3388	uint32_t ticket_age_add = `0`;
3389
3390	// ticket_max_early_data is the maximum amount of data allowed to be sent as
3391	// early data. If zero, 0-RTT is disallowed.
3392	uint32_t ticket_max_early_data = `0`;
3393
3394	// early_alpn is the ALPN protocol from the initial handshake. This is only
3395	// stored for TLS 1.3 and above in order to enforce ALPN matching for 0-RTT
3396	// resumptions.
3397	bssl::Array<uint8_t> early_alpn;
3398
3399	// extended_master_secret is whether the master secret in this session was
3400	// generated using EMS and thus isn't vulnerable to the Triple Handshake
3401	// attack.
3402	bool extended_master_secret : `1`;
3403
3404	// peer_sha256_valid is whether \|peer_sha256\| is valid.
3405	bool peer_sha256_valid : `1`; // Non-zero if peer_sha256 is valid
3406
3407	// not_resumable is used to indicate that session resumption is disallowed.
3408	bool not_resumable : `1`;
3409
3410	// ticket_age_add_valid is whether \|ticket_age_add\| is valid.
3411	bool ticket_age_add_valid : `1`;
3412
3413	// is_server is whether this session was created by a server.
3414	bool is_server : `1`;
3415
3416	private:
3417	~ssl_session_st();
3418	friend void SSL_SESSION_free(SSL_SESSION *);
3419	};
3420
3421
3422	#endif // OPENSSL_HEADER_SSL_INTERNAL_H
3423

Browse the source code of engine/third_party/boringssl/src/ssl/internal.h