TLS_method is the SSL_METHOD used for TLS connections.

DTLS_method is the SSL_METHOD used for DTLS connections.

TLS_with_buffers_method is like TLS_method, but avoids all use of crypto/x509. All client connections created with TLS_with_buffers_method will fail unless a certificate verifier is installed with SSL_set_custom_verify or SSL_CTX_set_custom_verify.

DTLS_with_buffers_method is like DTLS_method, but avoids all use of crypto/x509.

SSL_CTX_new returns a newly-allocated SSL_CTX with default settings or NULL on error.

SSL_CTX_up_ref increments the reference count of ctx. It returns one.

SSL_CTX_free releases memory associated with ctx.

SSL_new returns a newly-allocated SSL using ctx or NULL on error. The new connection inherits settings from ctx at the time of creation. Settings may also be individually configured on the connection.

On creation, an SSL is not configured to be either a client or server. Call SSL_set_connect_state or SSL_set_accept_state to set this.

SSL_free releases memory associated with ssl.

SSL_get_SSL_CTX returns the SSL_CTX associated with ssl. If SSL_set_SSL_CTX is called, it returns the new SSL_CTX, not the initial one.

SSL_set_connect_state configures ssl to be a client.

SSL_set_accept_state configures ssl to be a server.

SSL_is_server returns one if ssl is configured as a server and zero otherwise.

SSL_is_dtls returns one if ssl is a DTLS connection and zero otherwise.

SSL_is_quic returns one if ssl is a QUIC connection and zero otherwise.

SSL_set_bio configures ssl to read from rbio and write to wbio. ssl takes ownership of the two BIOs. If rbio and wbio are the same, ssl only takes ownership of one reference. See SSL_set0_rbio and SSL_set0_wbio for requirements on rbio and wbio, respectively.

If rbio is the same as the currently configured BIO for reading, that side is left untouched and is not freed.

If wbio is the same as the currently configured BIO for writing AND ssl is not currently configured to read from and write to the same BIO, that side is left untouched and is not freed. This asymmetry is present for historical reasons.

Due to the very complex historical behavior of this function, calling this function if ssl already has BIOs configured is deprecated. Prefer SSL_set0_rbio and SSL_set0_wbio instead.

SSL_set0_rbio configures ssl to read from rbio. It takes ownership of rbio. rbio may be a custom BIO, in which case it must implement BIO_read with BIO_meth_set_read. In DTLS, rbio must be non-blocking to properly handle timeouts and retransmits.

Note that, although this function and SSL_set0_wbio may be called on the same BIO, each call takes a reference. Use BIO_up_ref to balance this.

SSL_set0_wbio configures ssl to write to wbio. It takes ownership of wbio. wbio may be a custom BIO, in which case it must implement BIO_write with BIO_meth_set_write. It must additionally implement BIO_flush with BIO_meth_set_ctrl and BIO_CTRL_FLUSH. If flushing is unnecessary with wbio, BIO_flush should return one and do nothing.

Note that, although this function and SSL_set0_rbio may be called on the same BIO, each call takes a reference. Use BIO_up_ref to balance this.

SSL_get_rbio returns the BIO that ssl reads from.

SSL_get_wbio returns the BIO that ssl writes to.

SSL_get_fd calls SSL_get_rfd.

SSL_get_rfd returns the file descriptor that ssl is configured to read from. If ssl's read BIO is not configured or doesn't wrap a file descriptor then it returns -1.

Note: On Windows, this may return either a file descriptor or a socket (cast to int), depending on whether ssl was configured with a file descriptor or socket BIO.

SSL_get_wfd returns the file descriptor that ssl is configured to write to. If ssl's write BIO is not configured or doesn't wrap a file descriptor then it returns -1.

Note: On Windows, this may return either a file descriptor or a socket (cast to int), depending on whether ssl was configured with a file descriptor or socket BIO.

SSL_set_fd configures ssl to read from and write to fd. It returns one on success and zero on allocation error. The caller retains ownership of fd.

On Windows, fd is cast to a SOCKET and used with Winsock APIs.

SSL_set_rfd configures ssl to read from fd. It returns one on success and zero on allocation error. The caller retains ownership of fd.

On Windows, fd is cast to a SOCKET and used with Winsock APIs.

SSL_set_wfd configures ssl to write to fd. It returns one on success and zero on allocation error. The caller retains ownership of fd.

On Windows, fd is cast to a SOCKET and used with Winsock APIs.

SSL_do_handshake continues the current handshake. If there is none or the handshake has completed or False Started, it returns one. Otherwise, it returns <= 0. The caller should pass the value into SSL_get_error to determine how to proceed.

In DTLS, the caller must drive retransmissions and timeouts. After calling this function, the caller must use DTLSv1_get_timeout to determine the current timeout, if any. If it expires before the application next calls into ssl, call DTLSv1_handle_timeout. Note that DTLS handshake retransmissions use fresh sequence numbers, so it is not sufficient to replay packets at the transport.

After the DTLS handshake, some retransmissions may remain. If ssl wrote last in the handshake, it may need to retransmit the final flight in case of packet loss. Additionally, in DTLS 1.3, it may need to retransmit post-handshake messages. To handle these, the caller must always be prepared to receive packets and process them with SSL_read, even when the application protocol would otherwise not read from the connection.

TODO(davidben): Ensure 0 is only returned on transport EOF. https://crbug.com/466303.

SSL_connect configures ssl as a client, if unconfigured, and calls SSL_do_handshake.

SSL_accept configures ssl as a server, if unconfigured, and calls SSL_do_handshake.

SSL_read reads up to num bytes from ssl into buf. It implicitly runs any pending handshakes, including renegotiations when enabled. On success, it returns the number of bytes read. Otherwise, it returns <= 0. The caller should pass the value into SSL_get_error to determine how to proceed.

In DTLS 1.3, the caller must also drive timeouts from retransmitting the final flight of the handshake, as well as post-handshake messages. After calling this function, the caller must use DTLSv1_get_timeout to determine the current timeout, if any. If it expires before the application next calls into ssl, call DTLSv1_handle_timeout.

TODO(davidben): Ensure 0 is only returned on transport EOF. https://crbug.com/466303.

SSL_peek behaves like SSL_read but does not consume any bytes returned.

SSL_pending returns the number of buffered, decrypted bytes available for read in ssl. It does not read from the transport.

In DTLS, it is possible for this function to return zero while there is buffered, undecrypted data from the transport in ssl. For example, SSL_read may read a datagram with two records, decrypt the first, and leave the second buffered for a subsequent call to SSL_read. Callers that wish to detect this case can use SSL_has_pending.

SSL_has_pending returns one if ssl has buffered, decrypted bytes available for read, or if ssl has buffered data from the transport that has not yet been decrypted. If ssl has neither, this function returns zero.

In TLS, BoringSSL does not implement read-ahead, so this function returns one if and only if SSL_pending would return a non-zero value. In DTLS, it is possible for this function to return one while SSL_pending returns zero. For example, SSL_read may read a datagram with two records, decrypt the first, and leave the second buffered for a subsequent call to SSL_read.

As a result, if this function returns one, the next call to SSL_read may still fail, read from the transport, or both. The buffered, undecrypted data may be invalid or incomplete.

SSL_write writes up to num bytes from buf into ssl. It implicitly runs any pending handshakes, including renegotiations when enabled. On success, it returns the number of bytes written. Otherwise, it returns <= 0. The caller should pass the value into SSL_get_error to determine how to proceed.

In TLS, a non-blocking SSL_write differs from non-blocking write in that a failed SSL_write still commits to the data passed in. When retrying, the caller must supply the original write buffer (or a larger one containing the original as a prefix). By default, retries will fail if they also do not reuse the same buf pointer. This may be relaxed with SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER, but the buffer contents still must be unchanged.

By default, in TLS, SSL_write will not return success until all num bytes are written. This may be relaxed with SSL_MODE_ENABLE_PARTIAL_WRITE. It allows SSL_write to complete with a partial result when only part of the input was written in a single record.

In DTLS, neither SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER and SSL_MODE_ENABLE_PARTIAL_WRITE do anything. The caller may retry with a different buffer freely. A single call to SSL_write only ever writes a single record in a single packet, so num must be at most SSL3_RT_MAX_PLAIN_LENGTH.

TODO(davidben): Ensure 0 is only returned on transport EOF. https://crbug.com/466303.

SSL_KEY_UPDATE_REQUESTED indicates that the peer should reply to a KeyUpdate message with its own, thus updating traffic secrets for both directions on the connection.

SSL_KEY_UPDATE_NOT_REQUESTED indicates that the peer should not reply with it's own KeyUpdate message.

SSL_key_update queues a TLS 1.3 KeyUpdate message to be sent on ssl if one is not already queued. The request_type argument must one of the SSL_KEY_UPDATE_* values. This function requires that ssl have completed a TLS >= 1.3 handshake. It returns one on success or zero on error.

Note that this function does not _send_ the message itself. The next call to SSL_write will cause the message to be sent. SSL_write may be called with a zero length to flush a KeyUpdate message when no application data is pending.

SSL_shutdown shuts down ssl. It runs in two stages. First, it sends close_notify and returns zero or one on success or -1 on failure. Zero indicates that close_notify was sent, but not received, and one additionally indicates that the peer's close_notify had already been received.

To then wait for the peer's close_notify, run SSL_shutdown to completion a second time. This returns 1 on success and -1 on failure. Application data is considered a fatal error at this point. To process or discard it, read until close_notify with SSL_read instead.

In both cases, on failure, pass the return value into SSL_get_error to determine how to proceed.

Most callers should stop at the first stage. Reading for close_notify is primarily used for uncommon protocols where the underlying transport is reused after TLS completes. Additionally, DTLS uses an unordered transport and is unordered, so the second stage is a no-op in DTLS.

SSL_CTX_set_quiet_shutdown sets quiet shutdown on ctx to mode. If enabled, SSL_shutdown will not send a close_notify alert or wait for one from the peer. It will instead synchronously return one.

SSL_CTX_get_quiet_shutdown returns whether quiet shutdown is enabled for ctx.

SSL_set_quiet_shutdown sets quiet shutdown on ssl to mode. If enabled, SSL_shutdown will not send a close_notify alert or wait for one from the peer. It will instead synchronously return one.

SSL_get_quiet_shutdown returns whether quiet shutdown is enabled for ssl.

SSL_get_error returns a SSL_ERROR_* value for the most recent operation on ssl. It should be called after an operation failed to determine whether the error was fatal and, if not, when to retry.

SSL_ERROR_NONE indicates the operation succeeded.

SSL_ERROR_SSL indicates the operation failed within the library. The caller may inspect the error queue (see ERR_get_error) for more information.

SSL_ERROR_WANT_READ indicates the operation failed attempting to read from the transport. The caller may retry the operation when the transport is ready for reading.

SSL_ERROR_WANT_WRITE indicates the operation failed attempting to write to the transport. The caller may retry the operation when the transport is ready for writing.

SSL_ERROR_WANT_X509_LOOKUP indicates the operation failed in calling the cert_cb or client_cert_cb. The caller may retry the operation when the callback is ready to return a certificate or one has been configured externally.

See also SSL_CTX_set_cert_cb and SSL_CTX_set_client_cert_cb.

SSL_ERROR_SYSCALL indicates the operation failed externally to the library. The caller should consult the system-specific error mechanism. This is typically errno but may be something custom if using a custom BIO. It may also be signaled if the transport returned EOF, in which case the operation's return value will be zero.

SSL_ERROR_ZERO_RETURN indicates the operation failed because the connection was cleanly shut down with a close_notify alert.

SSL_ERROR_WANT_CONNECT indicates the operation failed attempting to connect the transport (the BIO signaled BIO_RR_CONNECT). The caller may retry the operation when the transport is ready.

SSL_ERROR_WANT_ACCEPT indicates the operation failed attempting to accept a connection from the transport (the BIO signaled BIO_RR_ACCEPT). The caller may retry the operation when the transport is ready.

TODO(davidben): Remove this. It's used by accept BIOs which are bizarre.

SSL_ERROR_WANT_CHANNEL_ID_LOOKUP is never used.

TODO(davidben): Remove this. Some callers reference it when stringifying errors. They should use SSL_error_description instead.

SSL_ERROR_PENDING_SESSION indicates the operation failed because the session lookup callback indicated the session was unavailable. The caller may retry the operation when lookup has completed.

See also SSL_CTX_sess_set_get_cb and SSL_magic_pending_session_ptr.

SSL_ERROR_PENDING_CERTIFICATE indicates the operation failed because the early callback indicated certificate lookup was incomplete. The caller may retry the operation when lookup has completed.

See also SSL_CTX_set_select_certificate_cb.

SSL_ERROR_WANT_PRIVATE_KEY_OPERATION indicates the operation failed because a private key operation was unfinished. The caller may retry the operation when the private key operation is complete.

See also SSL_set_private_key_method, SSL_CTX_set_private_key_method, and SSL_CREDENTIAL_set_private_key_method.

SSL_ERROR_PENDING_TICKET indicates that a ticket decryption is pending. The caller may retry the operation when the decryption is ready.

See also SSL_CTX_set_ticket_aead_method.

SSL_ERROR_EARLY_DATA_REJECTED indicates that early data was rejected. The caller should treat this as a connection failure and retry any operations associated with the rejected early data. SSL_reset_early_data_reject may be used to reuse the underlying connection for the retry.

SSL_ERROR_WANT_CERTIFICATE_VERIFY indicates the operation failed because certificate verification was incomplete. The caller may retry the operation when certificate verification is complete.

See also SSL_CTX_set_custom_verify.

SSL_ERROR_WANT_RENEGOTIATE indicates the operation is pending a response to a renegotiation request from the server. The caller may call SSL_renegotiate to schedule a renegotiation and retry the operation.

See also ssl_renegotiate_explicit.

SSL_ERROR_HANDSHAKE_HINTS_READY indicates the handshake has progressed enough for SSL_serialize_handshake_hints to be called. See also SSL_request_handshake_hints.

SSL_error_description returns a string representation of err, where err is one of the SSL_ERROR_* constants returned by SSL_get_error, or NULL if the value is unrecognized.

