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_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.

In DTLS, rbio must be non-blocking to properly handle timeouts and retransmits.

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.

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.

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. Whenever SSL_get_error signals SSL_ERROR_WANT_READ, use DTLSv1_get_timeout to determine the current timeout. If it expires before the next retry, call DTLSv1_handle_timeout. Note that DTLS handshake retransmissions use fresh sequence numbers, so it is not sufficient to replay packets at the transport.

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.

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

SSL_read_ex reads up to num bytes from ssl into buf. It is similar to SSL_read, but instead of returning the number of bytes read, it returns 1 on success or 0 for failure. The number of bytes actually read is stored in read_bytes.

This is only maintained for OpenSSL compatibility. Use SSL_read instead.

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

SSL_peek_ex reads up to num bytes from ssl into buf. It is similar to SSL_peek, but instead of returning the number of bytes read, it returns 1 on success or 0 for failure. The number of bytes actually read is stored in read_bytes.

This is only maintained for OpenSSL compatibility. Use SSL_peek instead.

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.

If read-ahead has been enabled with SSL_CTX_set_read_ahead or SSL_set_read_ahead, the behavior of SSL_pending will change, it may return 1 and a call to SSL_read to return no data. This can happen when a partial record has been read but can not be decrypted without more data from the read BIO.

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_write_ex writes up to num bytes from buf into ssl. It is similar to SSL_write, but instead of returning the number of bytes written, it returns 1 on success or 0 for failure. The number bytes actually written is stored in written.

This is only maintained for OpenSSL compatibility. Use SSL_write instead.

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 its own KeyUpdate message.

SSL_KEY_UPDATE_NONE should not be set by the user and is only used to indicate that there isn't a pending key operation. OpenSSL indicates that -1 is used, so that it will be an invalid value for the on-the-wire protocol when calling SSL_key_update.

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 be either SSL_KEY_UPDATE_REQUESTED or SSL_KEY_UPDATE_NOT_REQUESTED. This function requires that ssl have completed a TLS >= 1.3 handshake. It returns one on success or zero on error.

If request_type is set to SSL_KEY_UPDATE_NOT_REQUESTED, then the sending keys for this connection will be updated and the peer will be informed of the change. If request_type is set to SSL_KEY_UPDATE_REQUESTED, then the sending keys for this connection will be updated and the peer will be informed of the change along with a request for the peer to additionally update its sending keys. RFC: https://datatracker.ietf.org/doc/html/rfc8446#section-4.6.3

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_get_key_update_type returns the state of the pending key operation in ssl. The type of pending key operation will be either SSL_KEY_UPDATE_REQUESTED or SSL_KEY_UPDATE_NOT_REQUESTED if there is one, and SSL_KEY_UPDATE_NONE otherwise. This can be used to indicate whether a key update operation has been scheduled but not yet performed.

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 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.

If signaled by a DTLS handshake, the caller must also call DTLSv1_get_timeout and DTLSv1_handle_timeout as appropriate. See SSL_do_handshake.

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 and SSL_CTX_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 1 second, which is the strong recommendation of RFC 6347 (see section 4.2.4.1). However, there may exist situations where a shorter timeout would be beneficial, such as for time-sensitive applications.

DTLSv1_get_timeout queries the next DTLS handshake timeout. If there is a timeout in progress, it sets *out to the time remaining and returns one. Otherwise, it returns zero.

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

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

DTLSv1_handle_timeout is called when a DTLS handshake timeout expires. If no timeout had expired, it returns 0. Otherwise, it retransmits the previous flight of handshake messages and returns 1. If too many timeouts had expired without progress or an error occurs, it returns -1.

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. However, the operation may not be retried until the next timeout fires.

WARNING: This function breaks the usual return value convention.

TODO(davidben): This SSL_ERROR_WANT_WRITE behavior is kind of bizarre.

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. If ctx is configured to use the default minimum version, 0 is returned.

SSL_CTX_get_max_proto_version returns the maximum protocol version for ctx. If ctx is configured to use the default maximum version, 0 is returned.

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 or ssl is configured to use the default min version, 0 is returned.

