/* Copyright (C) 1995-1998 Eric Young ([email protected]) * All rights reserved. * * This package is an SSL implementation written * by Eric Young ([email protected]). * The implementation was written so as to conform with Netscapes SSL. * * This library is free for commercial and non-commercial use as long as * the following conditions are aheared to. The following conditions * apply to all code found in this distribution, be it the RC4, RSA, * lhash, DES, etc., code; not just the SSL code. The SSL documentation * included with this distribution is covered by the same copyright terms * except that the holder is Tim Hudson ([email protected]). * * Copyright remains Eric Young's, and as such any Copyright notices in * the code are not to be removed. * If this package is used in a product, Eric Young should be given attribution * as the author of the parts of the library used. * This can be in the form of a textual message at program startup or * in documentation (online or textual) provided with the package. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. All advertising materials mentioning features or use of this software * must display the following acknowledgement: * "This product includes cryptographic software written by * Eric Young ([email protected])" * The word 'cryptographic' can be left out if the rouines from the library * being used are not cryptographic related :-). * 4. If you include any Windows specific code (or a derivative thereof) from * the apps directory (application code) you must include an acknowledgement: * "This product includes software written by Tim Hudson ([email protected])" * * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * * The licence and distribution terms for any publically available version or * derivative of this code cannot be changed. i.e. this code cannot simply be * copied and put under another distribution licence * [including the GNU Public Licence.] */ /* ==================================================================== * Copyright (c) 1998-2007 The OpenSSL Project. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. All advertising materials mentioning features or use of this * software must display the following acknowledgment: * "This product includes software developed by the OpenSSL Project * for use in the OpenSSL Toolkit. (http://www.openssl.org/)" * * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to * endorse or promote products derived from this software without * prior written permission. For written permission, please contact * [email protected]. * * 5. Products derived from this software may not be called "OpenSSL" * nor may "OpenSSL" appear in their names without prior written * permission of the OpenSSL Project. * * 6. Redistributions of any form whatsoever must retain the following * acknowledgment: * "This product includes software developed by the OpenSSL Project * for use in the OpenSSL Toolkit (http://www.openssl.org/)" * * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE. * ==================================================================== * * This product includes cryptographic software written by Eric Young * ([email protected]). This product includes software written by Tim * Hudson ([email protected]). * */ /* ==================================================================== * Copyright 2002 Sun Microsystems, Inc. ALL RIGHTS RESERVED. * ECC cipher suite support in OpenSSL originally developed by * SUN MICROSYSTEMS, INC., and contributed to the OpenSSL project. */ /* ==================================================================== * Copyright 2005 Nokia. All rights reserved. * * The portions of the attached software ("Contribution") is developed by * Nokia Corporation and is licensed pursuant to the OpenSSL open source * license. * * The Contribution, originally written by Mika Kousa and Pasi Eronen of * Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites * support (see RFC 4279) to OpenSSL. * * No patent licenses or other rights except those expressly stated in * the OpenSSL open source license shall be deemed granted or received * expressly, by implication, estoppel, or otherwise. * * No assurances are provided by Nokia that the Contribution does not * infringe the patent or other intellectual property rights of any third * party or that the license provides you with all the necessary rights * to make use of the Contribution. * * THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN * ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA * SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY * OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR * OTHERWISE. */ #ifndef OPENSSL_HEADER_SSL_INTERNAL_H #define OPENSSL_HEADER_SSL_INTERNAL_H #include <openssl/base.h> #include <stdlib.h> #include <algorithm> #include <bitset> #include <initializer_list> #include <limits> #include <new> #include <type_traits> #include <utility> #include <openssl/aead.h> #include <openssl/curve25519.h> #include <openssl/err.h> #include <openssl/hpke.h> #include <openssl/lhash.h> #include <openssl/mem.h> #include <openssl/span.h> #include <openssl/ssl.h> #include <openssl/stack.h> #include "../crypto/err/internal.h" #include "../crypto/internal.h" #include "../crypto/lhash/internal.h" #if defined(OPENSSL_WINDOWS) // Windows defines struct timeval in winsock2.h. OPENSSL_MSVC_PRAGMA(warning(push, 3)) #include <winsock2.h> OPENSSL_MSVC_PRAGMA(warning(pop)) #else #include <sys/time.h> #endif BSSL_NAMESPACE_BEGIN struct SSL_CONFIG; struct SSL_HANDSHAKE; struct SSL_PROTOCOL_METHOD; struct SSL_X509_METHOD; // C++ utilities. // New behaves like |new| but uses |OPENSSL_malloc| for memory allocation. It // returns nullptr on allocation error. It only implements single-object // allocation and not new T[n]. // // Note: unlike |new|, this does not support non-public constructors. template <typename T, typename... Args> T *New(Args &&... args) { … } // Delete behaves like |delete| but uses |OPENSSL_free| to release memory. // // Note: unlike |delete| this does not support non-public destructors. template <typename T> void Delete(T *t) { … } // All types with kAllowUniquePtr set may be used with UniquePtr. Other types // may be C structs which require a |BORINGSSL_MAKE_DELETER| registration. namespace internal { DeleterImpl<T, std::enable_if_t<T::kAllowUniquePtr>>; } // namespace internal // MakeUnique behaves like |std::make_unique| but returns nullptr on allocation // error. template <typename T, typename... Args> UniquePtr<T> MakeUnique(Args &&... args) { … } // Array<T> is an owning array of elements of |T|. template <typename T> class Array { … }; // GrowableArray<T> is an array that owns elements of |T|, backed by an // Array<T>. When necessary, pushing will automatically trigger a resize. // // Note, for simplicity, this class currently differs from |std::vector| in that // |T| must be efficiently default-constructible. Allocated elements beyond the // end of the array are constructed and destructed. template <typename T> class GrowableArray { … }; // CBBFinishArray behaves like |CBB_finish| but stores the result in an Array. OPENSSL_EXPORT bool CBBFinishArray(CBB *cbb, Array<uint8_t> *out); // GetAllNames helps to implement |*_get_all_*_names| style functions. It // writes at most |max_out| string pointers to |out| and returns the number that // it would have liked to have written. The strings written consist of // |fixed_names_len| strings from |fixed_names| followed by |objects_len| // strings taken by projecting |objects| through |name|. template <typename T, typename Name> inline size_t GetAllNames(const char **out, size_t max_out, Span<const char *const> fixed_names, Name(T::*name), Span<const T> objects) { … } // RefCounted is a common base for ref-counted types. This is an instance of the // C++ curiously-recurring template pattern, so a type Foo must subclass // RefCounted<Foo>. It additionally must friend RefCounted<Foo> to allow calling // the destructor. template <typename Derived> class RefCounted { … }; // Protocol versions. // // Due to DTLS's historical wire version differences, we maintain two notions of // version. // // The "version" or "wire version" is the actual 16-bit value that appears on // the wire. It uniquely identifies a version and is also used at API // boundaries. The set of supported versions differs between TLS and DTLS. Wire // versions are opaque values and may not be compared numerically. // // The "protocol version" identifies the high-level handshake variant being // used. DTLS versions map to the corresponding TLS versions. Protocol versions // are sequential and may be compared numerically. // ssl_protocol_version_from_wire sets |*out| to the protocol version // corresponding to wire version |version| and returns true. If |version| is not // a valid TLS or DTLS version, it returns false. // // Note this simultaneously handles both DTLS and TLS. Use one of the // higher-level functions below for most operations. bool ssl_protocol_version_from_wire(uint16_t *out, uint16_t version); // ssl_get_version_range sets |*out_min_version| and |*out_max_version| to the // minimum and maximum enabled protocol versions, respectively. bool ssl_get_version_range(const SSL_HANDSHAKE *hs, uint16_t *out_min_version, uint16_t *out_max_version); // ssl_supports_version returns whether |hs| supports |version|. bool ssl_supports_version(const SSL_HANDSHAKE *hs, uint16_t version); // ssl_method_supports_version returns whether |method| supports |version|. bool ssl_method_supports_version(const SSL_PROTOCOL_METHOD *method, uint16_t version); // ssl_add_supported_versions writes the supported versions of |hs| to |cbb|, in // decreasing preference order. The version list is filtered to those whose // protocol version is at least |extra_min_version|. bool ssl_add_supported_versions(const SSL_HANDSHAKE *hs, CBB *cbb, uint16_t extra_min_version); // ssl_negotiate_version negotiates a common version based on |hs|'s preferences // and the peer preference list in |peer_versions|. On success, it returns true // and sets |*out_version| to the selected version. Otherwise, it returns false // and sets |*out_alert| to an alert to send. bool ssl_negotiate_version(SSL_HANDSHAKE *hs, uint8_t *out_alert, uint16_t *out_version, const CBS *peer_versions); // ssl_protocol_version returns |ssl|'s protocol version. It is an error to // call this function before the version is determined. uint16_t ssl_protocol_version(const SSL *ssl); // Cipher suites. BSSL_NAMESPACE_END struct ssl_cipher_st { … }; BSSL_NAMESPACE_BEGIN // Bits for |algorithm_mkey| (key exchange algorithm). #define SSL_kRSA … #define SSL_kECDHE … // SSL_kPSK is only set for plain PSK, not ECDHE_PSK. #define SSL_kPSK … #define SSL_kGENERIC … // Bits for |algorithm_auth| (server authentication). #define SSL_aRSA_SIGN … #define SSL_aRSA_DECRYPT … #define SSL_aECDSA … // SSL_aPSK is set for both PSK and ECDHE_PSK. #define SSL_aPSK … #define SSL_aGENERIC … #define SSL_aCERT … // Bits for |algorithm_enc| (symmetric encryption). #define SSL_3DES … #define SSL_AES128 … #define SSL_AES256 … #define SSL_AES128GCM … #define SSL_AES256GCM … #define SSL_CHACHA20POLY1305 … #define SSL_AES … // Bits for |algorithm_mac| (symmetric authentication). #define SSL_SHA1 … #define SSL_SHA256 … // SSL_AEAD is set for all AEADs. #define SSL_AEAD … // Bits for |algorithm_prf| (handshake digest). #define SSL_HANDSHAKE_MAC_DEFAULT … #define SSL_HANDSHAKE_MAC_SHA256 … #define SSL_HANDSHAKE_MAC_SHA384 … // SSL_MAX_MD_SIZE is size of the largest hash function used in TLS, SHA-384. #define SSL_MAX_MD_SIZE … // An SSLCipherPreferenceList contains a list of SSL_CIPHERs with equal- // preference groups. For TLS clients, the groups are moot because the server // picks the cipher and groups cannot be expressed on the wire. However, for // servers, the equal-preference groups allow the client's preferences to be // partially respected. (This only has an effect with // SSL_OP_CIPHER_SERVER_PREFERENCE). // // The equal-preference groups are expressed by grouping SSL_CIPHERs together. // All elements of a group have the same priority: no ordering is expressed // within a group. // // The values in |ciphers| are in one-to-one correspondence with // |in_group_flags|. (That is, sk_SSL_CIPHER_num(ciphers) is the number of // bytes in |in_group_flags|.) The bytes in |in_group_flags| are either 1, to // indicate that the corresponding SSL_CIPHER is not the last element of a // group, or 0 to indicate that it is. // // For example, if |in_group_flags| contains all zeros then that indicates a // traditional, fully-ordered preference. Every SSL_CIPHER is the last element // of the group (i.e. they are all in a one-element group). // // For a more complex example, consider: // ciphers: A B C D E F // in_group_flags: 1 1 0 0 1 0 // // That would express the following, order: // // A E // B -> D -> F // C struct SSLCipherPreferenceList { … }; // AllCiphers returns an array of all supported ciphers, sorted by id. Span<const SSL_CIPHER> AllCiphers(); // ssl_cipher_get_evp_aead sets |*out_aead| to point to the correct EVP_AEAD // object for |cipher| protocol version |version|. It sets |*out_mac_secret_len| // and |*out_fixed_iv_len| to the MAC key length and fixed IV length, // respectively. The MAC key length is zero except for legacy block and stream // ciphers. It returns true on success and false on error. bool ssl_cipher_get_evp_aead(const EVP_AEAD **out_aead, size_t *out_mac_secret_len, size_t *out_fixed_iv_len, const SSL_CIPHER *cipher, uint16_t version, bool is_dtls); // ssl_get_handshake_digest returns the |EVP_MD| corresponding to |version| and // |cipher|. const EVP_MD *ssl_get_handshake_digest(uint16_t version, const SSL_CIPHER *cipher); // ssl_create_cipher_list evaluates |rule_str|. It sets |*out_cipher_list| to a // newly-allocated |SSLCipherPreferenceList| containing the result. It returns // true on success and false on failure. If |strict| is true, nonsense will be // rejected. If false, nonsense will be silently ignored. An empty result is // considered an error regardless of |strict|. |has_aes_hw| indicates if the // list should be ordered based on having support for AES in hardware or not. bool ssl_create_cipher_list(UniquePtr<SSLCipherPreferenceList> *out_cipher_list, const bool has_aes_hw, const char *rule_str, bool strict); // ssl_cipher_auth_mask_for_key returns the mask of cipher |algorithm_auth| // values suitable for use with |key| in TLS 1.2 and below. |sign_ok| indicates // whether |key| may be used for signing. uint32_t ssl_cipher_auth_mask_for_key(const EVP_PKEY *key, bool sign_ok); // ssl_cipher_uses_certificate_auth returns whether |cipher| authenticates the // server and, optionally, the client with a certificate. bool ssl_cipher_uses_certificate_auth(const SSL_CIPHER *cipher); // ssl_cipher_requires_server_key_exchange returns whether |cipher| requires a // ServerKeyExchange message. // // This function may return false while still allowing |cipher| an optional // ServerKeyExchange. This is the case for plain PSK ciphers. bool ssl_cipher_requires_server_key_exchange(const SSL_CIPHER *cipher); // ssl_cipher_get_record_split_len, for TLS 1.0 CBC mode ciphers, returns the // length of an encrypted 1-byte record, for use in record-splitting. Otherwise // it returns zero. size_t ssl_cipher_get_record_split_len(const SSL_CIPHER *cipher); // ssl_choose_tls13_cipher returns an |SSL_CIPHER| corresponding with the best // available from |cipher_suites| compatible with |version| and |policy|. It // returns NULL if there isn't a compatible cipher. |has_aes_hw| indicates if // the choice should be made as if support for AES in hardware is available. const SSL_CIPHER *ssl_choose_tls13_cipher(CBS cipher_suites, bool has_aes_hw, uint16_t version, enum ssl_compliance_policy_t policy); // ssl_tls13_cipher_meets_policy returns true if |cipher_id| is acceptable given // |policy|. bool ssl_tls13_cipher_meets_policy(uint16_t cipher_id, enum ssl_compliance_policy_t policy); // ssl_cipher_is_deprecated returns true if |cipher| is deprecated. OPENSSL_EXPORT bool ssl_cipher_is_deprecated(const SSL_CIPHER *cipher); // Transcript layer. // SSLTranscript maintains the handshake transcript as a combination of a // buffer and running hash. class SSLTranscript { … }; // tls1_prf computes the PRF function for |ssl|. It fills |out|, using |secret| // as the secret and |label| as the label. |seed1| and |seed2| are concatenated // to form the seed parameter. It returns true on success and false on failure. bool tls1_prf(const EVP_MD *digest, Span<uint8_t> out, Span<const uint8_t> secret, Span<const char> label, Span<const uint8_t> seed1, Span<const uint8_t> seed2); // Encryption layer. // SSLAEADContext contains information about an AEAD that is being used to // encrypt an SSL connection. class SSLAEADContext { … }; // DTLS replay bitmap. // DTLS1_BITMAP maintains a sliding window of 64 sequence numbers to detect // replayed packets. It should be initialized by zeroing every field. struct DTLS1_BITMAP { … }; // reconstruct_seqnum takes the low order bits of a record sequence number from // the wire and reconstructs the full sequence number. It does so using the // algorithm described in section 4.2.2 of RFC 9147, where |wire_seq| is the // low bits of the sequence number as seen on the wire, |seq_mask| is a bitmask // of 8 or 16 1 bits corresponding to the length of the sequence number on the // wire, and |max_valid_seqnum| is the largest sequence number of a record // successfully deprotected in this epoch. This function returns the sequence // number that is numerically closest to one plus |max_valid_seqnum| that when // bitwise and-ed with |seq_mask| equals |wire_seq|. OPENSSL_EXPORT uint64_t reconstruct_seqnum(uint16_t wire_seq, uint64_t seq_mask, uint64_t max_valid_seqnum); // Record layer. // ssl_record_prefix_len returns the length of the prefix before the ciphertext // of a record for |ssl|. // // TODO(davidben): Expose this as part of public API once the high-level // buffer-free APIs are available. size_t ssl_record_prefix_len(const SSL *ssl); enum ssl_open_record_t { … }; // tls_open_record decrypts a record from |in| in-place. // // If the input did not contain a complete record, it returns // |ssl_open_record_partial|. It sets |*out_consumed| to the total number of // bytes necessary. It is guaranteed that a successful call to |tls_open_record| // will consume at least that many bytes. // // Otherwise, it sets |*out_consumed| to the number of bytes of input // consumed. Note that input may be consumed on all return codes if a record was // decrypted. // // On success, it returns |ssl_open_record_success|. It sets |*out_type| to the // record type and |*out| to the record body in |in|. Note that |*out| may be // empty. // // If a record was successfully processed but should be discarded, it returns // |ssl_open_record_discard|. // // If a record was successfully processed but is a close_notify, it returns // |ssl_open_record_close_notify|. // // On failure or fatal alert, it returns |ssl_open_record_error| and sets // |*out_alert| to an alert to emit, or zero if no alert should be emitted. enum ssl_open_record_t tls_open_record(SSL *ssl, uint8_t *out_type, Span<uint8_t> *out, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); // dtls_open_record implements |tls_open_record| for DTLS. It only returns // |ssl_open_record_partial| if |in| was empty and sets |*out_consumed| to // zero. The caller should read one packet and try again. enum ssl_open_record_t dtls_open_record(SSL *ssl, uint8_t *out_type, Span<uint8_t> *out, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); // ssl_needs_record_splitting returns one if |ssl|'s current outgoing cipher // state needs record-splitting and zero otherwise. bool ssl_needs_record_splitting(const SSL *ssl); // tls_seal_record seals a new record of type |type| and body |in| and writes it // to |out|. At most |max_out| bytes will be written. It returns true on success // and false on error. If enabled, |tls_seal_record| implements TLS 1.0 CBC // 1/n-1 record splitting and may write two records concatenated. // // For a large record, the bulk of the ciphertext will begin // |tls_seal_align_prefix_len| bytes into out. Aligning |out| appropriately may // improve performance. It writes at most |in_len| + |SSL_max_seal_overhead| // bytes to |out|. // // |in| and |out| may not alias. bool tls_seal_record(SSL *ssl, uint8_t *out, size_t *out_len, size_t max_out, uint8_t type, const uint8_t *in, size_t in_len); // dtls_record_header_write_len returns the length of the record header that // will be written at |epoch|. size_t dtls_record_header_write_len(const SSL *ssl, uint16_t epoch); // dtls_max_seal_overhead returns the maximum overhead, in bytes, of sealing a // record. size_t dtls_max_seal_overhead(const SSL *ssl, uint16_t epoch); // dtls_seal_prefix_len returns the number of bytes of prefix to reserve in // front of the plaintext when sealing a record in-place. size_t dtls_seal_prefix_len(const SSL *ssl, uint16_t epoch); // dtls_seal_record implements |tls_seal_record| for DTLS. |epoch| selects which // epoch's cipher state to use. Unlike |tls_seal_record|, |in| and |out| may // alias but, if they do, |in| must be exactly |dtls_seal_prefix_len| bytes // ahead of |out|. bool dtls_seal_record(SSL *ssl, uint8_t *out, size_t *out_len, size_t max_out, uint8_t type, const uint8_t *in, size_t in_len, uint16_t epoch); // ssl_process_alert processes |in| as an alert and updates |ssl|'s shutdown // state. It returns one of |ssl_open_record_discard|, |ssl_open_record_error|, // |ssl_open_record_close_notify|, or |ssl_open_record_fatal_alert| as // appropriate. enum ssl_open_record_t ssl_process_alert(SSL *ssl, uint8_t *out_alert, Span<const uint8_t> in); // Private key operations. // ssl_private_key_* perform the corresponding operation on // |SSL_PRIVATE_KEY_METHOD|. If there is a custom private key configured, they // call the corresponding function or |complete| depending on whether there is a // pending operation. Otherwise, they implement the operation with // |EVP_PKEY|. enum ssl_private_key_result_t ssl_private_key_sign( SSL_HANDSHAKE *hs, uint8_t *out, size_t *out_len, size_t max_out, uint16_t sigalg, Span<const uint8_t> in); enum ssl_private_key_result_t ssl_private_key_decrypt(SSL_HANDSHAKE *hs, uint8_t *out, size_t *out_len, size_t max_out, Span<const uint8_t> in); // ssl_pkey_supports_algorithm returns whether |pkey| may be used to sign // |sigalg|. bool ssl_pkey_supports_algorithm(const SSL *ssl, EVP_PKEY *pkey, uint16_t sigalg, bool is_verify); // ssl_public_key_verify verifies that the |signature| is valid for the public // key |pkey| and input |in|, using the signature algorithm |sigalg|. bool ssl_public_key_verify(SSL *ssl, Span<const uint8_t> signature, uint16_t sigalg, EVP_PKEY *pkey, Span<const uint8_t> in); // Key shares. // SSLKeyShare abstracts over KEM-like constructions, for use with TLS 1.2 ECDHE // cipher suites and the TLS 1.3 key_share extension. // // TODO(davidben): This class is named SSLKeyShare after the TLS 1.3 key_share // extension, but it really implements a KEM abstraction. Additionally, we use // the same type for Encap, which is a one-off, stateless operation, as Generate // and Decap. Slightly tidier would be for Generate to return a new SSLKEMKey // (or we introduce EVP_KEM and EVP_KEM_KEY), with a Decap method, and for Encap // to be static function. class SSLKeyShare { … }; struct NamedGroup { … }; // NamedGroups returns all supported groups. Span<const NamedGroup> NamedGroups(); // ssl_nid_to_group_id looks up the group corresponding to |nid|. On success, it // sets |*out_group_id| to the group ID and returns true. Otherwise, it returns // false. bool ssl_nid_to_group_id(uint16_t *out_group_id, int nid); // ssl_name_to_group_id looks up the group corresponding to the |name| string of // length |len|. On success, it sets |*out_group_id| to the group ID and returns // true. Otherwise, it returns false. bool ssl_name_to_group_id(uint16_t *out_group_id, const char *name, size_t len); // ssl_group_id_to_nid returns the NID corresponding to |group_id| or // |NID_undef| if unknown. int ssl_group_id_to_nid(uint16_t group_id); // Handshake messages. struct SSLMessage { … }; // SSL_MAX_HANDSHAKE_FLIGHT is the number of messages, including // ChangeCipherSpec, in the longest handshake flight. Currently this is the // client's second leg in a full handshake when client certificates, NPN, and // Channel ID, are all enabled. #define SSL_MAX_HANDSHAKE_FLIGHT … extern const uint8_t kHelloRetryRequest[SSL3_RANDOM_SIZE]; extern const uint8_t kTLS12DowngradeRandom[8]; extern const uint8_t kTLS13DowngradeRandom[8]; extern const uint8_t kJDK11DowngradeRandom[8]; // ssl_max_handshake_message_len returns the maximum number of bytes permitted // in a handshake message for |ssl|. size_t ssl_max_handshake_message_len(const SSL *ssl); // tls_can_accept_handshake_data returns whether |ssl| is able to accept more // data into handshake buffer. bool tls_can_accept_handshake_data(const SSL *ssl, uint8_t *out_alert); // tls_has_unprocessed_handshake_data returns whether there is buffered // handshake data that has not been consumed by |get_message|. bool tls_has_unprocessed_handshake_data(const SSL *ssl); // tls_append_handshake_data appends |data| to the handshake buffer. It returns // true on success and false on allocation failure. bool tls_append_handshake_data(SSL *ssl, Span<const uint8_t> data); // dtls_has_unprocessed_handshake_data behaves like // |tls_has_unprocessed_handshake_data| for DTLS. bool dtls_has_unprocessed_handshake_data(const SSL *ssl); // tls_flush_pending_hs_data flushes any handshake plaintext data. bool tls_flush_pending_hs_data(SSL *ssl); struct DTLS_OUTGOING_MESSAGE { … }; // dtls_clear_outgoing_messages releases all buffered outgoing messages. void dtls_clear_outgoing_messages(SSL *ssl); // Callbacks. // ssl_do_info_callback calls |ssl|'s info callback, if set. void ssl_do_info_callback(const SSL *ssl, int type, int value); // ssl_do_msg_callback calls |ssl|'s message callback, if set. void ssl_do_msg_callback(const SSL *ssl, int is_write, int content_type, Span<const uint8_t> in); // Transport buffers. class SSLBuffer { … }; // ssl_read_buffer_extend_to extends the read buffer to the desired length. For // TLS, it reads to the end of the buffer until the buffer is |len| bytes // long. For DTLS, it reads a new packet and ignores |len|. It returns one on // success, zero on EOF, and a negative number on error. // // It is an error to call |ssl_read_buffer_extend_to| in DTLS when the buffer is // non-empty. int ssl_read_buffer_extend_to(SSL *ssl, size_t len); // ssl_handle_open_record handles the result of passing |ssl->s3->read_buffer| // to a record-processing function. If |ret| is a success or if the caller // should retry, it returns one and sets |*out_retry|. Otherwise, it returns <= // 0. int ssl_handle_open_record(SSL *ssl, bool *out_retry, ssl_open_record_t ret, size_t consumed, uint8_t alert); // ssl_write_buffer_flush flushes the write buffer to the transport. It returns // one on success and <= 0 on error. For DTLS, whether or not the write // succeeds, the write buffer will be cleared. int ssl_write_buffer_flush(SSL *ssl); // Certificate functions. // ssl_parse_cert_chain parses a certificate list from |cbs| in the format used // by a TLS Certificate message. On success, it advances |cbs| and returns // true. Otherwise, it returns false and sets |*out_alert| to an alert to send // to the peer. // // If the list is non-empty then |*out_chain| and |*out_pubkey| will be set to // the certificate chain and the leaf certificate's public key // respectively. Otherwise, both will be set to nullptr. // // If the list is non-empty and |out_leaf_sha256| is non-NULL, it writes the // SHA-256 hash of the leaf to |out_leaf_sha256|. bool ssl_parse_cert_chain(uint8_t *out_alert, UniquePtr<STACK_OF(CRYPTO_BUFFER)> *out_chain, UniquePtr<EVP_PKEY> *out_pubkey, uint8_t *out_leaf_sha256, CBS *cbs, CRYPTO_BUFFER_POOL *pool); enum ssl_key_usage_t { … }; // ssl_cert_check_key_usage parses the DER-encoded, X.509 certificate in |in| // and returns true if doesn't specify a key usage or, if it does, if it // includes |bit|. Otherwise it pushes to the error queue and returns false. OPENSSL_EXPORT bool ssl_cert_check_key_usage(const CBS *in, enum ssl_key_usage_t bit); // ssl_cert_parse_pubkey extracts the public key from the DER-encoded, X.509 // certificate in |in|. It returns an allocated |EVP_PKEY| or else returns // nullptr and pushes to the error queue. UniquePtr<EVP_PKEY> ssl_cert_parse_pubkey(const CBS *in); // ssl_parse_client_CA_list parses a CA list from |cbs| in the format used by a // TLS CertificateRequest message. On success, it returns a newly-allocated // |CRYPTO_BUFFER| list and advances |cbs|. Otherwise, it returns nullptr and // sets |*out_alert| to an alert to send to the peer. UniquePtr<STACK_OF(CRYPTO_BUFFER)> ssl_parse_client_CA_list(SSL *ssl, uint8_t *out_alert, CBS *cbs); // ssl_has_client_CAs returns there are configured CAs. bool ssl_has_client_CAs(const SSL_CONFIG *cfg); // ssl_add_client_CA_list adds the configured CA list to |cbb| in the format // used by a TLS CertificateRequest message. It returns true on success and // false on error. bool ssl_add_client_CA_list(SSL_HANDSHAKE *hs, CBB *cbb); // ssl_check_leaf_certificate returns one if |pkey| and |leaf| are suitable as // a server's leaf certificate for |hs|. Otherwise, it returns zero and pushes // an error on the error queue. bool ssl_check_leaf_certificate(SSL_HANDSHAKE *hs, EVP_PKEY *pkey, const CRYPTO_BUFFER *leaf); // TLS 1.3 key derivation. // tls13_init_key_schedule initializes the handshake hash and key derivation // state, and incorporates the PSK. The cipher suite and PRF hash must have been // selected at this point. It returns true on success and false on error. bool tls13_init_key_schedule(SSL_HANDSHAKE *hs, Span<const uint8_t> psk); // tls13_init_early_key_schedule initializes the handshake hash and key // derivation state from |session| for use with 0-RTT. It returns one on success // and zero on error. bool tls13_init_early_key_schedule(SSL_HANDSHAKE *hs, const SSL_SESSION *session); // tls13_advance_key_schedule incorporates |in| into the key schedule with // HKDF-Extract. It returns true on success and false on error. bool tls13_advance_key_schedule(SSL_HANDSHAKE *hs, Span<const uint8_t> in); // tls13_set_traffic_key sets the read or write traffic keys to // |traffic_secret|. The version and cipher suite are determined from |session|. // It returns true on success and false on error. bool tls13_set_traffic_key(SSL *ssl, enum ssl_encryption_level_t level, enum evp_aead_direction_t direction, const SSL_SESSION *session, Span<const uint8_t> traffic_secret); // tls13_derive_early_secret derives the early traffic secret. It returns true // on success and false on error. bool tls13_derive_early_secret(SSL_HANDSHAKE *hs); // tls13_derive_handshake_secrets derives the handshake traffic secret. It // returns true on success and false on error. bool tls13_derive_handshake_secrets(SSL_HANDSHAKE *hs); // tls13_rotate_traffic_key derives the next read or write traffic secret. It // returns true on success and false on error. bool tls13_rotate_traffic_key(SSL *ssl, enum evp_aead_direction_t direction); // tls13_derive_application_secrets derives the initial application data traffic // and exporter secrets based on the handshake transcripts and |master_secret|. // It returns true on success and false on error. bool tls13_derive_application_secrets(SSL_HANDSHAKE *hs); // tls13_derive_resumption_secret derives the |resumption_secret|. bool tls13_derive_resumption_secret(SSL_HANDSHAKE *hs); // tls13_export_keying_material provides an exporter interface to use the // |exporter_secret|. bool tls13_export_keying_material(SSL *ssl, Span<uint8_t> out, Span<const uint8_t> secret, Span<const char> label, Span<const uint8_t> context); // tls13_finished_mac calculates the MAC of the handshake transcript to verify // the integrity of the Finished message, and stores the result in |out| and // length in |out_len|. |is_server| is true if this is for the Server Finished // and false for the Client Finished. bool tls13_finished_mac(SSL_HANDSHAKE *hs, uint8_t *out, size_t *out_len, bool is_server); // tls13_derive_session_psk calculates the PSK for this session based on the // resumption master secret and |nonce|. It returns true on success, and false // on failure. bool tls13_derive_session_psk(SSL_SESSION *session, Span<const uint8_t> nonce, bool is_dtls); // tls13_write_psk_binder calculates the PSK binder value over |transcript| and // |msg|, and replaces the last bytes of |msg| with the resulting value. It // returns true on success, and false on failure. If |out_binder_len| is // non-NULL, it sets |*out_binder_len| to the length of the value computed. bool tls13_write_psk_binder(const SSL_HANDSHAKE *hs, const SSLTranscript &transcript, Span<uint8_t> msg, size_t *out_binder_len); // tls13_verify_psk_binder verifies that the handshake transcript, truncated up // to the binders has a valid signature using the value of |session|'s // resumption secret. It returns true on success, and false on failure. bool tls13_verify_psk_binder(const SSL_HANDSHAKE *hs, const SSL_SESSION *session, const SSLMessage &msg, CBS *binders); // Encrypted ClientHello. struct ECHConfig { … }; class ECHServerConfig { … }; enum ssl_client_hello_type_t { … }; // ECH_CLIENT_* are types for the ClientHello encrypted_client_hello extension. #define ECH_CLIENT_OUTER … #define ECH_CLIENT_INNER … // ssl_decode_client_hello_inner recovers the full ClientHelloInner from the // EncodedClientHelloInner |encoded_client_hello_inner| by replacing its // outer_extensions extension with the referenced extensions from the // ClientHelloOuter |client_hello_outer|. If successful, it writes the recovered // ClientHelloInner to |out_client_hello_inner|. It returns true on success and // false on failure. // // This function is exported for fuzzing. OPENSSL_EXPORT bool ssl_decode_client_hello_inner( SSL *ssl, uint8_t *out_alert, Array<uint8_t> *out_client_hello_inner, Span<const uint8_t> encoded_client_hello_inner, const SSL_CLIENT_HELLO *client_hello_outer); // ssl_client_hello_decrypt attempts to decrypt and decode the |payload|. It // writes the result to |*out|. |payload| must point into |client_hello_outer|. // It returns true on success and false on error. On error, it sets // |*out_is_decrypt_error| to whether the failure was due to a bad ciphertext. bool ssl_client_hello_decrypt(SSL_HANDSHAKE *hs, uint8_t *out_alert, bool *out_is_decrypt_error, Array<uint8_t> *out, const SSL_CLIENT_HELLO *client_hello_outer, Span<const uint8_t> payload); #define ECH_CONFIRMATION_SIGNAL_LEN … // ssl_ech_confirmation_signal_hello_offset returns the offset of the ECH // confirmation signal in a ServerHello message, including the handshake header. size_t ssl_ech_confirmation_signal_hello_offset(const SSL *ssl); // ssl_ech_accept_confirmation computes the server's ECH acceptance signal, // writing it to |out|. The transcript portion is the concatenation of // |transcript| with |msg|. The |ECH_CONFIRMATION_SIGNAL_LEN| bytes from // |offset| in |msg| are replaced with zeros before hashing. This function // returns true on success, and false on failure. bool ssl_ech_accept_confirmation(const SSL_HANDSHAKE *hs, Span<uint8_t> out, Span<const uint8_t> client_random, const SSLTranscript &transcript, bool is_hrr, Span<const uint8_t> msg, size_t offset); // ssl_is_valid_ech_public_name returns true if |public_name| is a valid ECH // public name and false otherwise. It is exported for testing. OPENSSL_EXPORT bool ssl_is_valid_ech_public_name( Span<const uint8_t> public_name); // ssl_is_valid_ech_config_list returns true if |ech_config_list| is a valid // ECHConfigList structure and false otherwise. bool ssl_is_valid_ech_config_list(Span<const uint8_t> ech_config_list); // ssl_select_ech_config selects an ECHConfig and associated parameters to offer // on the client and updates |hs|. It returns true on success, whether an // ECHConfig was found or not, and false on internal error. On success, the // encapsulated key is written to |out_enc| and |*out_enc_len| is set to the // number of bytes written. If the function did not select an ECHConfig, the // encapsulated key is the empty string. bool ssl_select_ech_config(SSL_HANDSHAKE *hs, Span<uint8_t> out_enc, size_t *out_enc_len); // ssl_ech_extension_body_length returns the length of the body of a ClientHello // ECH extension that encrypts |in_len| bytes with |aead| and an 'enc' value of // length |enc_len|. The result does not include the four-byte extension header. size_t ssl_ech_extension_body_length(const EVP_HPKE_AEAD *aead, size_t enc_len, size_t in_len); // ssl_encrypt_client_hello constructs a new ClientHelloInner, adds it to the // inner transcript, and encrypts for inclusion in the ClientHelloOuter. |enc| // is the encapsulated key to include in the extension. It returns true on // success and false on error. If not offering ECH, |enc| is ignored and the // function will compute a GREASE ECH extension if necessary, and otherwise // return success while doing nothing. // // Encrypting the ClientHelloInner incorporates all extensions in the // ClientHelloOuter, so all other state necessary for |ssl_add_client_hello| // must already be computed. bool ssl_encrypt_client_hello(SSL_HANDSHAKE *hs, Span<const uint8_t> enc); // Credentials. enum class SSLCredentialType { … }; BSSL_NAMESPACE_END // SSL_CREDENTIAL is exported to C, so it must be defined outside the namespace. struct ssl_credential_st : public bssl::RefCounted<ssl_credential_st> { … }; BSSL_NAMESPACE_BEGIN // ssl_get_credential_list computes |hs|'s credential list. On success, it // writes it to |*out| and returns true. Otherwise, it returns false. The // credential list may be empty, in which case this function will successfully // return an empty array. // // The pointers in the result are only valid until |hs| is next mutated. bool ssl_get_credential_list(SSL_HANDSHAKE *hs, Array<SSL_CREDENTIAL *> *out); // Handshake functions. enum ssl_hs_wait_t { … }; enum ssl_grease_index_t { … }; enum tls12_server_hs_state_t { … }; enum tls13_server_hs_state_t { … }; // handback_t lists the points in the state machine where a handback can occur. // These are the different points at which key material is no longer needed. enum handback_t { … }; // SSL_HANDSHAKE_HINTS contains handshake hints for a connection. See // |SSL_request_handshake_hints| and related functions. struct SSL_HANDSHAKE_HINTS { … }; struct SSL_HANDSHAKE { … }; // kMaxTickets is the maximum number of tickets to send immediately after the // handshake. We use a one-byte ticket nonce, and there is no point in sending // so many tickets. constexpr size_t kMaxTickets = …; UniquePtr<SSL_HANDSHAKE> ssl_handshake_new(SSL *ssl); // ssl_check_message_type checks if |msg| has type |type|. If so it returns // one. Otherwise, it sends an alert and returns zero. bool ssl_check_message_type(SSL *ssl, const SSLMessage &msg, int type); // ssl_run_handshake runs the TLS handshake. It returns one on success and <= 0 // on error. It sets |out_early_return| to one if we've completed the handshake // early. int ssl_run_handshake(SSL_HANDSHAKE *hs, bool *out_early_return); // The following are implementations of |do_handshake| for the client and // server. enum ssl_hs_wait_t ssl_client_handshake(SSL_HANDSHAKE *hs); enum ssl_hs_wait_t ssl_server_handshake(SSL_HANDSHAKE *hs); enum ssl_hs_wait_t tls13_client_handshake(SSL_HANDSHAKE *hs); enum ssl_hs_wait_t tls13_server_handshake(SSL_HANDSHAKE *hs); // The following functions return human-readable representations of the TLS // handshake states for debugging. const char *ssl_client_handshake_state(SSL_HANDSHAKE *hs); const char *ssl_server_handshake_state(SSL_HANDSHAKE *hs); const char *tls13_client_handshake_state(SSL_HANDSHAKE *hs); const char *tls13_server_handshake_state(SSL_HANDSHAKE *hs); // tls13_add_key_update queues a KeyUpdate message on |ssl|. The // |update_requested| argument must be one of |SSL_KEY_UPDATE_REQUESTED| or // |SSL_KEY_UPDATE_NOT_REQUESTED|. bool tls13_add_key_update(SSL *ssl, int update_requested); // tls13_post_handshake processes a post-handshake message. It returns true on // success and false on failure. bool tls13_post_handshake(SSL *ssl, const SSLMessage &msg); bool tls13_process_certificate(SSL_HANDSHAKE *hs, const SSLMessage &msg, bool allow_anonymous); bool tls13_process_certificate_verify(SSL_HANDSHAKE *hs, const SSLMessage &msg); // tls13_process_finished processes |msg| as a Finished message from the // peer. If |use_saved_value| is true, the verify_data is compared against // |hs->expected_client_finished| rather than computed fresh. bool tls13_process_finished(SSL_HANDSHAKE *hs, const SSLMessage &msg, bool use_saved_value); bool tls13_add_certificate(SSL_HANDSHAKE *hs); // tls13_add_certificate_verify adds a TLS 1.3 CertificateVerify message to the // handshake. If it returns |ssl_private_key_retry|, it should be called again // to retry when the signing operation is completed. enum ssl_private_key_result_t tls13_add_certificate_verify(SSL_HANDSHAKE *hs); bool tls13_add_finished(SSL_HANDSHAKE *hs); bool tls13_process_new_session_ticket(SSL *ssl, const SSLMessage &msg); bssl::UniquePtr<SSL_SESSION> tls13_create_session_with_ticket(SSL *ssl, CBS *body); // ssl_setup_extension_permutation computes a ClientHello extension permutation // for |hs|, if applicable. It returns true on success and false on error. bool ssl_setup_extension_permutation(SSL_HANDSHAKE *hs); // ssl_setup_key_shares computes client key shares and saves them in |hs|. It // returns true on success and false on failure. If |override_group_id| is zero, // it offers the default groups, including GREASE. If it is non-zero, it offers // a single key share of the specified group. bool ssl_setup_key_shares(SSL_HANDSHAKE *hs, uint16_t override_group_id); bool ssl_ext_key_share_parse_serverhello(SSL_HANDSHAKE *hs, Array<uint8_t> *out_secret, uint8_t *out_alert, CBS *contents); bool ssl_ext_key_share_parse_clienthello(SSL_HANDSHAKE *hs, bool *out_found, Span<const uint8_t> *out_peer_key, uint8_t *out_alert, const SSL_CLIENT_HELLO *client_hello); bool ssl_ext_key_share_add_serverhello(SSL_HANDSHAKE *hs, CBB *out); bool ssl_ext_pre_shared_key_parse_serverhello(SSL_HANDSHAKE *hs, uint8_t *out_alert, CBS *contents); bool ssl_ext_pre_shared_key_parse_clienthello( SSL_HANDSHAKE *hs, CBS *out_ticket, CBS *out_binders, uint32_t *out_obfuscated_ticket_age, uint8_t *out_alert, const SSL_CLIENT_HELLO *client_hello, CBS *contents); bool ssl_ext_pre_shared_key_add_serverhello(SSL_HANDSHAKE *hs, CBB *out); // ssl_is_sct_list_valid does a shallow parse of the SCT list in |contents| and // returns whether it's valid. bool ssl_is_sct_list_valid(const CBS *contents); // ssl_write_client_hello_without_extensions writes a ClientHello to |out|, // up to the extensions field. |type| determines the type of ClientHello to // write. If |omit_session_id| is true, the session ID is empty. bool ssl_write_client_hello_without_extensions(const SSL_HANDSHAKE *hs, CBB *cbb, ssl_client_hello_type_t type, bool empty_session_id); // ssl_add_client_hello constructs a ClientHello and adds it to the outgoing // flight. It returns true on success and false on error. bool ssl_add_client_hello(SSL_HANDSHAKE *hs); struct ParsedServerHello { … }; // ssl_parse_server_hello parses |msg| as a ServerHello. On success, it writes // the result to |*out| and returns true. Otherwise, it returns false and sets // |*out_alert| to an alert to send to the peer. bool ssl_parse_server_hello(ParsedServerHello *out, uint8_t *out_alert, const SSLMessage &msg); enum ssl_cert_verify_context_t { … }; // tls13_get_cert_verify_signature_input generates the message to be signed for // TLS 1.3's CertificateVerify message. |cert_verify_context| determines the // type of signature. It sets |*out| to a newly allocated buffer containing the // result. This function returns true on success and false on failure. bool tls13_get_cert_verify_signature_input( SSL_HANDSHAKE *hs, Array<uint8_t> *out, enum ssl_cert_verify_context_t cert_verify_context); // ssl_is_valid_alpn_list returns whether |in| is a valid ALPN protocol list. bool ssl_is_valid_alpn_list(Span<const uint8_t> in); // ssl_is_alpn_protocol_allowed returns whether |protocol| is a valid server // selection for |hs->ssl|'s client preferences. bool ssl_is_alpn_protocol_allowed(const SSL_HANDSHAKE *hs, Span<const uint8_t> protocol); // ssl_alpn_list_contains_protocol returns whether |list|, a serialized ALPN // protocol list, contains |protocol|. bool ssl_alpn_list_contains_protocol(Span<const uint8_t> list, Span<const uint8_t> protocol); // ssl_negotiate_alpn negotiates the ALPN extension, if applicable. It returns // true on successful negotiation or if nothing was negotiated. It returns false // and sets |*out_alert| to an alert on error. bool ssl_negotiate_alpn(SSL_HANDSHAKE *hs, uint8_t *out_alert, const SSL_CLIENT_HELLO *client_hello); // ssl_get_local_application_settings looks up the configured ALPS value for // |protocol|. If found, it sets |*out_settings| to the value and returns true. // Otherwise, it returns false. bool ssl_get_local_application_settings(const SSL_HANDSHAKE *hs, Span<const uint8_t> *out_settings, Span<const uint8_t> protocol); // ssl_negotiate_alps negotiates the ALPS extension, if applicable. It returns // true on successful negotiation or if nothing was negotiated. It returns false // and sets |*out_alert| to an alert on error. bool ssl_negotiate_alps(SSL_HANDSHAKE *hs, uint8_t *out_alert, const SSL_CLIENT_HELLO *client_hello); struct SSLExtension { … }; // ssl_parse_extensions parses a TLS extensions block out of |cbs| and advances // it. It writes the parsed extensions to pointers in |extensions|. On success, // it fills in the |present| and |data| fields and returns true. Otherwise, it // sets |*out_alert| to an alert to send and returns false. Unknown extensions // are rejected unless |ignore_unknown| is true. bool ssl_parse_extensions(const CBS *cbs, uint8_t *out_alert, std::initializer_list<SSLExtension *> extensions, bool ignore_unknown); // ssl_verify_peer_cert verifies the peer certificate for |hs|. enum ssl_verify_result_t ssl_verify_peer_cert(SSL_HANDSHAKE *hs); // ssl_reverify_peer_cert verifies the peer certificate for |hs| when resuming a // session. enum ssl_verify_result_t ssl_reverify_peer_cert(SSL_HANDSHAKE *hs, bool send_alert); enum ssl_hs_wait_t ssl_get_finished(SSL_HANDSHAKE *hs); // ssl_send_finished adds a Finished message to the current flight of messages. // It returns true on success and false on error. bool ssl_send_finished(SSL_HANDSHAKE *hs); // ssl_send_tls12_certificate adds a TLS 1.2 Certificate message to the current // flight of messages. It returns true on success and false on error. bool ssl_send_tls12_certificate(SSL_HANDSHAKE *hs); // ssl_handshake_session returns the |SSL_SESSION| corresponding to the current // handshake. Note, in TLS 1.2 resumptions, this session is immutable. const SSL_SESSION *ssl_handshake_session(const SSL_HANDSHAKE *hs); // ssl_done_writing_client_hello is called after the last ClientHello is written // by |hs|. It releases some memory that is no longer needed. void ssl_done_writing_client_hello(SSL_HANDSHAKE *hs); // SSLKEYLOGFILE functions. // ssl_log_secret logs |secret| with label |label|, if logging is enabled for // |ssl|. It returns true on success and false on failure. bool ssl_log_secret(const SSL *ssl, const char *label, Span<const uint8_t> secret); // ClientHello functions. // ssl_client_hello_init parses |body| as a ClientHello message, excluding the // message header, and writes the result to |*out|. It returns true on success // and false on error. This function is exported for testing. OPENSSL_EXPORT bool ssl_client_hello_init(const SSL *ssl, SSL_CLIENT_HELLO *out, Span<const uint8_t> body); bool ssl_parse_client_hello_with_trailing_data(const SSL *ssl, CBS *cbs, SSL_CLIENT_HELLO *out); bool ssl_client_hello_get_extension(const SSL_CLIENT_HELLO *client_hello, CBS *out, uint16_t extension_type); bool ssl_client_cipher_list_contains_cipher( const SSL_CLIENT_HELLO *client_hello, uint16_t id); // GREASE. // ssl_get_grease_value returns a GREASE value for |hs|. For a given // connection, the values for each index will be deterministic. This allows the // same ClientHello be sent twice for a HelloRetryRequest or the same group be // advertised in both supported_groups and key_shares. uint16_t ssl_get_grease_value(const SSL_HANDSHAKE *hs, enum ssl_grease_index_t index); // Signature algorithms. // tls1_parse_peer_sigalgs parses |sigalgs| as the list of peer signature // algorithms and saves them on |hs|. It returns true on success and false on // error. bool tls1_parse_peer_sigalgs(SSL_HANDSHAKE *hs, const CBS *sigalgs); // tls1_get_legacy_signature_algorithm sets |*out| to the signature algorithm // that should be used with |pkey| in TLS 1.1 and earlier. It returns true on // success and false if |pkey| may not be used at those versions. bool tls1_get_legacy_signature_algorithm(uint16_t *out, const EVP_PKEY *pkey); // tls1_choose_signature_algorithm sets |*out| to a signature algorithm for use // with |cred| based on the peer's preferences and the algorithms supported. It // returns true on success and false on error. bool tls1_choose_signature_algorithm(SSL_HANDSHAKE *hs, const SSL_CREDENTIAL *cred, uint16_t *out); // tls12_add_verify_sigalgs adds the signature algorithms acceptable for the // peer signature to |out|. It returns true on success and false on error. bool tls12_add_verify_sigalgs(const SSL_HANDSHAKE *hs, CBB *out); // tls12_check_peer_sigalg checks if |sigalg| is acceptable for the peer // signature from |pkey|. It returns true on success and false on error, setting // |*out_alert| to an alert to send. bool tls12_check_peer_sigalg(const SSL_HANDSHAKE *hs, uint8_t *out_alert, uint16_t sigalg, EVP_PKEY *pkey); // Underdocumented functions. // // Functions below here haven't been touched up and may be underdocumented. #define TLSEXT_CHANNEL_ID_SIZE … // From RFC 4492, used in encoding the curve type in ECParameters #define NAMED_CURVE_TYPE … struct CERT { … }; // |SSL_PROTOCOL_METHOD| abstracts between TLS and DTLS. struct SSL_PROTOCOL_METHOD { … }; // The following wrappers call |open_*| but handle |read_shutdown| correctly. // ssl_open_handshake processes a record from |in| for reading a handshake // message. ssl_open_record_t ssl_open_handshake(SSL *ssl, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); // ssl_open_change_cipher_spec processes a record from |in| for reading a // ChangeCipherSpec. ssl_open_record_t ssl_open_change_cipher_spec(SSL *ssl, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); // ssl_open_app_data processes a record from |in| for reading application data. // On success, it returns |ssl_open_record_success| and sets |*out| to the // input. If it encounters a post-handshake message, it returns // |ssl_open_record_discard|. The caller should then retry, after processing any // messages received with |get_message|. ssl_open_record_t ssl_open_app_data(SSL *ssl, Span<uint8_t> *out, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); struct SSL_X509_METHOD { … }; // ssl_crypto_x509_method provides the |SSL_X509_METHOD| functions using // crypto/x509. extern const SSL_X509_METHOD ssl_crypto_x509_method; // ssl_noop_x509_method provides the |SSL_X509_METHOD| functions that avoid // crypto/x509. extern const SSL_X509_METHOD ssl_noop_x509_method; struct TicketKey { … }; struct CertCompressionAlg { … }; BSSL_NAMESPACE_END DEFINE_LHASH_OF(SSL_SESSION) BSSL_NAMESPACE_BEGIN // An ssl_shutdown_t describes the shutdown state of one end of the connection, // whether it is alive or has been shutdown via close_notify or fatal alert. enum ssl_shutdown_t { … }; enum ssl_ech_status_t { … }; struct SSL3_STATE { … }; // lengths of messages #define DTLS1_RT_MAX_HEADER_LENGTH … // DTLS_PLAINTEXT_RECORD_HEADER_LENGTH is the length of the DTLS record header // for plaintext records (in DTLS 1.3) or DTLS versions <= 1.2. #define DTLS_PLAINTEXT_RECORD_HEADER_LENGTH … // DTLS1_3_RECORD_HEADER_LENGTH is the length of the DTLS 1.3 record header // sent by BoringSSL for encrypted records. Note that received encrypted DTLS // 1.3 records might have a different length header. #define DTLS1_3_RECORD_HEADER_WRITE_LENGTH … static_assert …; static_assert …; #define DTLS1_HM_HEADER_LENGTH … #define DTLS1_CCS_HEADER_LENGTH … #define DTLS1_AL_HEADER_LENGTH … struct hm_header_st { … }; // An hm_fragment is an incoming DTLS message, possibly not yet assembled. struct hm_fragment { … }; struct OPENSSL_timeval { … }; struct DTLS1_STATE { … }; // An ALPSConfig is a pair of ALPN protocol and settings value to use with ALPS. struct ALPSConfig { … }; // SSL_CONFIG contains configuration bits that can be shed after the handshake // completes. Objects of this type are not shared; they are unique to a // particular |SSL|. // // See SSL_shed_handshake_config() for more about the conditions under which // configuration can be shed. struct SSL_CONFIG { … }; // From RFC 8446, used in determining PSK modes. #define SSL_PSK_DHE_KE … // kMaxEarlyDataAccepted is the advertised number of plaintext bytes of early // data that will be accepted. This value should be slightly below // kMaxEarlyDataSkipped in tls_record.c, which is measured in ciphertext. static const size_t kMaxEarlyDataAccepted = …; UniquePtr<CERT> ssl_cert_dup(CERT *cert); bool ssl_set_cert(CERT *cert, UniquePtr<CRYPTO_BUFFER> buffer); bool ssl_is_key_type_supported(int key_type); // ssl_compare_public_and_private_key returns true if |pubkey| is the public // counterpart to |privkey|. Otherwise it returns false and pushes a helpful // message on the error queue. bool ssl_compare_public_and_private_key(const EVP_PKEY *pubkey, const EVP_PKEY *privkey); bool ssl_get_new_session(SSL_HANDSHAKE *hs); bool ssl_encrypt_ticket(SSL_HANDSHAKE *hs, CBB *out, const SSL_SESSION *session); bool ssl_ctx_rotate_ticket_encryption_key(SSL_CTX *ctx); // ssl_session_new returns a newly-allocated blank |SSL_SESSION| or nullptr on // error. UniquePtr<SSL_SESSION> ssl_session_new(const SSL_X509_METHOD *x509_method); // ssl_hash_session_id returns a hash of |session_id|, suitable for a hash table // keyed on session IDs. uint32_t ssl_hash_session_id(Span<const uint8_t> session_id); // SSL_SESSION_parse parses an |SSL_SESSION| from |cbs| and advances |cbs| over // the parsed data. OPENSSL_EXPORT UniquePtr<SSL_SESSION> SSL_SESSION_parse( CBS *cbs, const SSL_X509_METHOD *x509_method, CRYPTO_BUFFER_POOL *pool); // ssl_session_serialize writes |in| to |cbb| as if it were serialising a // session for Session-ID resumption. It returns true on success and false on // error. OPENSSL_EXPORT bool ssl_session_serialize(const SSL_SESSION *in, CBB *cbb); // ssl_session_is_context_valid returns whether |session|'s session ID context // matches the one set on |hs|. bool ssl_session_is_context_valid(const SSL_HANDSHAKE *hs, const SSL_SESSION *session); // ssl_session_is_time_valid returns true if |session| is still valid and false // if it has expired. bool ssl_session_is_time_valid(const SSL *ssl, const SSL_SESSION *session); // ssl_session_is_resumable returns whether |session| is resumable for |hs|. bool ssl_session_is_resumable(const SSL_HANDSHAKE *hs, const SSL_SESSION *session); // ssl_session_protocol_version returns the protocol version associated with // |session|. Note that despite the name, this is not the same as // |SSL_SESSION_get_protocol_version|. The latter is based on upstream's name. uint16_t ssl_session_protocol_version(const SSL_SESSION *session); // ssl_session_get_digest returns the digest used in |session|. const EVP_MD *ssl_session_get_digest(const SSL_SESSION *session); void ssl_set_session(SSL *ssl, SSL_SESSION *session); // ssl_get_prev_session looks up the previous session based on |client_hello|. // On success, it sets |*out_session| to the session or nullptr if none was // found. If the session could not be looked up synchronously, it returns // |ssl_hs_pending_session| and should be called again. If a ticket could not be // decrypted immediately it returns |ssl_hs_pending_ticket| and should also // be called again. Otherwise, it returns |ssl_hs_error|. enum ssl_hs_wait_t ssl_get_prev_session(SSL_HANDSHAKE *hs, UniquePtr<SSL_SESSION> *out_session, bool *out_tickets_supported, bool *out_renew_ticket, const SSL_CLIENT_HELLO *client_hello); // The following flags determine which parts of the session are duplicated. #define SSL_SESSION_DUP_AUTH_ONLY … #define SSL_SESSION_INCLUDE_TICKET … #define SSL_SESSION_INCLUDE_NONAUTH … #define SSL_SESSION_DUP_ALL … // SSL_SESSION_dup returns a newly-allocated |SSL_SESSION| with a copy of the // fields in |session| or nullptr on error. The new session is non-resumable and // must be explicitly marked resumable once it has been filled in. OPENSSL_EXPORT UniquePtr<SSL_SESSION> SSL_SESSION_dup(SSL_SESSION *session, int dup_flags); // ssl_session_rebase_time updates |session|'s start time to the current time, // adjusting the timeout so the expiration time is unchanged. void ssl_session_rebase_time(SSL *ssl, SSL_SESSION *session); // ssl_session_renew_timeout calls |ssl_session_rebase_time| and renews // |session|'s timeout to |timeout| (measured from the current time). The // renewal is clamped to the session's auth_timeout. void ssl_session_renew_timeout(SSL *ssl, SSL_SESSION *session, uint32_t timeout); void ssl_update_cache(SSL *ssl); void ssl_send_alert(SSL *ssl, int level, int desc); int ssl_send_alert_impl(SSL *ssl, int level, int desc); bool tls_get_message(const SSL *ssl, SSLMessage *out); ssl_open_record_t tls_open_handshake(SSL *ssl, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); void tls_next_message(SSL *ssl); int tls_dispatch_alert(SSL *ssl); ssl_open_record_t tls_open_app_data(SSL *ssl, Span<uint8_t> *out, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); ssl_open_record_t tls_open_change_cipher_spec(SSL *ssl, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); int tls_write_app_data(SSL *ssl, bool *out_needs_handshake, size_t *out_bytes_written, Span<const uint8_t> in); bool tls_new(SSL *ssl); void tls_free(SSL *ssl); bool tls_init_message(const SSL *ssl, CBB *cbb, CBB *body, uint8_t type); bool tls_finish_message(const SSL *ssl, CBB *cbb, Array<uint8_t> *out_msg); bool tls_add_message(SSL *ssl, Array<uint8_t> msg); bool tls_add_change_cipher_spec(SSL *ssl); int tls_flush_flight(SSL *ssl); bool dtls1_init_message(const SSL *ssl, CBB *cbb, CBB *body, uint8_t type); bool dtls1_finish_message(const SSL *ssl, CBB *cbb, Array<uint8_t> *out_msg); bool dtls1_add_message(SSL *ssl, Array<uint8_t> msg); bool dtls1_add_change_cipher_spec(SSL *ssl); int dtls1_flush_flight(SSL *ssl); // ssl_add_message_cbb finishes the handshake message in |cbb| and adds it to // the pending flight. It returns true on success and false on error. bool ssl_add_message_cbb(SSL *ssl, CBB *cbb); // ssl_hash_message incorporates |msg| into the handshake hash. It returns true // on success and false on allocation failure. bool ssl_hash_message(SSL_HANDSHAKE *hs, const SSLMessage &msg); ssl_open_record_t dtls1_open_app_data(SSL *ssl, Span<uint8_t> *out, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); ssl_open_record_t dtls1_open_change_cipher_spec(SSL *ssl, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); int dtls1_write_app_data(SSL *ssl, bool *out_needs_handshake, size_t *out_bytes_written, Span<const uint8_t> in); // dtls1_write_record sends a record. It returns one on success and <= 0 on // error. int dtls1_write_record(SSL *ssl, int type, Span<const uint8_t> in, uint16_t epoch); int dtls1_retransmit_outgoing_messages(SSL *ssl); bool dtls1_parse_fragment(CBS *cbs, struct hm_header_st *out_hdr, CBS *out_body); bool dtls1_check_timeout_num(SSL *ssl); void dtls1_start_timer(SSL *ssl); void dtls1_stop_timer(SSL *ssl); bool dtls1_is_timer_expired(SSL *ssl); unsigned int dtls1_min_mtu(void); bool dtls1_new(SSL *ssl); void dtls1_free(SSL *ssl); bool dtls1_get_message(const SSL *ssl, SSLMessage *out); ssl_open_record_t dtls1_open_handshake(SSL *ssl, size_t *out_consumed, uint8_t *out_alert, Span<uint8_t> in); void dtls1_next_message(SSL *ssl); int dtls1_dispatch_alert(SSL *ssl); // tls1_configure_aead configures either the read or write direction AEAD (as // determined by |direction|) using the keys generated by the TLS KDF. The // |key_block_cache| argument is used to store the generated key block, if // empty. Otherwise it's assumed that the key block is already contained within // it. It returns true on success or false on error. bool tls1_configure_aead(SSL *ssl, evp_aead_direction_t direction, Array<uint8_t> *key_block_cache, const SSL_SESSION *session, Span<const uint8_t> iv_override); bool tls1_change_cipher_state(SSL_HANDSHAKE *hs, evp_aead_direction_t direction); int tls1_generate_master_secret(SSL_HANDSHAKE *hs, uint8_t *out, Span<const uint8_t> premaster); // tls1_get_grouplist returns the locally-configured group preference list. Span<const uint16_t> tls1_get_grouplist(const SSL_HANDSHAKE *ssl); // tls1_check_group_id returns whether |group_id| is consistent with locally- // configured group preferences. bool tls1_check_group_id(const SSL_HANDSHAKE *ssl, uint16_t group_id); // tls1_get_shared_group sets |*out_group_id| to the first preferred shared // group between client and server preferences and returns true. If none may be // found, it returns false. bool tls1_get_shared_group(SSL_HANDSHAKE *hs, uint16_t *out_group_id); // ssl_add_clienthello_tlsext writes ClientHello extensions to |out| for |type|. // It returns true on success and false on failure. The |header_len| argument is // the length of the ClientHello written so far and is used to compute the // padding length. (It does not include the record header or handshake headers.) // // If |type| is |ssl_client_hello_inner|, this function also writes the // compressed extensions to |out_encoded|. Otherwise, |out_encoded| should be // nullptr. // // On success, the function sets |*out_needs_psk_binder| to whether the last // ClientHello extension was the pre_shared_key extension and needs a PSK binder // filled in. The caller should then update |out| and, if applicable, // |out_encoded| with the binder after completing the whole message. bool ssl_add_clienthello_tlsext(SSL_HANDSHAKE *hs, CBB *out, CBB *out_encoded, bool *out_needs_psk_binder, ssl_client_hello_type_t type, size_t header_len); bool ssl_add_serverhello_tlsext(SSL_HANDSHAKE *hs, CBB *out); bool ssl_parse_clienthello_tlsext(SSL_HANDSHAKE *hs, const SSL_CLIENT_HELLO *client_hello); bool ssl_parse_serverhello_tlsext(SSL_HANDSHAKE *hs, const CBS *extensions); #define tlsext_tick_md … // ssl_process_ticket processes a session ticket from the client. It returns // one of: // |ssl_ticket_aead_success|: |*out_session| is set to the parsed session and // |*out_renew_ticket| is set to whether the ticket should be renewed. // |ssl_ticket_aead_ignore_ticket|: |*out_renew_ticket| is set to whether a // fresh ticket should be sent, but the given ticket cannot be used. // |ssl_ticket_aead_retry|: the ticket could not be immediately decrypted. // Retry later. // |ssl_ticket_aead_error|: an error occured that is fatal to the connection. enum ssl_ticket_aead_result_t ssl_process_ticket( SSL_HANDSHAKE *hs, UniquePtr<SSL_SESSION> *out_session, bool *out_renew_ticket, Span<const uint8_t> ticket, Span<const uint8_t> session_id); // tls1_verify_channel_id processes |msg| as a Channel ID message, and verifies // the signature. If the key is valid, it saves the Channel ID and returns true. // Otherwise, it returns false. bool tls1_verify_channel_id(SSL_HANDSHAKE *hs, const SSLMessage &msg); // tls1_write_channel_id generates a Channel ID message and puts the output in // |cbb|. |ssl->channel_id_private| must already be set before calling. This // function returns true on success and false on error. bool tls1_write_channel_id(SSL_HANDSHAKE *hs, CBB *cbb); // tls1_channel_id_hash computes the hash to be signed by Channel ID and writes // it to |out|, which must contain at least |EVP_MAX_MD_SIZE| bytes. It returns // true on success and false on failure. bool tls1_channel_id_hash(SSL_HANDSHAKE *hs, uint8_t *out, size_t *out_len); // tls1_record_handshake_hashes_for_channel_id records the current handshake // hashes in |hs->new_session| so that Channel ID resumptions can sign that // data. bool tls1_record_handshake_hashes_for_channel_id(SSL_HANDSHAKE *hs); // ssl_can_write returns whether |ssl| is allowed to write. bool ssl_can_write(const SSL *ssl); // ssl_can_read returns wheter |ssl| is allowed to read. bool ssl_can_read(const SSL *ssl); void ssl_get_current_time(const SSL *ssl, struct OPENSSL_timeval *out_clock); void ssl_ctx_get_current_time(const SSL_CTX *ctx, struct OPENSSL_timeval *out_clock); // ssl_reset_error_state resets state for |SSL_get_error|. void ssl_reset_error_state(SSL *ssl); // ssl_set_read_error sets |ssl|'s read half into an error state, saving the // current state of the error queue. void ssl_set_read_error(SSL *ssl); BSSL_NAMESPACE_END // Opaque C types. // // The following types are exported to C code as public typedefs, so they must // be defined outside of the namespace. // ssl_method_st backs the public |SSL_METHOD| type. It is a compatibility // structure to support the legacy version-locked methods. struct ssl_method_st { … }; struct ssl_ctx_st : public bssl::RefCounted<ssl_ctx_st> { … }; struct ssl_st { … }; struct ssl_session_st : public bssl::RefCounted<ssl_session_st> { … }; struct ssl_ech_keys_st : public bssl::RefCounted<ssl_ech_keys_st> { … }; #endif // OPENSSL_HEADER_SSL_INTERNAL_H
Codebase Browser
chromium