SSL_set_mtu sets the ssl's MTU in DTLS to mtu. It returns one on success and zero on failure.

DTLSv1_set_initial_timeout_duration sets the initial duration for a DTLS handshake timeout.

This duration overrides the default of 400 milliseconds, which is recommendation of RFC 9147 for real-time protocols.

DTLSv1_get_timeout queries the running DTLS timers. If there are any in progress, it sets *out to the time remaining until the first timer expires and returns one. Otherwise, it returns zero. Timers may be scheduled both during and after the handshake.

When the timeout expires, call DTLSv1_handle_timeout to handle the retransmit behavior.

NOTE: This function must be queried again whenever the state machine changes, including when DTLSv1_handle_timeout is called.

DTLSv1_handle_timeout is called when a DTLS timeout expires. If no timeout had expired, it returns 0. Otherwise, it handles the timeout and returns 1 on success or -1 on error.

This function may write to the transport (e.g. to retransmit messages) or update ssl's internal state and schedule an updated timer.

The caller's external timer should be compatible with the one ssl queries within some fudge factor. Otherwise, the call will be a no-op, but DTLSv1_get_timeout will return an updated timeout.

If the function returns -1, checking if SSL_get_error returns SSL_ERROR_WANT_WRITE may be used to determine if the retransmit failed due to a non-fatal error at the write BIO. In this case, when the BIO is writable, the operation may be retried by calling the original function, SSL_do_handshake or SSL_read.

WARNING: This function breaks the usual return value convention.

TODO(davidben): We can make this function entirely optional by just checking the timers in SSL_do_handshake or SSL_read. Then timers behave like any other retry condition: rerun the operation and the library will make what progress it can.

SSL_CTX_set_min_proto_version sets the minimum protocol version for ctx to version. If version is zero, the default minimum version is used. It returns one on success and zero if version is invalid.

SSL_CTX_set_max_proto_version sets the maximum protocol version for ctx to version. If version is zero, the default maximum version is used. It returns one on success and zero if version is invalid.

SSL_CTX_get_min_proto_version returns the minimum protocol version for ctx

SSL_CTX_get_max_proto_version returns the maximum protocol version for ctx

SSL_set_min_proto_version sets the minimum protocol version for ssl to version. If version is zero, the default minimum version is used. It returns one on success and zero if version is invalid.

SSL_set_max_proto_version sets the maximum protocol version for ssl to version. If version is zero, the default maximum version is used. It returns one on success and zero if version is invalid.

SSL_get_min_proto_version returns the minimum protocol version for ssl. If the connection's configuration has been shed, 0 is returned.

SSL_get_max_proto_version returns the maximum protocol version for ssl. If the connection's configuration has been shed, 0 is returned.

SSL_version returns the TLS or DTLS protocol version used by ssl, which is one of the *_VERSION values. (E.g. TLS1_2_VERSION.) Before the version is negotiated, the result is undefined.

SSL_OP_NO_QUERY_MTU, in DTLS, disables querying the MTU from the underlying BIO. Instead, the MTU is configured with SSL_set_mtu.

SSL_OP_NO_TICKET disables session ticket support (RFC 5077).

SSL_OP_CIPHER_SERVER_PREFERENCE configures servers to select ciphers and ECDHE curves according to the server's preferences instead of the client's.

The following flags toggle individual protocol versions. This is deprecated. Use SSL_CTX_set_min_proto_version and SSL_CTX_set_max_proto_version instead.

SSL_CTX_set_options enables all options set in options (which should be one or more of the SSL_OP_* values, ORed together) in ctx. It returns a bitmask representing the resulting enabled options.

SSL_CTX_clear_options disables all options set in options (which should be one or more of the SSL_OP_* values, ORed together) in ctx. It returns a bitmask representing the resulting enabled options.

SSL_CTX_get_options returns a bitmask of SSL_OP_* values that represent all the options enabled for ctx.

SSL_set_options enables all options set in options (which should be one or more of the SSL_OP_* values, ORed together) in ssl. It returns a bitmask representing the resulting enabled options.

SSL_clear_options disables all options set in options (which should be one or more of the SSL_OP_* values, ORed together) in ssl. It returns a bitmask representing the resulting enabled options.

SSL_get_options returns a bitmask of SSL_OP_* values that represent all the options enabled for ssl.

SSL_MODE_ENABLE_PARTIAL_WRITE, in TLS, allows SSL_write to complete with a partial result when the only part of the input was written in a single record. In DTLS, it does nothing.

SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER, in TLS, allows retrying an incomplete SSL_write with a different buffer. However, SSL_write still assumes the buffer contents are unchanged. This is not the default to avoid the misconception that non-blocking SSL_write behaves like non-blocking write. In DTLS, it does nothing.

SSL_MODE_NO_AUTO_CHAIN disables automatically building a certificate chain before sending certificates to the peer. This flag is set (and the feature disabled) by default. TODO(davidben): Remove this behavior. https://crbug.com/boringssl/42.

SSL_MODE_ENABLE_FALSE_START allows clients to send application data before receipt of ChangeCipherSpec and Finished. This mode enables full handshakes to 'complete' in one RTT. See RFC 7918.

When False Start is enabled, SSL_do_handshake may succeed before the handshake has completely finished. SSL_write will function at this point, and SSL_read will transparently wait for the final handshake leg before returning application data. To determine if False Start occurred or when the handshake is completely finished, see SSL_in_false_start, SSL_in_init, and SSL_CB_HANDSHAKE_DONE from SSL_CTX_set_info_callback.

SSL_MODE_CBC_RECORD_SPLITTING causes multi-byte CBC records in TLS 1.0 to be split in two: the first record will contain a single byte and the second will contain the remainder. This effectively randomises the IV and prevents BEAST attacks.

SSL_MODE_NO_SESSION_CREATION will cause any attempts to create a session to fail with SSL_R_SESSION_MAY_NOT_BE_CREATED. This can be used to enforce that session resumption is used for a given SSL*.

SSL_MODE_SEND_FALLBACK_SCSV sends TLS_FALLBACK_SCSV in the ClientHello. To be set only by applications that reconnect with a downgraded protocol version; see RFC 7507 for details.

DO NOT ENABLE THIS if your application attempts a normal handshake. Only use this in explicit fallback retries, following the guidance in RFC 7507.

SSL_CTX_set_mode enables all modes set in mode (which should be one or more of the SSL_MODE_* values, ORed together) in ctx. It returns a bitmask representing the resulting enabled modes.

SSL_CTX_clear_mode disables all modes set in mode (which should be one or more of the SSL_MODE_* values, ORed together) in ctx. It returns a bitmask representing the resulting enabled modes.

SSL_CTX_get_mode returns a bitmask of SSL_MODE_* values that represent all the modes enabled for ssl.

SSL_set_mode enables all modes set in mode (which should be one or more of the SSL_MODE_* values, ORed together) in ssl. It returns a bitmask representing the resulting enabled modes.

SSL_clear_mode disables all modes set in mode (which should be one or more of the SSL_MODE_* values, ORed together) in ssl. It returns a bitmask representing the resulting enabled modes.

SSL_get_mode returns a bitmask of SSL_MODE_* values that represent all the modes enabled for ssl.

SSL_CTX_set0_buffer_pool sets a CRYPTO_BUFFER_POOL that will be used to store certificates. This can allow multiple connections to share certificates and thus save memory.

The SSL_CTX does not take ownership of pool and the caller must ensure that pool outlives ctx and all objects linked to it, including SSL, X509 and SSL_SESSION objects. Basically, don't ever free pool.

SSL_CREDENTIAL_new_x509 returns a new, empty X.509 credential, or NULL on error. Callers should release the result with SSL_CREDENTIAL_free when done.

Callers should configure a certificate chain and private key on the credential, along with other properties, then add it with SSL_CTX_add1_credential.

SSL_CREDENTIAL_up_ref increments the reference count of cred.

SSL_CREDENTIAL_free decrements the reference count of cred. If it reaches zero, all data referenced by cred and cred itself are released.

SSL_CREDENTIAL_set1_private_key sets cred's private key to cred. It returns one on success and zero on failure.

SSL_CREDENTIAL_set1_signing_algorithm_prefs configures cred to use prefs as the preference list when signing with cred's private key. It returns one on success and zero on error. prefs should not include the internal-only value SSL_SIGN_RSA_PKCS1_MD5_SHA1.

It is an error to call this function with delegated credentials (see SSL_CREDENTIAL_new_delegated) because delegated credentials already constrain the key to a single algorithm.

SSL_CREDENTIAL_set1_cert_chain sets cred's certificate chain, starting from the leaf, to num_certs certificates from certs. It returns one on success and zero on error.

SSL_CREDENTIAL_set1_ocsp_response sets cred's stapled OCSP response to ocsp. It returns one on success and zero on error.

SSL_CREDENTIAL_set1_signed_cert_timestamp_list sets cred's list of signed certificate timestamps sct_list. sct_list must contain one or more SCT structures serialised as a SignedCertificateTimestampList (see https://tools.ietf.org/html/rfc6962#section-3.3) – i.e. each SCT is prefixed by a big-endian, uint16 length and the concatenation of one or more such prefixed SCTs are themselves also prefixed by a uint16 length. It returns one on success and zero on error.

SSL_CTX_add1_credential appends cred to ctx's credential list. It returns one on success and zero on error. The credential list is maintained in order of decreasing preference, so earlier calls are preferred over later calls.

After calling this function, it is an error to modify cred. Doing so may result in inconsistent handshake behavior or race conditions.

SSL_add1_credential appends cred to ssl's credential list. It returns one on success and zero on error. The credential list is maintained in order of decreasing preference, so earlier calls are preferred over later calls.

After calling this function, it is an error to modify cred. Doing so may result in inconsistent handshake behavior or race conditions.

SSL_certs_clear removes all credentials configured on ssl. It also removes the certificate chain and private key on the legacy credential.

SSL_get0_selected_credential returns the credential in use in the current handshake on ssl. If there is current handshake on ssl or if the handshake has not progressed to this point, it returns NULL.

This function is intended for use with SSL_CREDENTIAL_get_ex_data. It may be called from handshake callbacks, such as those in SSL_PRIVATE_KEY_METHOD, to trigger credential-specific behavior.

In applications that use the older APIs, such as SSL_use_certificate, this function may return an internal SSL_CREDENTIAL object. This internal object will have no ex_data installed. To avoid this, it is recommended that callers moving to SSL_CREDENTIAL use the new APIs consistently.

SSL_CTX_use_certificate sets ctx's leaf certificate to x509. It returns one on success and zero on failure. If ctx has a private key which is inconsistent with x509, the private key is silently dropped.

SSL_use_certificate sets ssl's leaf certificate to x509. It returns one on success and zero on failure. If ssl has a private key which is inconsistent with x509, the private key is silently dropped.

SSL_CTX_use_PrivateKey sets ctx's private key to pkey. It returns one on success and zero on failure. If ctx had a private key or SSL_PRIVATE_KEY_METHOD previously configured, it is replaced.

SSL_use_PrivateKey sets ssl's private key to pkey. It returns one on success and zero on failure. If ssl had a private key or SSL_PRIVATE_KEY_METHOD previously configured, it is replaced.

SSL_CTX_set0_chain sets ctx's certificate chain, excluding the leaf, to chain. On success, it returns one and takes ownership of chain. Otherwise, it returns zero.

SSL_CTX_set1_chain sets ctx's certificate chain, excluding the leaf, to chain. It returns one on success and zero on failure. The caller retains ownership of chain and may release it freely.

SSL_set0_chain sets ssl's certificate chain, excluding the leaf, to chain. On success, it returns one and takes ownership of chain. Otherwise, it returns zero.

SSL_set1_chain sets ssl's certificate chain, excluding the leaf, to chain. It returns one on success and zero on failure. The caller retains ownership of chain and may release it freely.

SSL_CTX_add0_chain_cert appends x509 to ctx's certificate chain. On success, it returns one and takes ownership of x509. Otherwise, it returns zero.

SSL_CTX_add1_chain_cert appends x509 to ctx's certificate chain. It returns one on success and zero on failure. The caller retains ownership of x509 and may release it freely.

SSL_add0_chain_cert appends x509 to ctx's certificate chain. On success, it returns one and takes ownership of x509. Otherwise, it returns zero.

SSL_CTX_add_extra_chain_cert calls SSL_CTX_add0_chain_cert.

SSL_add1_chain_cert appends x509 to ctx's certificate chain. It returns one on success and zero on failure. The caller retains ownership of x509 and may release it freely.

SSL_CTX_clear_chain_certs clears ctx's certificate chain and returns one.

SSL_CTX_clear_extra_chain_certs calls SSL_CTX_clear_chain_certs.

SSL_clear_chain_certs clears ssl's certificate chain and returns one.

SSL_CTX_set_cert_cb sets a callback that is called to select a certificate. The callback returns one on success, zero on internal error, and a negative number on failure or to pause the handshake. If the handshake is paused, SSL_get_error will return SSL_ERROR_WANT_X509_LOOKUP.

On the client, the callback may call SSL_get0_certificate_types and SSL_get_client_CA_list for information on the server's certificate request.

On the server, the callback will be called after extensions have been processed, but before the resumption decision has been made. This differs from OpenSSL which handles resumption before selecting the certificate.

SSL_set_cert_cb sets a callback that is called to select a certificate. The callback returns one on success, zero on internal error, and a negative number on failure or to pause the handshake. If the handshake is paused, SSL_get_error will return SSL_ERROR_WANT_X509_LOOKUP.

On the client, the callback may call SSL_get0_certificate_types and SSL_get_client_CA_list for information on the server's certificate request.

On the server, the callback will be called after extensions have been processed, but before the resumption decision has been made. This differs from OpenSSL which handles resumption before selecting the certificate.

SSL_get0_certificate_types, for a client, sets *out_types to an array containing the client certificate types requested by a server. It returns the length of the array. Note this list is always empty in TLS 1.3. The server will instead send signature algorithms. See SSL_get0_peer_verify_algorithms.

The behavior of this function is undefined except during the callbacks set by by SSL_CTX_set_cert_cb and SSL_CTX_set_client_cert_cb or when the handshake is paused because of them.