SSL_get_max_proto_version returns the maximum protocol version for ssl. If the connection's configuration has been shed or ssl is configured to use the default max version, 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. By default, OpenSSL automatically builds a certificate chain on the fly if there is no certificate chain explicitly provided. This feature is called Auto-Chaining. Auto-Chaining can be turned off in OpenSSL by setting the SSL_MODE_NO_AUTO_CHAIN flag for the SSL connection. AWS-LC has this flag turned on (auto-chaining off) by default. This forces the certificate chain to be explicit, and no longer results in unexpected certificate chains being sent back to clients. This may cause issues for services migrating to AWS-LC, if the service had been reliant on the default behavior. Services should restructure their certificate chains to not use the default auto-chaining behavior from OpenSSL when porting to AWS-LC. We highly recommend not to re-enable Auto-Chaining, but if a consumer had been relying on this default behavior, they can temporarily revert back with SSL_[CTX_]clear_mode. However, it is generally expected of AWS-LC consumers to structure their certificate chains to not rely on auto-chaining.

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_CTX_use_certificate sets ctx's leaf certificate to x509. It returns one on success and zero on failure.

SSL_use_certificate sets ssl's leaf certificate to x509. It returns one on success and zero on failure.

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

SSL_use_PrivateKey sets ssl's private key to pkey. It returns one on success and zero on failure.

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_BUILD_CHAIN_FLAG_UNTRUSTED treats any existing certificates as untrusted CAs. This is mutually exclusive to SSL_BUILD_CHAIN_FLAG_CHECK and SSL_BUILD_CHAIN_FLAG_CHECK will be prioritized to use the existing chain certificates instead.

SSL_BUILD_CHAIN_FLAG_NO_ROOT omits the root CA from the built chain.

SSL_BUILD_CHAIN_FLAG_CHECK uses only existing chain certificates to build the chain (effectively sanity checking and rearranging them if necessary). This is mutually exclusive to SSL_BUILD_CHAIN_FLAG_UNTRUSTED and SSL_BUILD_CHAIN_FLAG_CHECK will be prioritized.

SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR ignores errors during certificate verification, but still pushes the error onto the error queue.

SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR is only used when SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR is defined. It clears the error from the error queue if certificate verification has failed.

SSL_CTX_build_cert_chain builds the certificate chain for ctx. Normally this uses the chain store or the verify store if the chain store is not set. If the function is successful, the built chain will replace any existing chain in ctx. This function returns 1 on success and -1 on failure, unless SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR is set. If SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR is set, then this function returns 1 on success, 2 if certificate verification has failed, and -1 on all other types of failures.

SSL_build_cert_chain is similar to SSL_CTX_build_cert_chain, but the certificate chain is built for ssl instead.

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_CLIENT_HELLO_SUCCESS indicates that the ClientHello processing was successful. The handshake will continue normally.

SSL_CLIENT_HELLO_ERROR indicates that a fatal error occurred while processing the ClientHello. The callback should set *al to a TLS alert value to return to the client. The handshake will be aborted.

SSL_CLIENT_HELLO_RETRY indicates that the handshake should be paused and the server should retry when it can continue.

WARNING: The current implementation does not properly support SSL_CLIENT_HELLO_RETRY and attempting to use it will result in handshake failure.

SSL_client_hello_cb_fn is a callback function that is called when a ClientHello is received. The callback may inspect the ClientHello and make decisions about the connection based on its contents.

The callback should return one of:

• SSL_CLIENT_HELLO_SUCCESS to continue the handshake
• SSL_CLIENT_HELLO_ERROR to abort the handshake with alert *al
• SSL_CLIENT_HELLO_RETRY (not supported) is handled like SSL_CLIENT_HELLO_ERROR

SSL_client_hello_get1_extensions_present iterates over the extensions in the ClientHello. If any are found, it allocates an array of int and sets *out to point to this array and *outlen to the number of extensions. The ints in the array correspond to the type of each extension. The caller is responsible for releasing the array with OPENSSL_free. If no extensions are found, it sets *out to NULL and *outlen to 0. The function returns 1 on success and returns 0 on error.

