Associates a public certificate chain with a s2n_cert_chain_and_key object. It does
NOT set a private key, so the connection will need to be configured to
offload private key operations.
Creates a new s2n_cert_chain_and_key object. This object can be associated
with many config objects. It is used to represent a certificate and key pair.
@param chain_and_key A pointer to the s2n_cert_chain_and_key object being read.
@param cert_length This return value represents the length of the s2n certificate chain chain_and_key.
@returns the length of the s2n certificate chain chain_and_key.
Function to determine the size of the Client Hello cipher suites.
This can be used to allocate the out buffer for s2n_client_hello_get_cipher_suites().
Copies max_length bytes of the ClientHello message into the out buffer.
The ClientHello instrumented using this function will have the Random bytes
zero-ed out. Use s2n_client_hello_get_random to access the random bytes.
Allows the server to opt-in to accept client’s TLS maximum fragment length extension
requests. If this API is not called, and client requests the extension, server will ignore
the request and continue TLS handshake with default maximum fragment length of 8k bytes
Associates a certificate chain and private key with an s2n_config object.
Using this API, only one cert chain of each type (like ECDSA or RSA) may be associated with a config.
cert_chain_pem should be a PEM encoded certificate chain, with the first certificate
in the chain being your server’s certificate. private_key_pem should be a
PEM encoded private key corresponding to the server certificate.
The preferred method of associating a certificate chain and private key pair with an s2n_config object.
This method may be called multiple times to support multiple key types (RSA, RSA-PSS, ECDSA) and multiple
domains. On the server side, the certificate selected will be based on the incoming SNI value and the
client’s capabilities (supported ciphers).
Adds session ticket key on the server side. It would be ideal to add new keys after every
(encrypt_decrypt_key_lifetime_in_nanos/2) nanos because this will allow for gradual and
linear transition of a key from encrypt-decrypt state to decrypt-only state.
s2n_config_enable_cert_req_dss_legacy_compat adds a dss cert type in the server certificate request when being called.
It only sends the dss cert type in the cert request but does not succeed the handshake if a dss cert is received.
Please DO NOT call this api unless you know you actually need legacy DSS certificate type compatibility
@param config Config to enable legacy DSS certificates for
Allows the caller to set a TLS Maximum Fragment Length extension that will be used
to fragment outgoing messages. s2n-tls currently does not reject fragments larger
than the configured maximum when in server mode. The TLS negotiated maximum fragment
length overrides the preference set by the s2n_connection_prefer_throughput and
s2n_connection_prefer_low_latency.
Explicitly sets certificate chain and private key pairs to be used as defaults for each auth
method (key type). A “default” certificate is used when there is not an SNI match with any other
configured certificate.
Sets the s2n_cert_tiebreak_callback for resolving domain name conflicts.
If no callback is set, the first certificate added for a domain name will always be preferred.
Sets the extension data in the s2n_config object for the specified extension.
This method will clear any existing data that is set. If the data and length
parameters are set to NULL, no new data is set in the s2n_config object,
effectively clearing existing data.
Sets the maximum allowed depth of a cert chain used for X509 validation. The default value is
7. If this limit is exceeded, validation will fail if s2n_config_disable_x509_verification()
has not been called. 0 is an illegal value and will return an error.
1 means only a root certificate will be used.
Allows the caller to set a callback function that will be used to get
monotonic time. The monotonic time is the time since an arbitrary, unspecified
point. Unlike wall clock time, it MUST never move backwards.
Sets the application protocol preferences on an s2n_config object.
protocols is a list in order of preference, with most preferred protocol first, and of
length protocol_count.
Sets the callback to select the matching PSK.
If this callback is not set s2n-tls uses a default PSK selection logic that selects the first matching
server PSK.
Sets up a connection to request the certificate status of a peer during an SSL handshake. If set
to S2N_STATUS_REQUEST_NONE, no status request is made.
Sets how long a session ticket key will be in a state where it can used just for decryption of
already assigned tickets on the server side. Once decrypted, the session will resume and the
server will issue a new session ticket encrypted using a key in encrypt-decrypt state.
Allows the caller to set a callback function that will be used to get the
system time. The time returned should be the number of nanoseconds since the
Unix epoch (Midnight, January 1st, 1970).
Appends a PSK object to the list of PSKs supported by the s2n connection.
If a PSK with a duplicate identity is found, an error is returned and the PSK is not added to the list.
Note that a copy of psk is stored on the connection. The user is still responsible for freeing the
memory associated with psk.
Frees the memory associated with an s2n_connection
handle. The handle is considered invalid after s2n_connection_free is used.
s2n_connection_wipe() does not need to be called prior to this function. s2n_connection_free performs its own wipe
of sensitive data.
Function to get the alert that caused a connection to close. s2n-tls considers all
TLS alerts fatal and shuts down a connection whenever one is received.
A function that provides insight into whether or not the server was able to send a certificate that
partially or completely matched the client’s SNI extension.
Query the connection object for the configured blinding delay.
@param conn The connection object being updated
@returns the number of nanoseconds an application using self-service blinding should pause before calling close() or shutdown().
Function to get the human readable key exchange group name for the connection, for example:
secp521r1 or SecP256r1MLKEM768. If an EC curve or KEM was not negotiated, S2N_FAILURE will be
returned.
Function to return the last TLS message that was processed. The returned format is a human readable string.
@param conn A pointer to the s2n connection
@returns The last message name in the TLS state machine, e.g. “SERVER_HELLO”, “APPLICATION_DATA”.
Gets the negotiated PSK identity from the s2n connection object.
If the negotiated PSK does not exist, the PSK identity will not be obtained and no error will be returned.
Prior to this API call, use s2n_connection_get_negotiated_psk_identity_length to determine if a
negotiated PSK exists or not.
Gets the negotiated PSK identity length from the s2n connection object. The negotiated PSK
refers to the chosen PSK by the server to be used for the connection.
Function to check if the cipher used by current connection is supported by the current
cipher preferences.
@param conn A pointer to the s2n connection
@param version A string representing the security policy to check against.
@returns 1 if the connection satisfies the cipher suite. 0 if the connection does not satisfy the cipher suite. -1 if there is an error.
Creates a new connection object. Each s2n-tls SSL/TLS connection uses
one of these objects. These connection objects can be operated on by up
to two threads at a time, one sender and one receiver, but neither sending
nor receiving are atomic, so if these objects are being called by multiple
sender or receiver threads, you must perform your own locking to ensure
that only one sender or receiver is active at a time.
Signals the connection to do a key_update at the next possible opportunity. Note that the resulting key update message
will not be sent until s2n_send is called.
Retrieves the length of the serialized connection from s2n_connection_serialize(). Should be
used to allocate enough memory for the serialized connection buffer.
Must be invoked if any of the connection properties were changed on the basis of the server_name
extension. This must be invoked before marking the Client Hello callback done.
Used to configure s2n-tls to either use built-in blinding (set blinding to S2N_BUILT_IN_BLINDING) or
self-service blinding (set blinding to S2N_SELF_SERVICE_BLINDING).
Sets the cipher preference override for the s2n_connection. Calling this function is not necessary
unless you want to set the cipher preferences on the connection to something different than what is in the s2n_config.
Sets the protocol preference override for the s2n_connection. Calling this function is not necessary unless you want
to set the protocol preferences on the connection to something different than what is in the s2n_config.
Sets the PSK mode on the s2n connection object.
The supported PSK modes are listed in the enum s2n_psk_mode above.
This API overrides the PSK mode set on config for this connection.
Set a context containing anything needed in the recv callback function (for example,
a file descriptor), the buffer holding data to be sent or received, and the length of the buffer.
Set a context containing anything needed in the send callback function (for example,
a file descriptor), the buffer holding data to be sent or received, and the length of the buffer.
Prevents S2N from calling OPENSSL_init_crypto/OPENSSL_cleanup/EVP_cleanup on OpenSSL versions
prior to 1.1.x. This allows applications or languages that also init OpenSSL to interoperate
with S2N.
Creates a new s2n external pre-shared key (PSK) object with S2N_PSK_HMAC_SHA256 as the default
PSK hash algorithm. An external PSK is a key established outside of TLS using a secure mutually agreed upon mechanism.
Fetches the OpenSSL version s2n-tls was compiled with. This can be used by applications to validate at runtime
that the versions of s2n-tls and Openssl that they have loaded are correct.
Initializes the s2n-tls library and should be called once in your application, before any other s2n-tls
functions are called. Failure to call s2n_init() will result in errors from other s2n-tls functions.
Chooses a PSK from the offered PSK list to be used for the connection.
This API matches the PSK identity received from the client against the server’s known PSK identities
list, in order to choose the PSK to be used for the connection. If the PSK identity sent from the client
is NULL, no PSK is chosen for the connection. If the client offered PSK identity has no matching PSK identity
with the server, an error will be returned. Use this API along with the s2n_psk_selection_callback callback
to select a PSK identity.
Checks whether the offered PSK list has an offered psk object next in line in the list.
An offered PSK list contains all the PSKs offered by the client for the server to select.
Obtains the next offered PSK object from the list of offered PSKs. Use s2n_offered_psk_list_has_next
prior to this API call to ensure we have not reached the end of the list.
Sets the identity for a given external PSK object.
The identity is a unique identifier for the pre-shared secret.
It is a non-secret value represented by raw bytes.
Writes and encrypts size of buf data to the associated connection. s2n_send() will return the number of bytes
written, and may indicate a partial write.
Works in the same way as s2n_sendv_with_offset() but with the offs parameter implicitly assumed to be 0.
Therefore in the partial write case, the caller would have to make sure that the bufs and count fields are modified in a way that takes
the partial writes into account.
Works in the same way as s2n_send() except that it accepts vectorized buffers. Will return the number of bytes written, and may indicate a partial write. Partial writes are possible not just for non-blocking I/O, but also for connections aborted while active.
Translates an s2n_error code to a human readable string containing internal debug
information, including file name and line number. This function is useful when
reporting issues to the s2n-tls development team.
A callback function that is invoked if s2n-tls cannot resolve a conflict between
two certificates with the same domain name. This function is invoked while certificates
are added to an s2n_config.
The callback function takes a s2n-tls connection as input, which receives the ClientHello
and the context previously provided in s2n_config_set_client_hello_cb. The callback can
access any ClientHello information from the connection and use the s2n_connection_set_config
call to change the config of the connection.
Callback function to select a PSK from a list of offered PSKs.
Use this callback to implement custom PSK selection logic. The s2n-tls default PSK selection logic
chooses the first matching PSK from the list of offered PSKs sent by the client.