SSL_get0_peer_verify_algorithms sets *out_sigalgs to an array containing the signature algorithms the peer is able to verify. It returns the length of the array. Note these values are only sent starting TLS 1.2 and only mandatory starting TLS 1.3. If not sent, the empty array is returned. For the historical client certificate types list, see SSL_get0_certificate_types.

The behavior of this function is undefined except during the callbacks set by by SSL_CTX_set_cert_cb and SSL_CTX_set_client_cert_cb or when the handshake is paused because of them.

SSL_get0_peer_delegation_algorithms sets *out_sigalgs to an array containing the signature algorithms the peer is willing to use with delegated credentials. It returns the length of the array. If not sent, the empty array is returned.

The behavior of this function is undefined except during the callbacks set by by SSL_CTX_set_cert_cb and SSL_CTX_set_client_cert_cb or when the handshake is paused because of them.

SSL_CTX_get0_certificate returns ctx's leaf certificate.

SSL_get_certificate returns ssl's leaf certificate.

SSL_CTX_get0_privatekey returns ctx's private key.

SSL_get_privatekey returns ssl's private key.

SSL_CTX_get0_chain_certs sets *out_chain to ctx's certificate chain and returns one.

SSL_CTX_get_extra_chain_certs calls SSL_CTX_get0_chain_certs.

SSL_get0_chain_certs sets *out_chain to ssl's certificate chain and returns one.