This function can only be called from within a client hello callback (see SSL_CTX_set_client_hello_cb) or during server certificate selection (see SSL_CTX_set_select_certificate_cb).

SSL_client_hello_get_extension_order iterates over the extensions in the ClientHello. If exts is not null, the type for each extension will be stored in exts and *num_exts should be the size of storage allocated for exts; the function will return an error if *num_exts is too small. On success, the function will return 1 and will set *num_exts to the number of extensions. The caller may pass exts as null to obtain the number of extensions. If no ClientHello extensions are found, the function returns 1 and sets *num_exts to 0. The functions returns 0 on error.

This function can only be called from within a client hello callback (see SSL_CTX_set_client_hello_cb) or during server certificate selection (see SSL_CTX_set_select_certificate_cb).

SSL_CTX_set_client_hello_cb configures a callback that is called when a ClientHello message is received. This can be used to select certificates, adjust settings, or otherwise make decisions about the connection before the handshake proceeds.

The callback is invoked before most ClientHello processing and before the decision whether to resume a session is made. It may inspect the ClientHello and configure the connection accordingly.

The callback function is passed the SSL object, a pointer to an alert value, and the argument provided when the callback was set. It should return either SSL_CLIENT_HELLO_SUCCESS, SSL_CLIENT_HELLO_ERROR, or SSL_CLIENT_HELLO_RETRY. Note that SSL_CLIENT_HELLO_RETRY is not fully supported; it is treated the same as SSL_CLIENT_HELLO_ERROR.

SSL_client_hello_isv2 always returns zero as SSLv2 is not supported.

SSL_client_hello_get0_legacy_version provides the value of the "legacy_version" field in the client hello.

This function can only be called from within a client hello callback (see SSL_CTX_set_client_hello_cb) or during server certificate selection (see SSL_CTX_set_select_certificate_cb).

SSL_client_hello_get0_ext searches the extensions in the ClientHello for an extension of the given type. If found, it sets *out to point to the extension contents (not including the type and length bytes) and *outlen to the length of the extension contents. If not found, it returns zero.

This function can only be called from within a client hello callback (see SSL_CTX_set_client_hello_cb) or during server certificate selection (see SSL_CTX_set_select_certificate_cb).

SSL_certs_clear resets the private key, leaf certificate, and certificate chain of ssl.

SSL_CTX_check_private_key returns one if the certificate and private key configured in ctx are consistent and zero otherwise.

SSL_check_private_key returns one if the certificate and private key configured in ssl are consistent and zero otherwise.

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_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_use_cert_and_key sets x509, privatekey, and chain on ctx. The privatekey argument must be the private key of the certificate x509. If the override argument is 0, then x509, privatekey, and chain are set only if all were not previously set. If override is non-0, then the certificate, private key and chain certs are always set. privatekey and x509 are not copied or duplicated, their reference counts are incremented. In OpenSSL, a shallow copy of chain is stored with a reference count increment for all X509 objects in the chain. In AWS-LC, we represent X509 chains as a CRYPTO_BUFFER stack. Therefore, we create a an internal copy and leave the chain parameter untouched. This means, changes to chain after this function is called will not update in ctx. This is different from OpenSSL which stores a reference to the X509 certificates in the chain object.

Returns one on success and zero on error.

SSL_use_cert_and_key sets x509, privatekey, and chain on ssl. The privatekey argument must be the private key of the certificate x509. If the override argument is 0, then x509, privatekey, and chain are set only if all were not previously set. If override is non-0, then the certificate, private key and chain certs are always set. privatekey and x509 are not copied or duplicated, their reference counts are incremented. In OpenSSL, a shallow copy of chain is stored with a reference count increment for all X509 objects in the chain. In AWS-LC, we represent X509 chains as a CRYPTO_BUFFER stack. Therefore, we create a an internal copy and leave the chain parameter untouched. This means, changes to chain after this function is called will not update in ssl. This is different from OpenSSL which stores a reference to the X509 certificates in the chain object.

Returns one on success and zero on error.

Certificate and private key convenience functions.

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_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.)

There is no SSL* version of this function because connections discard configuration after handshaking, thus making it of questionable utility.

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_use_certificate_chain_file configures certificates for ssl. 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.

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.

Callers that use this structure should additionally call SSL_set_signing_algorithm_prefs or SSL_CTX_set_signing_algorithm_prefs with the private key's capabilities. This ensures BoringSSL will select a suitable signature algorithm for the private key.

SSL_set_private_key_method configures a custom private key on ssl. key_method must remain valid for the lifetime of ssl. Using custom keys with the multiple certificate slots feature is not supported.

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

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_find returns a SSL_CIPHER structure which has the cipher ID stored in ptr or NULL if unknown. The ptr parameter is a two element array of char, which stores the two-byte TLS cipher ID (as allocated by IANA) in network byte order. SSL_CIPHER_find re-casts ptr to uint16_t and calls SSL_get_cipher_by_value to get the SSL_CIPHER structure.

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 updates ctx->cipher_list with any values in ctx->tls13_cipher_list.

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 updates ctx->cipher_list with any values in ctx->tls13_cipher_list. 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. However, an empty string which also results in an empty cipher list, is allowed. This behavior is strongly advised against and only meant for OpenSSL compatibility.

Note: this API only sets the TLSv1.2 and below ciphers. Use SSL_CTX_set_ciphersuites to configure TLS 1.3 specific ciphers.

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 updates the cipher list ssl->config->cipher_list with any configured TLS 1.3 cipher suites by first checking ssl->config->tls13_cipher_list and otherwise falling back to ssl->ctx->tls13_cipher_list.

It returns one on success and zero on failure.

SSL_CTX_set_ciphersuites configures the available TLSv1.3 ciphersuites on ctx, evaluating str as a cipher string. It updates ctx->cipher_list with any values in ctx->tls13_cipher_list. It returns one on success and zero on failure.

SSL_set_ciphersuites configures the available TLSv1.3 ciphersuites on ssl, evaluating str as a cipher string. It updates ssl->config->cipher_list with any values in ssl->config->tls13_cipher_list. 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 updates the cipher list ssl->config->cipher_list with any configured TLS 1.3 cipher suites by first checking ssl->config->tls13_cipher_list and otherwise falling back to ssl->ctx->tls13_cipher_list.

Equal-preference groups cannot be configured for TLS 1.3 through these APIs.

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. However, an empty string which also results in an empty cipher list, is allowed. This behavior is strongly advised against and only meant for OpenSSL compatibility.

SSL_CTX_get_ciphers returns the cipher list for ctx, in order of preference. This includes TLS 1.3 and 1.2 and below cipher suites.

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. This includes TLS 1.3 and 1.2 and below cipher suites.

SSL_in_connect_init returns 1 if ssl is a client and has a pending handshake. Otherwise, it returns 0.

SSL_in_accept_init returns 1 if ssl is a server and has a pending handshake. Otherwise, it returns 0.

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 contrast, SSL_get_peer_cert_chain returns only the intermediate certificates if the ssl is a server.

SSL_get0_verified_chain returns the verified certificate chain of the peer including the peer's end entity certificate. It must be called after a session has been successfully established. If peer verification was not successful (as indicated by SSL_get_verify_result not returning X509_V_OK) the result will be null. If a verification callback was set with SSL_CTX_set_cert_verify_callback or SSL_set_custom_verify this function's behavior is undefined.

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_get_client_ciphers returns the stack of ciphers offered by the client during a handshake and that are supported by this library. If ssl is a client or the handshake hasn't occurred yet, NULL is returned. The stack of ciphers IS NOT de/serialized, so NULL will also be returned for deserialized or transported ssl's that haven't yet performed a new handshake.

SSL_client_hello_get0_ciphers provides access to the client ciphers field from the Client Hello, optionally writing the result to an out pointer. It returns the field length if successful, or 0 if ssl is a client or the handshake hasn't occurred yet. out points to the raw bytes from the client hello message so it may contain invalid or unsupported Cipher IDs.

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_custom_ext_add_cb is a callback function that is called when the ClientHello (for clients) or ServerHello (for servers) is constructed. In the case of a server, this callback will only be called for a given extension if the ClientHello contained that extension – it's not possible to inject extensions into a ServerHello that the client didn't request.