SSL_CTX_set_signed_cert_timestamp_list sets the list of signed certificate timestamps that is sent to clients that request it. The list argument must contain one or more SCT structures serialised as a SignedCertificateTimestamp List (see https://tools.ietf.org/html/rfc6962#section-3.3) – i.e. each SCT is prefixed by a big-endian, uint16 length and the concatenation of one or more such prefixed SCTs are themselves also prefixed by a uint16 length. It returns one on success and zero on error. The caller retains ownership of list.

SSL_set_signed_cert_timestamp_list sets the list of signed certificate timestamps that is sent to clients that request is. The same format as the one used for SSL_CTX_set_signed_cert_timestamp_list applies. The caller retains ownership of list.

SSL_CTX_set_ocsp_response sets the OCSP response that is sent to clients which request it. It returns one on success and zero on error. The caller retains ownership of response.

SSL_set_ocsp_response sets the OCSP response that is sent to clients which request it. It returns one on success and zero on error. The caller retains ownership of response.

SSL_SIGN_* are signature algorithm values as defined in TLS 1.3.

SSL_SIGN_RSA_PKCS1_SHA256_LEGACY is a backport of RSASSA-PKCS1-v1_5 with SHA-256 to TLS 1.3. It is disabled by default and only defined for client certificates.

SSL_SIGN_RSA_PKCS1_MD5_SHA1 is an internal signature algorithm used to specify raw RSASSA-PKCS1-v1_5 with an MD5/SHA-1 concatenation, as used in TLS before TLS 1.2.

SSL_get_signature_algorithm_name returns a human-readable name for sigalg, or NULL if unknown. If include_curve is one, the curve for ECDSA algorithms is included as in TLS 1.3. Otherwise, it is excluded as in TLS 1.2.

SSL_get_all_signature_algorithm_names outputs a list of possible strings SSL_get_signature_algorithm_name may return in this version of BoringSSL. It writes at most max_out entries to out and returns the total number it would have written, if max_out had been large enough. max_out may be initially set to zero to size the output.

This function is only intended to help initialize tables in callers that want possible strings pre-declared. This list would not be suitable to set a list of supported features. It is in no particular order, and may contain placeholder, experimental, or deprecated values that do not apply to every caller. Future versions of BoringSSL may also return strings not in this list, so this does not apply if, say, sending strings across services.

SSL_get_signature_algorithm_key_type returns the key type associated with sigalg as an EVP_PKEY_* constant or EVP_PKEY_NONE if unknown.

SSL_get_signature_algorithm_digest returns the digest function associated with sigalg or NULL if sigalg has no prehash (Ed25519) or is unknown.

SSL_is_signature_algorithm_rsa_pss returns one if sigalg is an RSA-PSS signature algorithm and zero otherwise.

SSL_CTX_set_signing_algorithm_prefs configures ctx to use prefs as the preference list when signing with ctx's private key. It returns one on success and zero on error. prefs should not include the internal-only value SSL_SIGN_RSA_PKCS1_MD5_SHA1.

SSL_set_signing_algorithm_prefs configures ssl to use prefs as the preference list when signing with ssl's private key. It returns one on success and zero on error. prefs should not include the internal-only value SSL_SIGN_RSA_PKCS1_MD5_SHA1.

SSL_CTX_set_chain_and_key sets the certificate chain and private key for a TLS client or server. References to the given CRYPTO_BUFFER and EVP_PKEY objects are added as needed. Exactly one of privkey or privkey_method may be non-NULL. Returns one on success and zero on error.

SSL_set_chain_and_key sets the certificate chain and private key for a TLS client or server. References to the given CRYPTO_BUFFER and EVP_PKEY objects are added as needed. Exactly one of privkey or privkey_method may be non-NULL. Returns one on success and zero on error.

SSL_CTX_get0_chain returns the list of CRYPTO_BUFFERs that were set by SSL_CTX_set_chain_and_key. Reference counts are not incremented by this call. The return value may be NULL if no chain has been set.

(Note: if a chain was configured by non-CRYPTO_BUFFER-based functions then the return value is undefined and, even if not NULL, the stack itself may contain nullptrs. Thus you shouldn't mix this function with non-CRYPTO_BUFFER functions for manipulating the chain.)

SSL_get0_chain returns the list of CRYPTO_BUFFERs that were set by SSL_set_chain_and_key, unless they have been discarded. Reference counts are not incremented by this call. The return value may be NULL if no chain has been set.

(Note: if a chain was configured by non-CRYPTO_BUFFER-based functions then the return value is undefined and, even if not NULL, the stack itself may contain nullptrs. Thus you shouldn't mix this function with non-CRYPTO_BUFFER functions for manipulating the chain.)

This function may return nullptr if a handshake has completed even if SSL_set_chain_and_key was previously called, since the configuration containing the certificates is typically cleared after handshake completion.

SSL_CTX_use_RSAPrivateKey sets ctx's private key to rsa. It returns one on success and zero on failure.

SSL_use_RSAPrivateKey sets ctx's private key to rsa. It returns one on success and zero on failure.

The following functions configure certificates or private keys but take as input DER-encoded structures. They return one on success and zero on failure.

The following functions configure certificates or private keys but take as input files to read from. They return one on success and zero on failure. The type parameter is one of the SSL_FILETYPE_* values and determines whether the file's contents are read as PEM or DER.

SSL_CTX_use_certificate_chain_file configures certificates for ctx. It reads the contents of file as a PEM-encoded leaf certificate followed optionally by the certificate chain to send to the peer. It returns one on success and zero on failure.

WARNING: If the input contains "TRUSTED CERTIFICATE" PEM blocks, this function parses auxiliary properties as in d2i_X509_AUX. Passing untrusted input to this function allows an attacker to influence those properties. See d2i_X509_AUX for details.

SSL_CTX_set_default_passwd_cb sets the password callback for PEM-based convenience functions called on ctx.

SSL_CTX_get_default_passwd_cb returns the callback set by SSL_CTX_set_default_passwd_cb.

SSL_CTX_set_default_passwd_cb_userdata sets the userdata parameter for ctx's password callback.

SSL_CTX_get_default_passwd_cb_userdata returns the userdata parameter set by SSL_CTX_set_default_passwd_cb_userdata.

ssl_private_key_method_st (aka SSL_PRIVATE_KEY_METHOD) describes private key hooks. This is used to off-load signing operations to a custom, potentially asynchronous, backend. Metadata about the key such as the type and size are parsed out of the certificate.

SSL_set_private_key_method configures a custom private key on ssl. key_method must remain valid for the lifetime of ssl.

If using an RSA or ECDSA key, callers should configure signing capabilities with SSL_set_signing_algorithm_prefs. Otherwise, BoringSSL may select a signature algorithm that key_method does not support.

SSL_CTX_set_private_key_method configures a custom private key on ctx. key_method must remain valid for the lifetime of ctx.

If using an RSA or ECDSA key, callers should configure signing capabilities with SSL_CTX_set_signing_algorithm_prefs. Otherwise, BoringSSL may select a signature algorithm that key_method does not support.

SSL_CREDENTIAL_set_private_key_method configures a custom private key on cred. key_method must remain valid for the lifetime of cred. It returns one on success and zero if cred does not use private keys.

If using an RSA or ECDSA key, callers should configure signing capabilities with SSL_CREDENTIAL_set1_signing_algorithm_prefs. Otherwise, BoringSSL may select a signature algorithm that key_method does not support. This is not necessary for delegated credentials (see SSL_CREDENTIAL_new_delegated) because delegated credentials only support a single signature algorithm.

Functions in key_method will be passed an SSL object, but not cred directly. Use SSL_get0_selected_credential to determine the selected credential. From there, SSL_CREDENTIAL_get_ex_data can be used to look up credential-specific state, such as a handle to the private key.

SSL_CREDENTIAL_set_must_match_issuer sets the flag that this credential should be considered only when it matches a peer request for a particular issuer via a negotiation mechanism (such as the certificate_authorities extension).

SSL_CREDENTIAL_clear_must_match_issuer clears the flag requiring issuer matching, indicating this credential should be considered regardless of peer issuer matching requests. (This is the default).

SSL_CREDENTIAL_must_match_issuer returns the value of the flag indicating that this credential should be considered only when it matches a peer request for a particular issuer via a negotiation mechanism (such as the certificate_authorities extension).

SSL_can_release_private_key returns one if ssl will no longer call into the private key and zero otherwise. If the function returns one, the caller can release state associated with the private key.

NOTE: This function assumes the caller does not use SSL_clear to reuse ssl for a second connection. If SSL_clear is used, BoringSSL may still use the private key on the second connection.

SSL_get_cipher_by_value returns the structure representing a TLS cipher suite based on its assigned number, or NULL if unknown. See https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4.

SSL_CIPHER_get_id returns cipher's non-IANA id. This is not its IANA-assigned number, which is called the "value" here, although it may be cast to a uint16_t to get it.

SSL_CIPHER_get_protocol_id returns cipher's IANA-assigned number.

SSL_CIPHER_is_aead returns one if cipher uses an AEAD cipher.

SSL_CIPHER_is_block_cipher returns one if cipher is a block cipher.

SSL_CIPHER_get_cipher_nid returns the NID for cipher's bulk cipher. Possible values are NID_aes_128_gcm, NID_aes_256_gcm, NID_chacha20_poly1305, NID_aes_128_cbc, NID_aes_256_cbc, and NID_des_ede3_cbc.

SSL_CIPHER_get_digest_nid returns the NID for cipher's HMAC if it is a legacy cipher suite. For modern AEAD-based ciphers (see SSL_CIPHER_is_aead), it returns NID_undef.

Note this function only returns the legacy HMAC digest, not the PRF hash.

SSL_CIPHER_get_kx_nid returns the NID for cipher's key exchange. This may be NID_kx_rsa, NID_kx_ecdhe, or NID_kx_psk for TLS 1.2. In TLS 1.3, cipher suites do not specify the key exchange, so this function returns NID_kx_any.

SSL_CIPHER_get_auth_nid returns the NID for cipher's authentication type. This may be NID_auth_rsa, NID_auth_ecdsa, or NID_auth_psk for TLS 1.2. In TLS 1.3, cipher suites do not specify authentication, so this function returns NID_auth_any.

SSL_CIPHER_get_handshake_digest returns cipher's PRF hash. If cipher is a pre-TLS-1.2 cipher, it returns EVP_md5_sha1 but note these ciphers use SHA-256 in TLS 1.2. Other return values may be treated uniformly in all applicable versions.

SSL_CIPHER_get_prf_nid behaves like SSL_CIPHER_get_handshake_digest but returns the NID constant. Use SSL_CIPHER_get_handshake_digest instead.

SSL_CIPHER_get_min_version returns the minimum protocol version required for cipher.

SSL_CIPHER_get_max_version returns the maximum protocol version that supports cipher.

SSL_CIPHER_standard_name returns the standard IETF name for cipher. For example, "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256".

SSL_CIPHER_get_name returns the OpenSSL name of cipher. For example, "ECDHE-RSA-AES128-GCM-SHA256". Callers are recommended to use SSL_CIPHER_standard_name instead.

SSL_CIPHER_get_kx_name returns a string that describes the key-exchange method used by cipher. For example, "ECDHE_ECDSA". TLS 1.3 AEAD-only ciphers return the string "GENERIC".

SSL_CIPHER_get_bits returns the strength, in bits, of cipher. If out_alg_bits is not NULL, it writes the number of bits consumed by the symmetric algorithm to *out_alg_bits.

SSL_get_all_cipher_names outputs a list of possible strings SSL_CIPHER_get_name may return in this version of BoringSSL. It writes at most max_out entries to out and returns the total number it would have written, if max_out had been large enough. max_out may be initially set to zero to size the output.

This function is only intended to help initialize tables in callers that want possible strings pre-declared. This list would not be suitable to set a list of supported features. It is in no particular order, and may contain placeholder, experimental, or deprecated values that do not apply to every caller. Future versions of BoringSSL may also return strings not in this list, so this does not apply if, say, sending strings across services.

SSL_get_all_standard_cipher_names outputs a list of possible strings SSL_CIPHER_standard_name may return in this version of BoringSSL. It writes at most max_out entries to out and returns the total number it would have written, if max_out had been large enough. max_out may be initially set to zero to size the output.

This function is only intended to help initialize tables in callers that want possible strings pre-declared. This list would not be suitable to set a list of supported features. It is in no particular order, and may contain placeholder, experimental, or deprecated values that do not apply to every caller. Future versions of BoringSSL may also return strings not in this list, so this does not apply if, say, sending strings across services.

SSL_DEFAULT_CIPHER_LIST is the default cipher suite configuration. It is substituted when a cipher string starts with 'DEFAULT'.

SSL_CTX_set_strict_cipher_list configures the cipher list for ctx, evaluating str as a cipher string and returning error if str contains anything meaningless. It returns one on success and zero on failure.

SSL_CTX_set_cipher_list configures the cipher list for ctx, evaluating str as a cipher string. It returns one on success and zero on failure.

Prefer to use SSL_CTX_set_strict_cipher_list. This function tolerates garbage inputs, unless an empty cipher list results.

SSL_set_strict_cipher_list configures the cipher list for ssl, evaluating str as a cipher string and returning error if str contains anything meaningless. It returns one on success and zero on failure.

SSL_set_cipher_list configures the cipher list for ssl, evaluating str as a cipher string. It returns one on success and zero on failure.

Prefer to use SSL_set_strict_cipher_list. This function tolerates garbage inputs, unless an empty cipher list results.

SSL_CTX_get_ciphers returns the cipher list for ctx, in order of preference.

SSL_CTX_cipher_in_group returns one if the ith cipher (see SSL_CTX_get_ciphers) is in the same equipreference group as the one following it and zero otherwise.

SSL_get_ciphers returns the cipher list for ssl, in order of preference.

SSL_is_init_finished returns one if ssl has completed its initial handshake and has no pending handshake. It returns zero otherwise.

SSL_in_init returns one if ssl has a pending handshake and zero otherwise.

SSL_in_false_start returns one if ssl has a pending handshake that is in False Start. SSL_write may be called at this point without waiting for the peer, but SSL_read will complete the handshake before accepting application data.

See also SSL_MODE_ENABLE_FALSE_START.

SSL_get_peer_certificate returns the peer's leaf certificate or NULL if the peer did not use certificates. The caller must call X509_free on the result to release it.

SSL_get_peer_cert_chain returns the peer's certificate chain or NULL if unavailable or the peer did not use certificates. This is the unverified list of certificates as sent by the peer, not the final chain built during verification. The caller does not take ownership of the result.

WARNING: This function behaves differently between client and server. If ssl is a server, the returned chain does not include the leaf certificate. If a client, it does.

SSL_get_peer_full_cert_chain returns the peer's certificate chain, or NULL if unavailable or the peer did not use certificates. This is the unverified list of certificates as sent by the peer, not the final chain built during verification. The caller does not take ownership of the result.

This is the same as SSL_get_peer_cert_chain except that this function always returns the full chain, i.e. the first element of the return value (if any) will be the leaf certificate. In constrast, SSL_get_peer_cert_chain returns only the intermediate certificates if the ssl is a server.

SSL_get0_peer_certificates returns the peer's certificate chain, or NULL if unavailable or the peer did not use certificates. This is the unverified list of certificates as sent by the peer, not the final chain built during verification. The caller does not take ownership of the result.

This is the CRYPTO_BUFFER variant of SSL_get_peer_full_cert_chain.

SSL_get0_signed_cert_timestamp_list sets *out and *out_len to point to *out_len bytes of SCT information from the server. This is only valid if ssl is a client. The SCT information is a SignedCertificateTimestampList (including the two leading length bytes). See https://tools.ietf.org/html/rfc6962#section-3.3 If no SCT was received then *out_len will be zero on return.

WARNING: the returned data is not guaranteed to be well formed.

SSL_get0_ocsp_response sets *out and *out_len to point to *out_len bytes of an OCSP response from the server. This is the DER encoding of an OCSPResponse type as defined in RFC 2560.

WARNING: the returned data is not guaranteed to be well formed.

SSL_get_tls_unique writes at most max_out bytes of the tls-unique value for ssl to out and sets *out_len to the number of bytes written. It returns one on success or zero on error. In general max_out should be at least 12.

This function will always fail if the initial handshake has not completed. The tls-unique value will change after a renegotiation but, since renegotiations can be initiated by the server at any point, the higher-level protocol must either leave them disabled or define states in which the tls-unique value can be read.

The tls-unique value is defined by https://tools.ietf.org/html/rfc5929#section-3.1. Due to a weakness in the TLS protocol, tls-unique is broken for resumed connections unless the Extended Master Secret extension is negotiated. Thus this function will return zero if ssl performed session resumption unless EMS was used when negotiating the original session.

SSL_get_extms_support returns one if the Extended Master Secret extension or TLS 1.3 was negotiated. Otherwise, it returns zero.

SSL_get_current_cipher returns cipher suite used by ssl, or NULL if it has not been negotiated yet.

SSL_session_reused returns one if ssl performed an abbreviated handshake and zero otherwise.

TODO(davidben): Hammer down the semantics of this API while a handshake, initial or renego, is in progress.

SSL_get_secure_renegotiation_support returns one if the peer supports secure renegotiation (RFC 5746) or TLS 1.3. Otherwise, it returns zero.

SSL_export_keying_material exports a value derived from the master secret, as specified in RFC 5705. It writes out_len bytes to out given a label and optional context. (Since a zero length context is allowed, the use_context flag controls whether a context is included.)

It returns one on success and zero otherwise.

SSL_SESSION_new returns a newly-allocated blank SSL_SESSION or NULL on error. This may be useful when writing tests but should otherwise not be used.

SSL_SESSION_up_ref increments the reference count of session and returns one.

SSL_SESSION_free decrements the reference count of session. If it reaches zero, all data referenced by session and session itself are released.

SSL_SESSION_to_bytes serializes in into a newly allocated buffer and sets *out_data to that buffer and *out_len to its length. The caller takes ownership of the buffer and must call OPENSSL_free when done. It returns one on success and zero on error.

SSL_SESSION_to_bytes_for_ticket serializes in, but excludes the session identification information, namely the session ID and ticket.

SSL_SESSION_from_bytes parses in_len bytes from in as an SSL_SESSION. It returns a newly-allocated SSL_SESSION on success or NULL on error.

SSL_SESSION_get_version returns a string describing the TLS or DTLS version session was established at. For example, "TLSv1.2" or "DTLSv1".

SSL_SESSION_get_protocol_version returns the TLS or DTLS version session was established at.

SSL_SESSION_set_protocol_version sets session's TLS or DTLS version to version. This may be useful when writing tests but should otherwise not be used. It returns one on success and zero on error.

SSL_MAX_SSL_SESSION_ID_LENGTH is the maximum length of an SSL session ID.

SSL_SESSION_get_id returns a pointer to a buffer containing session's session ID and sets *out_len to its length.

This function should only be used for implementing a TLS session cache. TLS sessions are not suitable for application-level session state, and a session ID is an implementation detail of the TLS resumption handshake mechanism. Not all resumption flows use session IDs, and not all connections within an application-level session will reuse TLS sessions.

To determine if resumption occurred, use SSL_session_reused instead. Comparing session IDs will not give the right result in all cases.

As a workaround for some broken applications, BoringSSL sometimes synthesizes arbitrary session IDs for non-ID-based sessions. This behavior may be removed in the future.

SSL_SESSION_set1_id sets session's session ID to sid, It returns one on success and zero on error. This function may be useful in writing tests but otherwise should not be used.

SSL_SESSION_get_time returns the time at which session was established in seconds since the UNIX epoch.

SSL_SESSION_get_timeout returns the lifetime of session in seconds.

SSL_SESSION_get0_peer returns the peer leaf certificate stored in session.

TODO(davidben): This should return a const X509 *.

SSL_SESSION_get0_peer_certificates returns the peer certificate chain stored in session, or NULL if the peer did not use certificates. This is the unverified list of certificates as sent by the peer, not the final chain built during verification. The caller does not take ownership of the result.

SSL_SESSION_get0_signed_cert_timestamp_list sets *out and *out_len to point to *out_len bytes of SCT information stored in session. This is only valid for client sessions. The SCT information is a SignedCertificateTimestampList (including the two leading length bytes). See https://tools.ietf.org/html/rfc6962#section-3.3 If no SCT was received then *out_len will be zero on return.

WARNING: the returned data is not guaranteed to be well formed.

SSL_SESSION_get0_ocsp_response sets *out and *out_len to point to *out_len bytes of an OCSP response from the server. This is the DER encoding of an OCSPResponse type as defined in RFC 2560.

WARNING: the returned data is not guaranteed to be well formed.

SSL_MAX_MASTER_KEY_LENGTH is the maximum length of a master secret.

SSL_SESSION_get_master_key writes up to max_out bytes of session's secret to out and returns the number of bytes written. If max_out is zero, it returns the size of the secret.

SSL_SESSION_set_time sets session's creation time to time and returns time. This function may be useful in writing tests but otherwise should not be used.

SSL_SESSION_set_timeout sets session's timeout to timeout and returns one. This function may be useful in writing tests but otherwise should not be used.

SSL_SESSION_get0_id_context returns a pointer to a buffer containing session's session ID context (see SSL_CTX_set_session_id_context) and sets *out_len to its length.

SSL_SESSION_set1_id_context sets session's session ID context (see SSL_CTX_set_session_id_context) to sid_ctx. It returns one on success and zero on error. This function may be useful in writing tests but otherwise should not be used.

SSL_SESSION_should_be_single_use returns one if session should be single-use (TLS 1.3 and later) and zero otherwise.

If this function returns one, clients retain multiple sessions and use each only once. This prevents passive observers from correlating connections with tickets. See RFC 8446, appendix C.4. If it returns zero, session cannot be used without leaking a correlator.

SSL_SESSION_is_resumable returns one if session is complete and contains a session ID or ticket. It returns zero otherwise. Note this function does not ensure session will be resumed. It may be expired, dropped by the server, or associated with incompatible parameters.

SSL_SESSION_has_ticket returns one if session has a ticket and zero otherwise.

SSL_SESSION_get0_ticket sets *out_ticket and *out_len to session's ticket, or NULL and zero if it does not have one. out_ticket may be NULL if only the ticket length is needed.

SSL_SESSION_set_ticket sets session's ticket to ticket. It returns one on success and zero on error. This function may be useful in writing tests but otherwise should not be used.

SSL_SESSION_get_ticket_lifetime_hint returns ticket lifetime hint of session in seconds or zero if none was set.

SSL_SESSION_get0_cipher returns the cipher negotiated by the connection which established session.

Note that, in TLS 1.3, there is no guarantee that resumptions with session will use that cipher. Prefer calling SSL_get_current_cipher on the SSL instead.

SSL_SESSION_has_peer_sha256 returns one if session has a SHA-256 hash of the peer's certificate retained and zero if the peer did not present a certificate or if this was not enabled when session was created. See also SSL_CTX_set_retain_only_sha256_of_client_certs.

SSL_SESSION_get0_peer_sha256 sets *out_ptr and *out_len to the SHA-256 hash of the peer certificate retained in session, or NULL and zero if it does not have one. See also SSL_CTX_set_retain_only_sha256_of_client_certs.

SSL_SESS_CACHE_OFF disables all session caching.

SSL_SESS_CACHE_CLIENT enables session caching for a client. The internal cache is never used on a client, so this only enables the callbacks.

SSL_SESS_CACHE_SERVER enables session caching for a server.

SSL_SESS_CACHE_BOTH enables session caching for both client and server.

SSL_SESS_CACHE_NO_AUTO_CLEAR disables automatically calling SSL_CTX_flush_sessions every 255 connections.

SSL_SESS_CACHE_NO_INTERNAL_LOOKUP, on a server, disables looking up a session from the internal session cache.

SSL_SESS_CACHE_NO_INTERNAL_STORE, on a server, disables storing sessions in the internal session cache.

SSL_SESS_CACHE_NO_INTERNAL, on a server, disables the internal session cache.

SSL_CTX_set_session_cache_mode sets the session cache mode bits for ctx to mode. It returns the previous value.

SSL_CTX_get_session_cache_mode returns the session cache mode bits for ctx

SSL_set_session, for a client, configures ssl to offer to resume session in the initial handshake and returns one. The caller retains ownership of session. Note that configuring a session assumes the authentication in the session is valid. For callers that wish to revalidate the session before offering, see SSL_SESSION_get0_peer_certificates, SSL_SESSION_get0_signed_cert_timestamp_list, and SSL_SESSION_get0_ocsp_response.

It is an error to call this function after the handshake has begun.

SSL_DEFAULT_SESSION_TIMEOUT is the default lifetime, in seconds, of a session in TLS 1.2 or earlier. This is how long we are willing to use the secret to encrypt traffic without fresh key material.

SSL_DEFAULT_SESSION_PSK_DHE_TIMEOUT is the default lifetime, in seconds, of a session for TLS 1.3 psk_dhe_ke. This is how long we are willing to use the secret as an authenticator.

SSL_DEFAULT_SESSION_AUTH_TIMEOUT is the default non-renewable lifetime, in seconds, of a TLS 1.3 session. This is how long we are willing to trust the signature in the initial handshake.

SSL_CTX_set_timeout sets the lifetime, in seconds, of TLS 1.2 (or earlier) sessions created in ctx to timeout.

SSL_CTX_set_session_psk_dhe_timeout sets the lifetime, in seconds, of TLS 1.3 sessions created in ctx to timeout.

SSL_CTX_get_timeout returns the lifetime, in seconds, of TLS 1.2 (or earlier) sessions created in ctx.

SSL_MAX_SID_CTX_LENGTH is the maximum length of a session ID context.

SSL_CTX_set_session_id_context sets ctx's session ID context to sid_ctx. It returns one on success and zero on error. The session ID context is an application-defined opaque byte string. A session will not be used in a connection without a matching session ID context.

For a server, if SSL_VERIFY_PEER is enabled, it is an error to not set a session ID context.

SSL_set_session_id_context sets ssl's session ID context to sid_ctx. It returns one on success and zero on error. See also SSL_CTX_set_session_id_context.

SSL_get0_session_id_context returns a pointer to ssl's session ID context and sets *out_len to its length. It returns NULL on error.

SSL_SESSION_CACHE_MAX_SIZE_DEFAULT is the default maximum size of a session cache.

SSL_CTX_sess_set_cache_size sets the maximum size of ctx's internal session cache to size. It returns the previous value.

SSL_CTX_sess_get_cache_size returns the maximum size of ctx's internal session cache.

SSL_CTX_sess_number returns the number of sessions in ctx's internal session cache.

SSL_CTX_add_session inserts session into ctx's internal session cache. It returns one on success and zero on error or if session is already in the cache. The caller retains its reference to session.

SSL_CTX_remove_session removes session from ctx's internal session cache. It returns one on success and zero if session was not in the cache.

SSL_CTX_flush_sessions removes all sessions from ctx which have expired as of time time. If time is zero, all sessions are removed.

SSL_CTX_sess_set_new_cb sets the callback to be called when a new session is established and ready to be cached. If the session cache is disabled (the appropriate one of SSL_SESS_CACHE_CLIENT or SSL_SESS_CACHE_SERVER is unset), the callback is not called.

The callback is passed a reference to session. It returns one if it takes ownership (and then calls SSL_SESSION_free when done) and zero otherwise. A consumer which places session into an in-memory cache will likely return one, with the cache calling SSL_SESSION_free. A consumer which serializes session with SSL_SESSION_to_bytes may not need to retain session and will likely return zero. Returning one is equivalent to calling SSL_SESSION_up_ref and then returning zero.

Note: For a client, the callback may be called on abbreviated handshakes if a ticket is renewed. Further, it may not be called until some time after SSL_do_handshake or SSL_connect completes if False Start is enabled. Thus it's recommended to use this callback over calling SSL_get_session on handshake completion.

SSL_CTX_sess_get_new_cb returns the callback set by SSL_CTX_sess_set_new_cb.

SSL_CTX_sess_set_remove_cb sets a callback which is called when a session is removed from the internal session cache.

TODO(davidben): What is the point of this callback? It seems useless since it only fires on sessions in the internal cache.

SSL_CTX_sess_get_remove_cb returns the callback set by SSL_CTX_sess_set_remove_cb.

SSL_CTX_sess_set_get_cb sets a callback to look up a session by ID for a server. The callback is passed the session ID and should return a matching SSL_SESSION or NULL if not found. It should set *out_copy to zero and return a new reference to the session. This callback is not used for a client.

For historical reasons, if *out_copy is set to one (default), the SSL library will take a new reference to the returned SSL_SESSION, expecting the callback to return a non-owning pointer. This is not recommended. If ctx and thus the callback is used on multiple threads, the session may be removed and invalidated before the SSL library calls SSL_SESSION_up_ref, whereas the callback may synchronize internally.

To look up a session asynchronously, the callback may return SSL_magic_pending_session_ptr. See the documentation for that function and SSL_ERROR_PENDING_SESSION.

If the internal session cache is enabled, the callback is only consulted if the internal cache does not return a match.

SSL_CTX_sess_get_get_cb returns the callback set by SSL_CTX_sess_set_get_cb.

SSL_magic_pending_session_ptr returns a magic SSL_SESSION* which indicates that the session isn't currently unavailable. SSL_get_error will then return SSL_ERROR_PENDING_SESSION and the handshake can be retried later when the lookup has completed.

SSL_DEFAULT_TICKET_KEY_ROTATION_INTERVAL is the interval with which the default session ticket encryption key is rotated, if in use. If any non-default ticket encryption mechanism is configured, automatic rotation is disabled.

SSL_CTX_get_tlsext_ticket_keys writes ctx's session ticket key material to len bytes of out. It returns one on success and zero if len is not 48. If out is NULL, it returns 48 instead.

SSL_CTX_set_tlsext_ticket_keys sets ctx's session ticket key material to len bytes of in. It returns one on success and zero if len is not 48. If in is NULL, it returns 48 instead.

SSL_TICKET_KEY_NAME_LEN is the length of the key name prefix of a session ticket.

SSL_CTX_set_tlsext_ticket_key_cb sets the ticket callback to callback and returns one. callback will be called when encrypting a new ticket and when decrypting a ticket from the client.

In both modes, ctx and hmac_ctx will already have been initialized with EVP_CIPHER_CTX_init and HMAC_CTX_init, respectively. callback configures hmac_ctx with an HMAC digest and key, and configures ctx for encryption or decryption, based on the mode.

When encrypting a new ticket, encrypt will be one. It writes a public 16-byte key name to key_name and a fresh IV to iv. The output IV length must match EVP_CIPHER_CTX_iv_length of the cipher selected. In this mode, callback returns 1 on success, 0 to decline sending a ticket, and -1 on error.

When decrypting a ticket, encrypt will be zero. key_name will point to a 16-byte key name and iv points to an IV. The length of the IV consumed must match EVP_CIPHER_CTX_iv_length of the cipher selected. In this mode, callback returns -1 to abort the handshake, 0 if the ticket key was unrecognized, and 1 or 2 on success. If it returns 2, the ticket will be renewed. This may be used to re-key the ticket.

WARNING: callback wildly breaks the usual return value convention and is called in two different modes.

ssl_ticket_aead_result_t enumerates the possible results from decrypting a ticket with an SSL_TICKET_AEAD_METHOD.

ssl_ticket_aead_method_st (aka SSL_TICKET_AEAD_METHOD) contains methods for encrypting and decrypting session tickets.

SSL_CTX_set_ticket_aead_method configures a custom ticket AEAD method table on ctx. aead_method must remain valid for the lifetime of ctx.

SSL_process_tls13_new_session_ticket processes an unencrypted TLS 1.3 NewSessionTicket message from buf and returns a resumable SSL_SESSION, or NULL on error. The caller takes ownership of the returned session and must call SSL_SESSION_free to free it.

buf contains buf_len bytes that represents a complete NewSessionTicket message including its header, i.e., one byte for the type (0x04) and three bytes for the length. buf must contain only one such message.

This function may be used to process NewSessionTicket messages in TLS 1.3 clients that are handling the record layer externally.

SSL_CTX_set_num_tickets configures ctx to send num_tickets immediately after a successful TLS 1.3 handshake as a server. It returns one. Large values of num_tickets will be capped within the library.

By default, BoringSSL sends two tickets.

SSL_CTX_get_num_tickets returns the number of tickets ctx will send immediately after a successful TLS 1.3 handshake as a server.

SSL_GROUP_* define TLS group IDs.

SSL_CTX_set1_group_ids sets the preferred groups for ctx to group_ids. Each element of group_ids should be one of the SSL_GROUP_* constants. It returns one on success and zero on failure.

SSL_set1_group_ids sets the preferred groups for ssl to group_ids. Each element of group_ids should be one of the SSL_GROUP_* constants. It returns one on success and zero on failure.

SSL_get_group_id returns the ID of the group used by ssl's most recently completed handshake, or 0 if not applicable.

SSL_get_group_name returns a human-readable name for the group specified by the given TLS group ID, or NULL if the group is unknown.

SSL_get_all_group_names outputs a list of possible strings SSL_get_group_name may return in this version of BoringSSL. It writes at most max_out entries to out and returns the total number it would have written, if max_out had been large enough. max_out may be initially set to zero to size the output.

This function is only intended to help initialize tables in callers that want possible strings pre-declared. This list would not be suitable to set a list of supported features. It is in no particular order, and may contain placeholder, experimental, or deprecated values that do not apply to every caller. Future versions of BoringSSL may also return strings not in this list, so this does not apply if, say, sending strings across services.

The following APIs also configure Diffie-Hellman groups, but use NID_* constants instead of SSL_GROUP_* constants. These are provided for OpenSSL compatibility. Where NIDs are unstable constants specific to OpenSSL and BoringSSL, group IDs are defined by the TLS protocol. Prefer the group ID representation if storing persistently, or exporting to another process or library.

SSL_CTX_set1_groups sets the preferred groups for ctx to be groups. Each element of groups should be a NID_* constant from nid.h. It returns one on success and zero on failure.

SSL_set1_groups sets the preferred groups for ssl to be groups. Each element of groups should be a NID_* constant from nid.h. It returns one on success and zero on failure.

SSL_CTX_set1_groups_list decodes groups as a colon-separated list of group names (e.g. "X25519" or "P-256") and sets ctx's preferred groups to the result. It returns one on success and zero on failure.

SSL_set1_groups_list decodes groups as a colon-separated list of group names (e.g. "X25519" or "P-256") and sets ssl's preferred groups to the result. It returns one on success and zero on failure.

SSL_get_negotiated_group returns the NID of the group used by ssl's most recently completed handshake, or NID_undef if not applicable.

SSL_VERIFY_NONE, on a client, verifies the server certificate but does not make errors fatal. The result may be checked with SSL_get_verify_result. On a server it does not request a client certificate. This is the default.

SSL_VERIFY_PEER, on a client, makes server certificate errors fatal. On a server it requests a client certificate and makes errors fatal. However, anonymous clients are still allowed. See SSL_VERIFY_FAIL_IF_NO_PEER_CERT.

SSL_VERIFY_FAIL_IF_NO_PEER_CERT configures a server to reject connections if the client declines to send a certificate. This flag must be used together with SSL_VERIFY_PEER, otherwise it won't work.

SSL_VERIFY_PEER_IF_NO_OBC configures a server to request a client certificate if and only if Channel ID is not negotiated.

SSL_CTX_set_verify configures certificate verification behavior. mode is one of the SSL_VERIFY_* values defined above. callback should be NULL.

If callback is non-NULL, it is called as in X509_STORE_CTX_set_verify_cb, which is a deprecated and fragile mechanism to run the default certificate verification process, but suppress individual errors in it. See X509_STORE_CTX_set_verify_cb for details, If set, the callback may use SSL_get_ex_data_X509_STORE_CTX_idx with X509_STORE_CTX_get_ex_data to look up the SSL from store_ctx.

WARNING: callback is not suitable for implementing custom certificate check, accepting all certificates, or extracting the certificate after verification. It does not replace the default process and is called multiple times throughout that process. It is also very difficult to implement this callback safely, without inadvertently relying on implementation details or making incorrect assumptions about when the callback is called.

Instead, use SSL_CTX_set_custom_verify or SSL_CTX_set_cert_verify_callback to customize certificate verification. Those callbacks can inspect the peer-sent chain, call X509_verify_cert and inspect the result, or perform other operations more straightforwardly.

SSL_set_verify configures certificate verification behavior. mode is one of the SSL_VERIFY_* values defined above. callback should be NULL.

If callback is non-NULL, it is called as in X509_STORE_CTX_set_verify_cb, which is a deprecated and fragile mechanism to run the default certificate verification process, but suppress individual errors in it. See X509_STORE_CTX_set_verify_cb for details, If set, the callback may use SSL_get_ex_data_X509_STORE_CTX_idx with X509_STORE_CTX_get_ex_data to look up the SSL from store_ctx.

WARNING: callback is not suitable for implementing custom certificate check, accepting all certificates, or extracting the certificate after verification. It does not replace the default process and is called multiple times throughout that process. It is also very difficult to implement this callback safely, without inadvertently relying on implementation details or making incorrect assumptions about when the callback is called.

Instead, use SSL_set_custom_verify or SSL_set_cert_verify_callback to customize certificate verification. Those callbacks can inspect the peer-sent chain, call X509_verify_cert and inspect the result, or perform other operations more straightforwardly.

SSL_CTX_set_custom_verify configures certificate verification. mode is one of the SSL_VERIFY_* values defined above. callback performs the certificate verification.

The callback may call SSL_get0_peer_certificates for the certificate chain to validate. The callback should return ssl_verify_ok if the certificate is valid. If the certificate is invalid, the callback should return ssl_verify_invalid and optionally set *out_alert to an alert to send to the peer. Some useful alerts include SSL_AD_CERTIFICATE_EXPIRED, SSL_AD_CERTIFICATE_REVOKED, SSL_AD_UNKNOWN_CA, SSL_AD_BAD_CERTIFICATE, SSL_AD_CERTIFICATE_UNKNOWN, and SSL_AD_INTERNAL_ERROR. See RFC 5246 section 7.2.2 for their precise meanings. If unspecified, SSL_AD_CERTIFICATE_UNKNOWN will be sent by default.

To verify a certificate asynchronously, the callback may return ssl_verify_retry. The handshake will then pause with SSL_get_error returning SSL_ERROR_WANT_CERTIFICATE_VERIFY.

SSL_set_custom_verify behaves like SSL_CTX_set_custom_verify but configures an individual SSL.

SSL_CTX_get_verify_mode returns ctx's verify mode, set by SSL_CTX_set_verify.

SSL_get_verify_mode returns ssl's verify mode, set by SSL_CTX_set_verify or SSL_set_verify. It returns -1 on error.

SSL_CTX_get_verify_callback returns the callback set by SSL_CTX_set_verify.

SSL_get_verify_callback returns the callback set by SSL_CTX_set_verify or SSL_set_verify.

SSL_set1_host sets a DNS name that will be required to be present in the verified leaf certificate. It returns one on success and zero on error.

Note: unless _some_ name checking is performed, certificate validation is ineffective. Simply checking that a host has some certificate from a CA is rarely meaningful—you have to check that the CA believed that the host was who you expect to be talking to.

By default, both subject alternative names and the subject's common name attribute are checked. The latter has long been deprecated, so callers should call SSL_set_hostflags with X509_CHECK_FLAG_NEVER_CHECK_SUBJECT to use the standard behavior. https://crbug.com/boringssl/464 tracks fixing the default.

SSL_set_hostflags calls X509_VERIFY_PARAM_set_hostflags on the X509_VERIFY_PARAM associated with this SSL*. flags should be some combination of the X509_CHECK_* constants.

SSL_CTX_set_verify_depth sets the maximum depth of a certificate chain accepted in verification. This count excludes both the target certificate and the trust anchor (root certificate).

SSL_set_verify_depth sets the maximum depth of a certificate chain accepted in verification. This count excludes both the target certificate and the trust anchor (root certificate).

SSL_CTX_get_verify_depth returns the maximum depth of a certificate accepted in verification.

SSL_get_verify_depth returns the maximum depth of a certificate accepted in verification.

SSL_CTX_set1_param sets verification parameters from param. It returns one on success and zero on failure. The caller retains ownership of param.

SSL_set1_param sets verification parameters from param. It returns one on success and zero on failure. The caller retains ownership of param.

SSL_CTX_get0_param returns ctx's X509_VERIFY_PARAM for certificate verification. The caller must not release the returned pointer but may call functions on it to configure it.

SSL_get0_param returns ssl's X509_VERIFY_PARAM for certificate verification. The caller must not release the returned pointer but may call functions on it to configure it.

SSL_CTX_set_purpose sets ctx's X509_VERIFY_PARAM's 'purpose' parameter to purpose. It returns one on success and zero on error.

SSL_set_purpose sets ssl's X509_VERIFY_PARAM's 'purpose' parameter to purpose. It returns one on success and zero on error.

SSL_CTX_set_trust sets ctx's X509_VERIFY_PARAM's 'trust' parameter to trust. It returns one on success and zero on error.

SSL_set_trust sets ssl's X509_VERIFY_PARAM's 'trust' parameter to trust. It returns one on success and zero on error.

SSL_CTX_set_cert_store sets ctx's certificate store to store. It takes ownership of store. The store is used for certificate verification.

The store is also used for the auto-chaining feature, but this is deprecated. See also SSL_MODE_NO_AUTO_CHAIN.

SSL_CTX_get_cert_store returns ctx's certificate store.

SSL_CTX_set_default_verify_paths calls X509_STORE_set_default_paths on ctx's store. See that function for details.

Using this function is not recommended. In OpenSSL, these defaults are determined by OpenSSL's install prefix. There is no corresponding concept for BoringSSL. Future versions of BoringSSL may change or remove this functionality.

SSL_CTX_load_verify_locations calls X509_STORE_load_locations on ctx's store. See that function for details.

SSL_get_verify_result returns the result of certificate verification. It is either X509_V_OK or a X509_V_ERR_* value.

SSL_alert_from_verify_result returns the SSL alert code, such as SSL_AD_CERTIFICATE_EXPIRED, that corresponds to an X509_V_ERR_* value. The return value is always an alert, even when result is X509_V_OK.

SSL_get_ex_data_X509_STORE_CTX_idx returns the ex_data index used to look up the SSL associated with an X509_STORE_CTX in the verify callback.

SSL_CTX_set_cert_verify_callback sets a custom callback to be called on certificate verification rather than X509_verify_cert. store_ctx contains the verification parameters. The callback should return one on success and zero on fatal error. It may use X509_STORE_CTX_set_error to set a verification result.

The callback may use SSL_get_ex_data_X509_STORE_CTX_idx to recover the SSL object from store_ctx.

SSL_enable_signed_cert_timestamps causes ssl (which must be the client end of a connection) to request SCTs from the server. See https://tools.ietf.org/html/rfc6962.

Call SSL_get0_signed_cert_timestamp_list to recover the SCT after the handshake.

SSL_CTX_enable_signed_cert_timestamps enables SCT requests on all client SSL objects created from ctx.

Call SSL_get0_signed_cert_timestamp_list to recover the SCT after the handshake.

SSL_enable_ocsp_stapling causes ssl (which must be the client end of a connection) to request a stapled OCSP response from the server.

Call SSL_get0_ocsp_response to recover the OCSP response after the handshake.

SSL_CTX_enable_ocsp_stapling enables OCSP stapling on all client SSL objects created from ctx.

Call SSL_get0_ocsp_response to recover the OCSP response after the handshake.

SSL_CTX_set0_verify_cert_store sets an X509_STORE that will be used exclusively for certificate verification and returns one. Ownership of store is transferred to the SSL_CTX.

SSL_CTX_set1_verify_cert_store sets an X509_STORE that will be used exclusively for certificate verification and returns one. An additional reference to store will be taken.

SSL_set0_verify_cert_store sets an X509_STORE that will be used exclusively for certificate verification and returns one. Ownership of store is transferred to the SSL.

SSL_set1_verify_cert_store sets an X509_STORE that will be used exclusively for certificate verification and returns one. An additional reference to store will be taken.

SSL_CTX_set_verify_algorithm_prefs configures ctx to use prefs as the preference list when verifying signatures from the peer's long-term key. It returns one on zero on error. prefs should not include the internal-only value SSL_SIGN_RSA_PKCS1_MD5_SHA1.

SSL_set_verify_algorithm_prefs configures ssl to use prefs as the preference list when verifying signatures from the peer's long-term key. It returns one on zero on error. prefs should not include the internal-only value SSL_SIGN_RSA_PKCS1_MD5_SHA1.

SSL_set_client_CA_list sets ssl's client certificate CA list to name_list. It takes ownership of name_list.

SSL_CTX_set_client_CA_list sets ctx's client certificate CA list to name_list. It takes ownership of name_list.

SSL_set0_client_CAs sets ssl's client certificate CA list to name_list, which should contain DER-encoded distinguished names (RFC 5280). It takes ownership of name_list.

SSL_set0_CA_names sets ssl's CA name list for the certificate authorities extension to name_list, which should contain DER-encoded distinguished names (RFC 5280). It takes ownership of name_list.

SSL_CTX_set0_client_CAs sets ctx's client certificate CA list to name_list, which should contain DER-encoded distinguished names (RFC 5280). It takes ownership of name_list.

SSL_get_client_CA_list returns ssl's client certificate CA list. If ssl has not been configured as a client, this is the list configured by SSL_CTX_set_client_CA_list.

If configured as a client, it returns the client certificate CA list sent by the server. In this mode, the behavior is undefined except during the callbacks set by SSL_CTX_set_cert_cb and SSL_CTX_set_client_cert_cb or when the handshake is paused because of them.

SSL_get0_server_requested_CAs returns the CAs sent by a server to guide a client in certificate selection. They are a series of DER-encoded X.509 names. This function may only be called during a callback set by SSL_CTX_set_cert_cb or when the handshake is paused because of it.

The returned stack is owned by ssl, as are its contents. It should not be used past the point where the handshake is restarted after the callback.

SSL_CTX_get_client_CA_list returns ctx's client certificate CA list.

SSL_add_client_CA appends x509's subject to the client certificate CA list. It returns one on success or zero on error. The caller retains ownership of x509.

SSL_CTX_add_client_CA appends x509's subject to the client certificate CA list. It returns one on success or zero on error. The caller retains ownership of x509.

SSL_load_client_CA_file opens file and reads PEM-encoded certificates from it. It returns a newly-allocated stack of the certificate subjects or NULL on error. Duplicates in file are ignored.

SSL_dup_CA_list makes a deep copy of list. It returns the new list on success or NULL on allocation error.

SSL_add_file_cert_subjects_to_stack behaves like SSL_load_client_CA_file but appends the result to out. It returns one on success or zero on error.

SSL_add_bio_cert_subjects_to_stack behaves like SSL_add_file_cert_subjects_to_stack but reads from bio.

SSL_set_tlsext_host_name, for a client, configures ssl to advertise name in the server_name extension. It returns one on success and zero on error.

SSL_get_servername, for a server, returns the hostname supplied by the client or NULL if there was none. The type argument must be TLSEXT_NAMETYPE_host_name.

SSL_get_servername_type, for a server, returns TLSEXT_NAMETYPE_host_name if the client sent a hostname and -1 otherwise.

SSL_CTX_set_tlsext_servername_callback configures callback to be called on the server after ClientHello extensions have been parsed and returns one. The callback may use SSL_get_servername to examine the server_name extension and returns a SSL_TLSEXT_ERR_* value. The value of arg may be set by calling SSL_CTX_set_tlsext_servername_arg.

If the callback returns SSL_TLSEXT_ERR_NOACK, the server_name extension is not acknowledged in the ServerHello. If the return value is SSL_TLSEXT_ERR_ALERT_FATAL, then *out_alert is the alert to send, defaulting to SSL_AD_UNRECOGNIZED_NAME. SSL_TLSEXT_ERR_ALERT_WARNING is ignored and treated as SSL_TLSEXT_ERR_OK.

SSL_CTX_set_tlsext_servername_arg sets the argument to the servername callback and returns one. See SSL_CTX_set_tlsext_servername_callback.

SSL_TLSEXT_ERR_* are values returned by some extension-related callbacks.

SSL_set_SSL_CTX changes ssl's SSL_CTX. ssl will use the certificate-related settings from ctx, and SSL_get_SSL_CTX will report ctx. This function may be used during the callbacks registered by SSL_CTX_set_select_certificate_cb, SSL_CTX_set_tlsext_servername_callback, and SSL_CTX_set_cert_cb or when the handshake is paused from them. It is typically used to switch certificates based on SNI.

Note the session cache and related settings will continue to use the initial SSL_CTX. Callers should use SSL_CTX_set_session_id_context to partition the session cache between different domains.

TODO(davidben): Should other settings change after this call?

SSL_CTX_set_alpn_protos sets the client ALPN protocol list on ctx to protos. protos must be in wire-format (i.e. a series of non-empty, 8-bit length-prefixed strings), or the empty string to disable ALPN. It returns zero on success and one on failure. Configuring a non-empty string enables ALPN on a client.

WARNING: this function is dangerous because it breaks the usual return value convention.

SSL_set_alpn_protos sets the client ALPN protocol list on ssl to protos. protos must be in wire-format (i.e. a series of non-empty, 8-bit length-prefixed strings), or the empty string to disable ALPN. It returns zero on success and one on failure. Configuring a non-empty string enables ALPN on a client.

WARNING: this function is dangerous because it breaks the usual return value convention.

SSL_CTX_set_alpn_select_cb sets a callback function on ctx that is called during ClientHello processing in order to select an ALPN protocol from the client's list of offered protocols. SSL_select_next_proto is an optional utility function which may be useful in implementing this callback.

The callback is passed a wire-format (i.e. a series of non-empty, 8-bit length-prefixed strings) ALPN protocol list in in. To select a protocol, the callback should set *out and *out_len to the selected protocol and return SSL_TLSEXT_ERR_OK on success. It does not pass ownership of the buffer, so *out should point to a static string, a buffer that outlives the callback call, or the corresponding entry in in.

If the server supports ALPN, but there are no protocols in common, the callback should return SSL_TLSEXT_ERR_ALERT_FATAL to abort the connection with a no_application_protocol alert.

If the server does not support ALPN, it can return SSL_TLSEXT_ERR_NOACK to continue the handshake without negotiating a protocol. This may be useful if multiple server configurations share an SSL_CTX, only some of which have ALPN protocols configured.

SSL_TLSEXT_ERR_ALERT_WARNING is ignored and will be treated as SSL_TLSEXT_ERR_NOACK.

The callback will only be called if the client supports ALPN. Callers that wish to require ALPN for all clients must check SSL_get0_alpn_selected after the handshake. In QUIC connections, this is done automatically.

The cipher suite is selected before negotiating ALPN. The callback may use SSL_get_pending_cipher to query the cipher suite. This may be used to implement HTTP/2's cipher suite constraints.

SSL_get0_alpn_selected gets the selected ALPN protocol (if any) from ssl. On return it sets *out_data to point to *out_len bytes of protocol name (not including the leading length-prefix byte). If the server didn't respond with a negotiated protocol then *out_len will be zero.

SSL_CTX_set_allow_unknown_alpn_protos configures client connections on ctx to allow unknown ALPN protocols from the server. Otherwise, by default, the client will require that the protocol be advertised in SSL_CTX_set_alpn_protos.

SSL_add_application_settings configures ssl to enable ALPS with ALPN protocol proto, sending an ALPS value of settings. It returns one on success and zero on error. If proto is negotiated via ALPN and the peer supports ALPS, settings will be sent to the peer. The peer's ALPS value can be retrieved with SSL_get0_peer_application_settings.

On the client, this function should be called before the handshake, once for each supported ALPN protocol which uses ALPS. proto must be included in the client's ALPN configuration (see SSL_CTX_set_alpn_protos and SSL_set_alpn_protos). On the server, ALPS can be preconfigured for each protocol as in the client, or configuration can be deferred to the ALPN callback (see SSL_CTX_set_alpn_select_cb), in which case only the selected protocol needs to be configured.

ALPS can be independently configured from 0-RTT, however changes in protocol settings will fallback to 1-RTT to negotiate the new value, so it is recommended for settings to be relatively stable.

SSL_get0_peer_application_settings sets *out_data and *out_len to a buffer containing the peer's ALPS value, or the empty string if ALPS was not negotiated. Note an empty string could also indicate the peer sent an empty settings value. Use SSL_has_application_settings to check if ALPS was negotiated. The output buffer is owned by ssl and is valid until the next time ssl is modified.

SSL_has_application_settings returns one if ALPS was negotiated on this connection and zero otherwise.

SSL_set_alps_use_new_codepoint configures whether to use the new ALPS codepoint. By default, the old codepoint is used.

ssl_cert_compression_func_t is a pointer to a function that performs compression. It must write the compressed representation of in to out, returning one on success and zero on error. The results of compressing certificates are not cached internally. Implementations may wish to implement their own cache if they expect it to be useful given the certificates that they serve.

ssl_cert_decompression_func_t is a pointer to a function that performs decompression. The compressed data from the peer is passed as in and the decompressed result must be exactly uncompressed_len bytes long. It returns one on success, in which case *out must be set to the result of decompressing in, or zero on error. Setting *out transfers ownership, i.e. CRYPTO_BUFFER_free will be called on *out at some point in the future. The results of decompressions are not cached internally. Implementations may wish to implement their own cache if they expect it to be useful.

SSL_CTX_add_cert_compression_alg registers a certificate compression algorithm on ctx with ID alg_id. (The value of alg_id should be an IANA assigned value and each can only be registered once.)

One of the function pointers may be NULL to avoid having to implement both sides of a compression algorithm if you're only going to use it in one direction. In this case, the unimplemented direction acts like it was never configured.

For a server, algorithms are registered in preference order with the most preferable first. It returns one on success or zero on error.

SSL_CTX_set_next_protos_advertised_cb sets a callback that is called when a TLS server needs a list of supported protocols for Next Protocol Negotiation.

If the callback wishes to advertise NPN to the client, it should return SSL_TLSEXT_ERR_OK and then set *out and *out_len to describe to a buffer containing a (possibly empty) list of supported protocols in wire format. That is, each protocol is prefixed with a 1-byte length, then concatenated. From there, the client will select a protocol, possibly one not on the server's list. The caller can use SSL_get0_next_proto_negotiated after the handshake completes to query the final protocol.

The returned buffer must remain valid and unmodified for at least the duration of the SSL operation (e.g. SSL_do_handshake) that triggered the callback.

If the caller wishes not to advertise NPN, it should return SSL_TLSEXT_ERR_NOACK. No NPN extension will be included in the ServerHello, and the TLS server will behave as if it does not implement NPN.

SSL_CTX_set_next_proto_select_cb sets a callback that is called when a client needs to select a protocol from the server's provided list, passed in wire format in in_len bytes from in. The callback can assume that in is syntactically valid. SSL_select_next_proto is an optional utility function which may be useful in implementing this callback.

On success, the callback should return SSL_TLSEXT_ERR_OK and set *out and *out_len to describe a buffer containing the selected protocol, or an empty buffer to select no protocol. The returned buffer may point within in, or it may point to some other buffer that remains valid and unmodified for at least the duration of the SSL operation (e.g. SSL_do_handshake) that triggered the callback.

Returning any other value indicates a fatal error and will terminate the TLS connection. To proceed without selecting a protocol, the callback must return SSL_TLSEXT_ERR_OK and set *out and *out_len to an empty buffer. (E.g. NULL and zero, respectively.)

Configuring this callback enables NPN on a client. Although the callback can then decline to negotiate a protocol, merely configuring the callback causes the client to offer NPN in the ClientHello. Callers thus should not configure this callback in TLS client contexts that are not intended to use NPN.

SSL_get0_next_proto_negotiated sets *out_data and *out_len to point to the client's requested protocol for this connection. If the client didn't request any protocol, then *out_len is set to zero.

Note that the client can request any protocol it chooses. The value returned from this function need not be a member of the list of supported protocols provided by the server.

SSL_select_next_proto implements the standard protocol selection for either ALPN servers or NPN clients. It is expected that this function is called from the callback set by SSL_CTX_set_alpn_select_cb or SSL_CTX_set_next_proto_select_cb.

peer and supported contain the peer and locally-configured protocols, respectively. This function finds the first protocol in peer which is also in supported. If one was found, it sets *out and *out_len to point to it and returns OPENSSL_NPN_NEGOTIATED. Otherwise, it returns OPENSSL_NPN_NO_OVERLAP and sets *out and *out_len to the first supported protocol.

In ALPN, the server should only select protocols among those that the client offered. Thus, if this function returns OPENSSL_NPN_NO_OVERLAP, the caller should ignore *out and return SSL_TLSEXT_ERR_ALERT_FATAL from SSL_CTX_set_alpn_select_cb's callback to indicate there was no match.

In NPN, the client may either select one of the server's protocols, or an "opportunistic" protocol as described in Section 6 of draft-agl-tls-nextprotoneg-03. When this function returns OPENSSL_NPN_NO_OVERLAP, *out implicitly selects the first supported protocol for use as the opportunistic protocol. The caller may use it, ignore it and select a different opportunistic protocol, or ignore it and select no protocol (empty string).

peer and supported must be vectors of 8-bit, length-prefixed byte strings. The length byte itself is not included in the length. A byte string of length 0 is invalid. No byte string may be truncated. supported must be non-empty; a caller that supports no ALPN/NPN protocols should skip negotiating the extension, rather than calling this function. If any of these preconditions do not hold, this function will return OPENSSL_NPN_NO_OVERLAP and set *out and *out_len to an empty buffer for robustness, but callers are not recommended to rely on this. An empty buffer is not a valid output for SSL_CTX_set_alpn_select_cb's callback.

WARNING: *out and *out_len may alias either peer or supported and may not be used after one of those buffers is modified or released. Additionally, this function is not const-correct for compatibility reasons. Although *out is a non-const pointer, callers may not modify the buffer though *out.

SSL_CTX_set_tls_channel_id_enabled configures whether connections associated with ctx should enable Channel ID as a server.

SSL_set_tls_channel_id_enabled configures whether ssl should enable Channel ID as a server.

SSL_CTX_set1_tls_channel_id configures a TLS client to send a TLS Channel ID to compatible servers. private_key must be a P-256 EC key. It returns one on success and zero on error.

SSL_set1_tls_channel_id configures a TLS client to send a TLS Channel ID to compatible servers. private_key must be a P-256 EC key. It returns one on success and zero on error.

SSL_get_tls_channel_id gets the client's TLS Channel ID from a server SSL and copies up to the first max_out bytes into out. The Channel ID consists of the client's P-256 public key as an (x,y) pair where each is a 32-byte, big-endian field element. It returns 0 if the client didn't offer a Channel ID and the length of the complete Channel ID otherwise. This function always returns zero if ssl is a client.

srtp_protection_profile_st (aka SRTP_PROTECTION_PROFILE) is an SRTP profile for use with the use_srtp extension.

SRTP_* define constants for SRTP profiles.

SSL_CTX_set_srtp_profiles enables SRTP for all SSL objects created from ctx. profile contains a colon-separated list of profile names. It returns one on success and zero on failure.

SSL_set_srtp_profiles enables SRTP for ssl. profile contains a colon-separated list of profile names. It returns one on success and zero on failure.

SSL_get_srtp_profiles returns the SRTP profiles supported by ssl.

SSL_get_selected_srtp_profile returns the selected SRTP profile, or NULL if SRTP was not negotiated.

PSK_MAX_IDENTITY_LEN is the maximum supported length of a PSK identity, excluding the NUL terminator.

PSK_MAX_PSK_LEN is the maximum supported length of a pre-shared key.

SSL_CTX_set_psk_client_callback sets the callback to be called when PSK is negotiated on the client. This callback must be set to enable PSK cipher suites on the client.

The callback is passed the identity hint in hint or NULL if none was provided. It should select a PSK identity and write the identity and the corresponding PSK to identity and psk, respectively. The identity is written as a NUL-terminated C string of length (excluding the NUL terminator) at most max_identity_len. The PSK's length must be at most max_psk_len. The callback returns the length of the PSK or 0 if no suitable identity was found.

SSL_set_psk_client_callback sets the callback to be called when PSK is negotiated on the client. This callback must be set to enable PSK cipher suites on the client. See also SSL_CTX_set_psk_client_callback.

SSL_CTX_set_psk_server_callback sets the callback to be called when PSK is negotiated on the server. This callback must be set to enable PSK cipher suites on the server.

The callback is passed the identity in identity. It should write a PSK of length at most max_psk_len to psk and return the number of bytes written or zero if the PSK identity is unknown.

SSL_set_psk_server_callback sets the callback to be called when PSK is negotiated on the server. This callback must be set to enable PSK cipher suites on the server. See also SSL_CTX_set_psk_server_callback.

SSL_CTX_use_psk_identity_hint configures server connections to advertise an identity hint of identity_hint. It returns one on success and zero on error.

SSL_use_psk_identity_hint configures server connections to advertise an identity hint of identity_hint. It returns one on success and zero on error.

SSL_get_psk_identity_hint returns the PSK identity hint advertised for ssl or NULL if there is none.

SSL_get_psk_identity, after the handshake completes, returns the PSK identity that was negotiated by ssl or NULL if PSK was not used.

SSL_CREDENTIAL_new_delegated returns a new, empty delegated credential, or NULL on error. Callers should release the result with SSL_CREDENTIAL_free when done.

Callers should configure a delegated credential, certificate chain and private key on the credential, along with other properties, then add it with SSL_CTX_add1_credential.

SSL_CREDENTIAL_set1_delegated_credential sets cred's delegated credentials structure to dc. It returns one on success and zero on error, including if dc is malformed. This should be a DelegatedCredential structure, signed by the end-entity certificate, as described in RFC 9345.

ssl_encryption_level_t represents an encryption level in TLS 1.3. Values in this enum match the first 4 epochs used in DTLS 1.3 (section 6.1).

ssl_quic_method_st (aka SSL_QUIC_METHOD) describes custom QUIC hooks.

SSL_quic_max_handshake_flight_len returns returns the maximum number of bytes that may be received at the given encryption level. This function should be used to limit buffering in the QUIC implementation.

See https://www.rfc-editor.org/rfc/rfc9000#section-7.5

SSL_quic_read_level returns the current read encryption level.

TODO(davidben): Is it still necessary to expose this function to callers? QUICHE does not use it.

SSL_quic_write_level returns the current write encryption level.

TODO(davidben): Is it still necessary to expose this function to callers? QUICHE does not use it.

SSL_provide_quic_data provides data from QUIC at a particular encryption level level. It returns one on success and zero on error. Note this function will return zero if the handshake is not expecting data from level at this time. The QUIC implementation should then close the connection with an error.

SSL_process_quic_post_handshake processes any data that QUIC has provided after the handshake has completed. This includes NewSessionTicket messages sent by the server. It returns one on success and zero on error.

SSL_CTX_set_quic_method configures the QUIC hooks. This should only be configured with a minimum version of TLS 1.3. quic_method must remain valid for the lifetime of ctx. It returns one on success and zero on error.

SSL_set_quic_method configures the QUIC hooks. This should only be configured with a minimum version of TLS 1.3. quic_method must remain valid for the lifetime of ssl. It returns one on success and zero on error.

SSL_set_quic_transport_params configures ssl to send params (of length params_len) in the quic_transport_parameters extension in either the ClientHello or EncryptedExtensions handshake message. It is an error to set transport parameters if ssl is not configured for QUIC. The buffer pointed to by params only need be valid for the duration of the call to this function. This function returns 1 on success and 0 on failure.

SSL_get_peer_quic_transport_params provides the caller with the value of the quic_transport_parameters extension sent by the peer. A pointer to the buffer containing the TransportParameters will be put in *out_params, and its length in *params_len. This buffer will be valid for the lifetime of the SSL. If no params were received from the peer, *out_params_len will be 0.

SSL_set_quic_use_legacy_codepoint configures whether to use the legacy QUIC extension codepoint 0xffa5 as opposed to the official value 57. Call with use_legacy set to 1 to use 0xffa5 and call with 0 to use 57. By default, the standard code point is used.

SSL_set_quic_early_data_context configures a context string in QUIC servers for accepting early data. If a resumption connection offers early data, the server will check if the value matches that of the connection which minted the ticket. If not, resumption still succeeds but early data is rejected. This should include all QUIC Transport Parameters except ones specified that the client MUST NOT remember. This should also include any application protocol-specific state. For HTTP/3, this should be the serialized server SETTINGS frame and the QUIC Transport Parameters (except the stateless reset token).

This function may be called before SSL_do_handshake or during server certificate selection. It returns 1 on success and 0 on failure.

SSL_CTX_set_early_data_enabled sets whether early data is allowed to be used with resumptions using ctx.

SSL_set_early_data_enabled sets whether early data is allowed to be used with resumptions using ssl. See SSL_CTX_set_early_data_enabled for more information.

SSL_in_early_data returns one if ssl has a pending handshake that has progressed enough to send or receive early data. Clients may call SSL_write to send early data, but SSL_read will complete the handshake before accepting application data. Servers may call SSL_read to read early data and SSL_write to send half-RTT data.

SSL_SESSION_early_data_capable returns whether early data would have been attempted with session if enabled.

SSL_SESSION_copy_without_early_data returns a copy of session with early data disabled. If session already does not support early data, it returns session with the reference count increased. The caller takes ownership of the result and must release it with SSL_SESSION_free.

This function may be used on the client to clear early data support from existing sessions when the server rejects early data. In particular, SSL_R_WRONG_VERSION_ON_EARLY_DATA requires a fresh connection to retry, and the client would not want 0-RTT enabled for the next connection attempt.

SSL_early_data_accepted returns whether early data was accepted on the handshake performed by ssl.

SSL_reset_early_data_reject resets ssl after an early data reject. All 0-RTT state is discarded, including any pending SSL_write calls. The caller should treat ssl as a logically fresh connection, usually by driving the handshake to completion using SSL_do_handshake.

It is an error to call this function on an SSL object that is not signaling SSL_ERROR_EARLY_DATA_REJECTED.

SSL_get_ticket_age_skew returns the difference, in seconds, between the client-sent ticket age and the server-computed value in TLS 1.3 server connections which resumed a session.

An ssl_early_data_reason_t describes why 0-RTT was accepted or rejected. These values are persisted to logs. Entries should not be renumbered and numeric values should never be reused.

SSL_get_early_data_reason returns details why 0-RTT was accepted or rejected on ssl. This is primarily useful on the server.

SSL_early_data_reason_string returns a string representation for reason, or NULL if reason is unknown. This function may be used for logging.

SSL_set_enable_ech_grease configures whether the client will send a GREASE ECH extension when no supported ECHConfig is available.

SSL_set1_ech_config_list configures ssl to, as a client, offer ECH with the specified configuration. ech_config_list should contain a serialized ECHConfigList structure. It returns one on success and zero on error.

This function returns an error if the input is malformed. If the input is valid but none of the ECHConfigs implement supported parameters, it will return success and proceed without ECH.

If a supported ECHConfig is found, ssl will encrypt the true ClientHello parameters. If the server cannot decrypt it, e.g. due to a key mismatch, ECH has a recovery flow. ssl will handshake using the cleartext parameters, including a public name in the ECHConfig. If using SSL_CTX_set_custom_verify, callers should use SSL_get0_ech_name_override to verify the certificate with the public name. If using the built-in verifier, the X509_STORE_CTX will be configured automatically.

If no other errors are found in this handshake, it will fail with SSL_R_ECH_REJECTED. Since it didn't use the true parameters, the connection cannot be used for application data. Instead, callers should handle this error by calling SSL_get0_ech_retry_configs and retrying the connection with updated ECH parameters. If the retry also fails with SSL_R_ECH_REJECTED, the caller should report a connection failure.

SSL_get0_ech_name_override, if ssl is a client and the server rejected ECH, sets *out_name and *out_name_len to point to a buffer containing the ECH public name. Otherwise, the buffer will be empty.

When offering ECH as a client, this function should be called during the certificate verification callback (see SSL_CTX_set_custom_verify). If *out_name_len is non-zero, the caller should verify the certificate against the result, interpreted as a DNS name, rather than the true server name. In this case, the handshake will never succeed and is only used to authenticate retry configs. See also SSL_get0_ech_retry_configs.

SSL_get0_ech_retry_configs sets *out_retry_configs and *out_retry_configs_len to a buffer containing a serialized ECHConfigList. If the server did not provide an ECHConfigList, *out_retry_configs_len will be zero.

When handling an SSL_R_ECH_REJECTED error code as a client, callers should use this function to recover from potential key mismatches. If the result is non-empty, the caller should retry the connection, passing this buffer to SSL_set1_ech_config_list. If the result is empty, the server has rolled back ECH support, and the caller should retry without ECH.

This function must only be called in response to an SSL_R_ECH_REJECTED error code. Calling this function on ssls that have not authenticated the rejection handshake will assert in debug builds and otherwise return an unparsable list.

SSL_marshal_ech_config constructs a new serialized ECHConfig. On success, it sets *out to a newly-allocated buffer containing the result and *out_len to the size of the buffer. The caller must call OPENSSL_free on *out to release the memory. On failure, it returns zero.

The config_id field is a single byte identifier for the ECHConfig. Reusing config IDs is allowed, but if multiple ECHConfigs with the same config ID are active at a time, server load may increase. See SSL_ECH_KEYS_has_duplicate_config_id.

The public key and KEM algorithm are taken from key. public_name is the DNS name used to authenticate the recovery flow. max_name_len should be the length of the longest name in the ECHConfig's anonymity set and influences client padding decisions.

SSL_ECH_KEYS_new returns a newly-allocated SSL_ECH_KEYS or NULL on error.

SSL_ECH_KEYS_up_ref increments the reference count of keys.

SSL_ECH_KEYS_free releases memory associated with keys.

SSL_ECH_KEYS_add decodes ech_config as an ECHConfig and appends it with key to keys. If is_retry_config is non-zero, this config will be returned to the client on configuration mismatch. It returns one on success and zero on error.

This function should be called successively to register each ECHConfig in decreasing order of preference. This configuration must be completed before setting keys on an SSL_CTX with SSL_CTX_set1_ech_keys. After that point, keys is immutable; no more ECHConfig values may be added.

See also SSL_CTX_set1_ech_keys.

SSL_ECH_KEYS_has_duplicate_config_id returns one if keys has duplicate config IDs or zero otherwise. Duplicate config IDs still work, but may increase server load due to trial decryption.

SSL_ECH_KEYS_marshal_retry_configs serializes the retry configs in keys as an ECHConfigList. On success, it sets *out to a newly-allocated buffer containing the result and *out_len to the size of the buffer. The caller must call OPENSSL_free on *out to release the memory. On failure, it returns zero.

This output may be advertised to clients in DNS.

SSL_CTX_set1_ech_keys configures ctx to use keys to decrypt encrypted ClientHellos. It returns one on success, and zero on failure. If keys does not contain any retry configs, this function will fail. Retry configs are marked as such when they are added to keys with SSL_ECH_KEYS_add.

Once keys has been passed to this function, it is immutable. Unlike most SSL_CTX configuration functions, this function may be called even if ctx already has associated connections on multiple threads. This may be used to rotate keys in a long-lived server process.

The configured ECHConfig values should also be advertised out-of-band via DNS (see draft-ietf-dnsop-svcb-https). Before advertising an ECHConfig in DNS, deployments should ensure all instances of the service are configured with the ECHConfig and corresponding private key.

Only the most recent fully-deployed ECHConfigs should be advertised in DNS. keys may contain a newer set if those ECHConfigs are mid-deployment. It should also contain older sets, until the DNS change has rolled out and the old records have expired from caches.

If there is a mismatch, SSL objects associated with ctx will complete the handshake using the cleartext ClientHello and send updated ECHConfig values to the client. The client will then retry to recover, but with a latency penalty. This recovery flow depends on the public name in the ECHConfig. Before advertising an ECHConfig in DNS, deployments must ensure all instances of the service can present a valid certificate for the public name.

BoringSSL negotiates ECH before certificate selection callbacks are called, including SSL_CTX_set_select_certificate_cb. If ECH is negotiated, the reported SSL_CLIENT_HELLO structure and SSL_get_servername function will transparently reflect the inner ClientHello. Callers should select parameters based on these values to correctly handle ECH as well as the recovery flow.

SSL_ech_accepted returns one if ssl negotiated ECH and zero otherwise.

SSL_AD_REASON_OFFSET is the offset between error reasons and SSL_AD_* values. Any error code under ERR_LIB_SSL with an error reason above this value corresponds to an alert description. Consumers may add or subtract SSL_AD_REASON_OFFSET to convert between them.

make_errors.go reserves error codes above 1000 for manually-assigned errors. This value must be kept in sync with reservedReasonCode in make_errors.h

SSL_AD_* are alert descriptions.

SSL_alert_type_string_long returns a string description of value as an alert type (warning or fatal).

SSL_alert_desc_string_long returns a string description of value as an alert description or "unknown" if unknown.

SSL_send_fatal_alert sends a fatal alert over ssl of the specified type, which should be one of the SSL_AD_* constants. It returns one on success and <= 0 on error. The caller should pass the return value into SSL_get_error to determine how to proceed. Once this function has been called, future calls to SSL_write will fail.

If retrying a failed operation due to SSL_ERROR_WANT_WRITE, subsequent calls must use the same alert parameter.

SSL_get_ivs sets *out_iv_len to the length of the IVs for the ciphers underlying ssl and sets *out_read_iv and *out_write_iv to point to the current IVs for the read and write directions. This is only meaningful for connections with implicit IVs (i.e. CBC mode with TLS 1.0).

It returns one on success or zero on error.

SSL_get_key_block_len returns the length of ssl's key block, for TLS 1.2 and below. It is an error to call this function during a handshake, or if ssl negotiated TLS 1.3.

SSL_generate_key_block generates out_len bytes of key material for ssl's current connection state, for TLS 1.2 and below. It is an error to call this function during a handshake, or if ssl negotiated TLS 1.3.

SSL_get_read_sequence returns, in TLS, the expected sequence number of the next incoming record in the current epoch. In DTLS, it returns the maximum sequence number received in the current epoch and includes the epoch number in the two most significant bytes.

SSL_get_write_sequence returns the sequence number of the next outgoing record in the current epoch. In DTLS, it includes the epoch number in the two most significant bytes.

SSL_CTX_set_record_protocol_version returns whether version is zero.

SSL_serialize_capabilities writes an opaque byte string to out describing some of ssl's capabilities. It returns one on success and zero on error.

This string is used by BoringSSL internally to reduce the impact of version skew.

SSL_request_handshake_hints configures ssl to generate a handshake hint for client_hello. It returns one on success and zero on error. client_hello should contain a serialized ClientHello structure, from the client_hello and client_hello_len fields of the SSL_CLIENT_HELLO structure. capabilities should contain the output of SSL_serialize_capabilities.

When configured, ssl will perform no I/O (so there is no need to configure BIOs). For QUIC, the caller should still configure an SSL_QUIC_METHOD, but the callbacks themselves will never be called and may be left NULL or report failure. SSL_provide_quic_data also should not be called.

If hint generation is successful, SSL_do_handshake will stop the handshake early with SSL_get_error returning SSL_ERROR_HANDSHAKE_HINTS_READY. At this point, the caller should run SSL_serialize_handshake_hints to extract the resulting hints.

Hint generation may fail if, e.g., ssl was unable to process the ClientHello. Callers should then complete the certificate selection RPC and continue the original handshake with no hint. It will likely fail, but this reports the correct alert to the client and is more robust in case of mismatch.

SSL_serialize_handshake_hints writes an opaque byte string to out containing the handshake hints computed by out. It returns one on success and zero on error. This function should only be called if SSL_request_handshake_hints was configured and the handshake terminated with SSL_ERROR_HANDSHAKE_HINTS_READY.

This string may be passed to SSL_set_handshake_hints on another SSL to avoid an extra signature call.

SSL_set_handshake_hints configures ssl to use hints as handshake hints. It returns one on success and zero on error. The handshake will then continue as before, but apply predicted values from hints where applicable.

Hints may contain connection and session secrets, so they must not leak and must come from a source trusted to terminate the connection. However, they will not change ssl's configuration. The caller is responsible for serializing and applying options from the RPC server as needed. This ensures ssl's behavior is self-consistent and consistent with the caller's local decisions.

SSL_CTX_set_msg_callback installs cb as the message callback for ctx. This callback will be called when sending or receiving low-level record headers, complete handshake messages, ChangeCipherSpec, alerts, and DTLS ACKs. write_p is one for outgoing messages and zero for incoming messages.

For each record header, cb is called with version = 0 and content_type = SSL3_RT_HEADER. The len bytes from buf contain the header. Note that this does not include the record body. If the record is sealed, the length in the header is the length of the ciphertext.

For each handshake message, ChangeCipherSpec, alert, and DTLS ACK, version is the protocol version and content_type is the corresponding record type. The len bytes from buf contain the handshake message, one-byte ChangeCipherSpec body, two-byte alert, and ACK respectively.

In connections that enable ECH, cb is additionally called with content_type = SSL3_RT_CLIENT_HELLO_INNER for each ClientHelloInner that is encrypted or decrypted. The len bytes from buf contain the ClientHelloInner, including the reconstructed outer extensions and handshake header.

For a V2ClientHello, version is SSL2_VERSION, content_type is zero, and the len bytes from buf contain the V2ClientHello structure.

SSL_CTX_set_msg_callback_arg sets the arg parameter of the message callback.

SSL_set_msg_callback installs cb as the message callback of ssl. See SSL_CTX_set_msg_callback for when this callback is called.

SSL_set_msg_callback_arg sets the arg parameter of the message callback.

SSL_CTX_set_keylog_callback configures a callback to log key material. This is intended for debugging use with tools like Wireshark. The cb function should log line followed by a newline, synchronizing with any concurrent access to the log.

The format is described in https://www.ietf.org/archive/id/draft-ietf-tls-keylogfile-01.html

WARNING: The data in line allows an attacker to break security properties of the TLS protocol, including confidentiality, integrity, and forward secrecy. This impacts both the current connection, and, in TLS 1.2, future connections that resume a session from it. Both direct access to the data and side channel leaks from application code are possible attack vectors. This callback is intended for debugging and should not be used in production connections.

SSL_CTX_get_keylog_callback returns the callback configured by SSL_CTX_set_keylog_callback.

SSL_CTX_set_current_time_cb configures a callback to retrieve the current time, which should be set in *out_clock. This can be used for testing purposes; for example, a callback can be configured that returns a time set explicitly by the test. The ssl pointer passed to cb is always null.

SSL_set_shed_handshake_config allows some of the configuration of ssl to be freed after its handshake completes. Once configuration has been shed, APIs that query it may fail. "Configuration" in this context means anything that was set by the caller, as distinct from information derived from the handshake. For example, SSL_get_ciphers queries how the SSL was configured by the caller, and fails after configuration has been shed, whereas SSL_get_cipher queries the result of the handshake, and is unaffected by configuration shedding.

If configuration shedding is enabled, it is an error to call SSL_clear.

Note that configuration shedding as a client additionally depends on renegotiation being disabled (see SSL_set_renegotiate_mode). If renegotiation is possible, the configuration will be retained. If configuration shedding is enabled and renegotiation later disabled after the handshake, SSL_set_renegotiate_mode will shed configuration then. This may be useful for clients which support renegotiation with some ALPN protocols, such as HTTP/1.1, and not others, such as HTTP/2.

SSL_set_renegotiate_mode configures how ssl, a client, reacts to renegotiation attempts by a server. If ssl is a server, peer-initiated renegotiations are *always* rejected and this function does nothing.

WARNING: Renegotiation is error-prone, complicates TLS's security properties, and increases its attack surface. When enabled, many common assumptions about BoringSSL's behavior no longer hold, and the calling application must handle more cases. Renegotiation is also incompatible with many application protocols, e.g. section 9.2.1 of RFC 7540. Many functions behave in ambiguous or undefined ways during a renegotiation.

The renegotiation mode defaults to ssl_renegotiate_never, but may be set at any point in a connection's lifetime. Set it to ssl_renegotiate_once to allow one renegotiation, ssl_renegotiate_freely to allow all renegotiations or ssl_renegotiate_ignore to ignore HelloRequest messages. Note that ignoring HelloRequest messages may cause the connection to stall if the server waits for the renegotiation to complete.

If set to ssl_renegotiate_explicit, SSL_read and SSL_peek calls which encounter a HelloRequest will pause with SSL_ERROR_WANT_RENEGOTIATE. SSL_write will continue to work while paused. The caller may call SSL_renegotiate to begin the renegotiation at a later point. This mode may be used if callers wish to eagerly call SSL_peek without triggering a renegotiation.

If configuration shedding is enabled (see SSL_set_shed_handshake_config), configuration is released if, at any point after the handshake, renegotiation is disabled. It is not possible to switch from disabling renegotiation to enabling it on a given connection. Callers that condition renegotiation on, e.g., ALPN must enable renegotiation before the handshake and conditionally disable it afterwards.

When enabled, renegotiation can cause properties of ssl, such as the cipher suite, to change during the lifetime of the connection. More over, during a renegotiation, not all properties of the new handshake are available or fully established. In BoringSSL, most functions, such as SSL_get_current_cipher, report information from the most recently completed handshake, not the pending one. However, renegotiation may rerun handshake callbacks, such as SSL_CTX_set_cert_cb. Such callbacks must ensure they are acting on the desired versions of each property.

BoringSSL does not reverify peer certificates on renegotiation and instead requires they match between handshakes, so certificate verification callbacks (see SSL_CTX_set_custom_verify) may assume ssl is in the initial handshake and use SSL_get0_peer_certificates, etc.

There is no support in BoringSSL for initiating renegotiations as a client or server.

SSL_renegotiate starts a deferred renegotiation on ssl if it was configured with ssl_renegotiate_explicit and has a pending HelloRequest. It returns one on success and zero on error.

This function does not do perform any I/O. On success, a subsequent SSL_do_handshake call will run the handshake. SSL_write and SSL_read will also complete the handshake before sending or receiving application data.

SSL_renegotiate_pending returns one if ssl is in the middle of a renegotiation.

SSL_total_renegotiations returns the total number of renegotiation handshakes performed by ssl. This includes the pending renegotiation, if any.

SSL_MAX_CERT_LIST_DEFAULT is the default maximum length, in bytes, of a peer certificate chain.

SSL_CTX_get_max_cert_list returns the maximum length, in bytes, of a peer certificate chain accepted by ctx.

SSL_CTX_set_max_cert_list sets the maximum length, in bytes, of a peer certificate chain to max_cert_list. This affects how much memory may be consumed during the handshake.