When called, extension_value will contain the extension number that is being considered for addition (so that a single callback can handle multiple extensions). If the callback wishes to include the extension, it must set *out to point to *out_len bytes of extension contents and return one. In this case, the corresponding SSL_custom_ext_free_cb callback will later be called with the value of *out once that data has been copied.

If the callback does not wish to add an extension it must return zero.

Alternatively, the callback can abort the connection by setting *out_alert_value to a TLS alert number and returning -1.

SSL_custom_ext_free_cb is a callback function that is called by AWS-LC iff an SSL_custom_ext_add_cb callback previously returned one. In that case, this callback is called and passed the out pointer that was returned by the add callback. This is to free any dynamically allocated data created by the add callback.

SSL_custom_ext_parse_cb is a callback function that is called by AWS-LC to parse an extension from the peer: that is from the ServerHello for a client and from the ClientHello for a server.

When called, extension_value will contain the extension number and the contents of the extension are contents_len bytes at contents.

The callback must return one to continue the handshake. Otherwise, if it returns zero, a fatal alert with value *out_alert_value is sent and the handshake is aborted.

SSL_extension_supported returns one iff AWS-LC internally handles extensions of type extension_value. This can be used to avoid registering custom extension handlers for extensions that a future version of AWS-LC may handle internally.

SSL_CTX_add_client_custom_ext registers callback functions for handling custom TLS extensions for client connections.

If add_cb is NULL then an empty extension will be added in each ClientHello. Otherwise, see the comment for SSL_custom_ext_add_cb about this callback.

The free_cb may be NULL if add_cb doesn't dynamically allocate data that needs to be freed.

It returns one on success or zero on error. It's always an error to register callbacks for the same extension twice, or to register callbacks for an extension that AWS-LC handles internally. See SSL_extension_supported to discover, at runtime, which extensions AWS-LC handles internally.

SSL_CTX_add_server_custom_ext is the same as SSL_CTX_add_client_custom_ext, but for server connections.

Unlike on the client side, if add_cb is NULL no extension will be added. The add_cb, if any, will only be called if the ClientHello contained a matching extension.

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. The caller is responsible for protecting the integrity of the serialized session data; no minimum-length validation is performed on individual fields.

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 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 decrypting the ticket failed, 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_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.

Note that this API does not use the SSL_GROUP_* values defined below.

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.

Note that this API does not use the SSL_GROUP_* values defined below.

SSL_CTX_set1_groups_list sets the preferred groups for ctx to be the colon-separated list groups. Each element of groups should be a curve name (e.g. P-256, X25519, ...). It returns one on success and zero on failure.

SSL_set1_groups_list sets the preferred groups for ssl to be the colon-separated list groups. Each element of groups should be a curve name (e.g. P-256, X25519, ...). 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_GROUP_* define TLS group IDs.

The following are defined at https://datatracker.ietf.org/doc/html/draft-kwiatkowski-tls-ecdhe-mlkem.html

The following are defined at https://datatracker.ietf.org/doc/html/draft-connolly-tls-mlkem-key-agreement.html

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_peer_tmp_key sets *out_key to the temporary key provided by the peer that was during the key exchange. If ssl is the server, the client's temporary key is returned; if ssl is the client, the server's temporary key is returned. It returns 1 on success and 0 if otherwise.

SSL_get_server_tmp_key is a backwards compatible alias to SSL_get_peer_tmp_key in OpenSSL. Note that this means the client's temporary key is being set to *out_key instead, if ssl is the server.

*** EXPERIMENTAL — DO NOT USE WITHOUT CHECKING ***

SSL_to_bytes and SSL_from_bytes are developed to support SSL transfer across processes after handshake finished.

SSL transfer allows the TLS connection to be used in a different process (or on a different machine). This only applies to servers.

1. Before termination, the process 1 encodes the SSL by calling SSL_to_bytes.
2. Another process resumes the SSL by calling SSL_from_bytes.

WARNING: The serialisation formats are not yet stable: version skew may be fatal. WARNING: The encoded data contains sensitive key material and must be protected.

SSL_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.

CAUTION: This function will serialize an established TLS 1.2/1.3 connection, which includes sensitive security parameters established during the connection handshake, and memory buffers that may contain sensitive in-flight application data. It is the callers responsibility for ensuring the confidentiality and data integrity of the serialized encoding. Minimally a caller must encrypt the returned bytes using an AEAD cipher, such as AES-128-GCM before persisting the bytes to storage.

WARNING: Currently only works with TLS 1.2 or TLS 1.3 after handshake has finished. WARNING: Currently only supports SSL as server. WARNING: CRYPTO_EX_DATA ssl->ex_data is not encoded. Remember set ex_data back after decode. WARNING: BIO ssl->rbio and ssl->wbio are not encoded. WARNING: STACK_OF(SSL_CIPHER) ssl->client_cipher_suites is not encoded.

Initial implementation of this API is made by Evgeny Potemkin.

SSL_from_bytes parses in_len bytes from in as an SSL. It returns a newly-allocated SSL on success or NULL on error. The SSL is marked with handshake finished. in and in_len should come from out_data and out_len of SSL_to_bytes. In other words, SSL_from_bytes should be called after SSL_to_bytes.

CAUTION: This function deserializes an encoded TLS 1.2/1.3 established connection so that the communication may continue on the previously established channel. It is the callers responsibility for maintaining confidentiality and integrity of serialized bytes between the time of serialization and invoking this function. See SSL_to_bytes for more details.

WARNING: Do not decode the same bytes in for different connections. Otherwise, the connections use the same key material. WARNING: Remember set ssl->rbio and ssl->wbio before using ssl. WARNING: Remember set callback functions and ex_data back if needed. WARNING: STACK_OF(SSL_CIPHER) ssl->client_cipher_suites is not encoded and will be repopulated on next handshake. WARNING: To ensure behavior unchange, ctx setting should be the same.

Initial implementation of this API is made by Evgeny Potemkin.

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.

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.

X509_V_FLAG_X509_STRICT is always ON by default and X509_V_FLAG_ALLOW_PROXY_CERTS is always OFF. Both are non-configurable. See x509.h for more details.

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_set1_cert_store is like SSL_CTX_set_cert_store, but does not take additional ownership of store.

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_set_verify_result sets the result of certificate verification.

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.

Client certificate CA list.

When requesting a client certificate, a server may advertise a list of certificate authorities which are accepted. These functions may be used to configure this list.

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

SSL_CTX_set_client_CA_list sets ctx's client certificate CA list to name_list. It takes ownership of and frees 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_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. This may be called during the callbacks set by SSL_CTX_set_cert_cb and SSL_CTX_set_client_cert_cb, when the handshake is paused because of them, or after the handshake has completed.

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. The returned list must be in wire format. The list is returned by setting *out to point to it and *out_len to its length. This memory will not be modified, but one should assume that ssl keeps a reference to it.

The callback should return SSL_TLSEXT_ERR_OK if it wishes to advertise. Otherwise, no such extension will be included in the ServerHello.

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. *out must be set to point to the selected protocol (which may be within in). The length of the protocol name must be written into *out_len. The server's advertised protocols are provided in in and in_len. 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.

The client must select a protocol. It is fatal to the connection if this callback returns a value other than SSL_TLSEXT_ERR_OK.

Configuring this callback enables NPN on a client.

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_data is set to NULL.

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_psk_client_cb_func defines a function signature for the client callback.

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_psk_server_cb_func defines a function signature for the server 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_set1_delegated_credential configures the delegated credential (DC) that will be sent to the peer for the current connection. dc is the DC in wire format, and pkey or key_method is the corresponding private key. Currently, only servers may configure a DC to use in the handshake.

The DC will only be used if the protocol version is correct and the signature scheme is supported by the peer. If not, the DC will not be negotiated and the handshake will use the private key (or private key method) associated with the certificate.

SSL_delegated_credential_used returns one if a delegated credential was used and zero otherwise.

ssl_encryption_level_t represents a specific QUIC encryption level used to transmit handshake messages.

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.