Finalizes a private key operation and unblocks the connection.
Frees the opaque structure representing a private key operation.
Returns the input to the private key operation.
Returns the size of the input to the private key operation.
Returns the type of the private key operation.
Performs a private key operation using the given private key.
Sets the output of the private key operation.
Calculates the s2n stack trace.
Frees the memory associated with an s2n_cert_chain_and_key object.
Get the user supplied context from the s2n_cert_chain_and_key object.
Get the private key from the s2n_cert_chain_and_key object.
Associates a certificate chain and private key with an s2n_cert_chain_and_key object.
Associates a certificate chain and private key with an s2n_cert_chain_and_key object.
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.
Adds a context to the s2n_cert_chain_and_key object.
Set the raw OCSP stapling data for a certificate chain.
Set the signed certificate timestamp (SCT) for a certificate chain.
This is used for Certificate Transparency.
Returns the certificate out_cert present at the index cert_idx of the certificate chain chain_and_key.
@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.
Returns the s2n certificate in DER format along with its length.
Returns the UTF8 String representation of the DER encoded ASN.1 X.509 certificate extension data.
Returns the UTF8 String length of the ASN.1 X.509 certificate extension data.
Returns the DER encoding of an ASN.1 X.509 certificate extension value, it’s length and a boolean critical.
Returns the length of the DER encoded extension value of the ASN.1 X.509 certificate extension.
Cleans up any internal resources used by s2n-tls. This function should be called from each thread or process
that is created subsequent to calling s2n_init when that thread or process is done calling other s2n-tls functions.
Marks the non-blocking callback as complete. Can be invoked from within the callback when
operating in non-blocking mode to continue the handshake.
Frees an s2n_client_hello structure.
Copies into the out buffer max_length bytes of the cipher_suites on the ClientHello.
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().
Retrieves the list of compression methods sent in the Client Hello.
Get the length of the compression methods list sent in the Client Hello.
Copies into the out buffer max_length bytes of a given extension type on the ClientHello
Query the ClientHello message received by the server. Use this function to allocate the out buffer for
other client hello extension functions.
Copies into the out buffer max_length bytes of the extensions in the ClientHello.
Function to determine the size of the Client Hello extensions.
This can be used to allocate the out buffer for s2n_client_hello_get_extensions().
Access the Client Hello protocol version
Access the protocol version from the header of the first record that contained the ClientHello message.
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.
Function to determine the size of the raw Client Hello buffer.
Gets the first server name in a Client Hello.
Gets the length of the first server name in a Client Hello.
Copies up to max_length bytes of the ClientHello session_id into the out buffer and stores the number of copied bytes in out_length.
Get the the ClientHello session id length in bytes
Retrieves the supported groups received from the client in the supported groups extension.
Used to check if a particular extension exists in the client hello.
Creates an s2n_client_hello from bytes representing a ClientHello message.
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, 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).
Associates a set of Diffie-Hellman parameters with an s2n_config object.
@note dhparams_pem should be PEM encoded DH parameters.
Adds a PEM to the trust store. This will allocate memory, and load pem into the trust store.
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.
Appends the provided application protocol to the preference list
Disables timestamp validation for received certificates.
Turns off all X.509 validation during the negotiation phase of the connection. This should only
be used for testing or debugging purposes.
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
Frees the memory associated with an s2n_config object.
Frees the certificate chain and key associated with an s2n_config object.
Frees the DH params associated with an s2n_config object.
Gets Client Certificate authentication method the s2n_config object is using.
Gets the user defined context from the s2n_config object.
The context is set by calling s2n_config_set_ctx()
Retrieves the list of supported groups configured by the security policy associated with config.
Loads default system certificates into the trust store.
Creates a new s2n_config object. This object can (and should) be associated with many connection
objects.
Creates a new s2n_config object with minimal default options.
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.
Sets the config’s alert behavior based on the s2n_alert_behavior enum.
Sets up the callback to invoke when private key operations occur.
Configures whether or not s2n-tls will perform potentially expensive validation of
the results of a private key operation.
Allows the caller to set a callback function that will be used to delete SSL
session data from a cache.
Allows the caller to set a callback function that will be used to retrieve SSL
session data from a cache.
Allows the caller to set a callback function that will be used to store SSL
session data in a cache.
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.
Toggles whether or not to validate stapled OCSP responses.
Sets the security policy that includes the cipher/kem/signature/ecc preferences and
protocol version.
Sets whether or not a Client Certificate should be required to complete the TLS Connection.
Allows the caller to set a callback function that will be called after ClientHello was parsed.
Sets the callback execution mode.
Set the Certificate Transparency Support level.
Sets user defined context on the s2n_config object.
Set a callback to accept or reject early data.
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 initial number of session tickets to send after a >=TLS1.3 handshake. The default value is one ticket.
Sets a key logging callback on the provided config
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 PSK mode on the s2n config object.
The supported PSK modes are listed in the enum s2n_psk_mode above.
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.
Enable or disable receiving of multiple TLS records in a single s2n_recv call
Set a custom send buffer size.
Set what version to use when serializing connections
Sets the maximum bytes of early data the server will accept.
Enable or disable session caching.
Sets the lifetime of the cached session state. The default value is 15 hours.
Sets a session ticket callback to be called when a client receives a new session ticket.
Enable or disable session resumption using session ticket.
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.
Sets how long a session ticket key will be in a state where it can be used for both encryption
and decryption of tickets on the server side.
Adds to the trust store from a CA file or directory containing trusted certificates.
Toggle whether generated signatures are verified before being sent.
Sets the callback to use for verifying that a hostname from an X.509 certificate is trusted.
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).
Clears the trust store of all certificates.
Increases the number of session tickets to send after a >=TLS1.3 handshake.
Appends the provided application protocol to the preference list
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.
Check if Client Auth was used for a connection.
Deserializes the provided buffer into the s2n_connection parameter.
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.
Wipes and releases buffers and memory allocated during the TLS handshake.
Access the protocol version selected for the connection.
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 a human readable string of the cipher suite that was chosen
for a connection.
Returns the IANA value for the connection’s negotiated cipher suite.
Gets Client Certificate authentication method the s2n_connection object is using.
Gets the raw certificate chain received from the client.
Get the Client Hello from a s2n_connection.
Access the client hello protocol version for the connection.
Access the protocol version supported by the client.
Gets user defined context from a s2n_connection object.
Function to get the human readable elliptic curve name for the connection.
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().
Reports the current state of early data for a connection.
Function to return the last TLS handshake type that was processed. The returned format is a human readable string.
Function to get the human readable KEM group name for the connection.
Function to get the human readable KEM name for the connection.
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”.
Provides access to the TLS master secret.
Reports the maximum size of the early data allowed by a connection.
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.
Query the connection for a buffer containing the OCSP response.
Returns the validated peer certificate chain as a s2n_cert_chain_and_key opaque object.
Gets the assigned file descriptor for the read channel of an s2n connection.
Reports the remaining size of the early data allowed by a connection.
Query the connection for a buffer containing the Certificate Transparency response.
Get the certificate used during the TLS handshake
Get the client certificate’s digest algorithm.
Get the client certificate’s signature algorithm.
Get the connection’s selected digest algorithm.
Get the connection’s selected signature algorithm.
Access the protocol version supported by the server.
Serializes the session state from connection and copies into the session buffer and returns the number of copied bytes
Gets the latest session id from the connection, copies it into the session_id buffer, and returns the number of copied bytes.
Gets the latest session id’s length from the connection.
Use this to query the serialized session state size before copying it into a buffer.
Retrieves a hint from the server indicating how long this ticket’s lifetime is.
Returns the number of session tickets issued by the server.
Get the number of bytes the connection has received.
Get the number of bytes the connection has transmitted out.
Gets the assigned file descriptor for the write channel of an s2n connection.
Check if the connection is OCSP stapled.
Check if the connection was resumed from an earlier handshake.
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.
Change the behavior of s2n-tls when sending data to prefer low latency.
Change the behavior of s2n-tls when sending data to prefer high throughput.
Wipes and free the in and out buffers associated with a connection.
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.
Serializes the s2n_connection into the provided 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 whether or not a Client Certificate should be required to complete the TLS Connection.
Associates a configuration object with a connection.
Sets user defined context in s2n_connection object.
Configure the connection to free IO buffers when they are not currently in use.
Changes the behavior of s2n-tls when sending data to initially prefer records
small enough to fit in single ethernet frames.
Sets the file descriptor for a s2n connection.
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.
Sets the file descriptor for the read channel of an s2n connection.
Configure the connection to reduce potentially expensive calls to recv.
Configure a connection to use a recv callback to receive data.
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.
Configure a connection to use a send callback to send data.
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.
Sets the user context associated with early data on a server.
Sets the keying material lifetime for >=TLS1.3 session tickets so that one session doesn’t get re-used ad infinitum.
The default value is one week.
Sets the maximum bytes of early data the server will accept.
De-serializes the session state and updates the connection accordingly.
Sets the callback to use for verifying that a hostname from an X.509 certificate is trusted.
Sets the assigned file descriptor for the write channel of an s2n connection.
Provides access to the TLS-Exporter functionality.
Indicates to s2n that the connection is using corked IO.
Wipes an existing connection and allows it to be reused. Erases all data associated with a connection including
pending reads.
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.
Prevents S2N from installing an atexit handler, which allows safe shutdown of S2N from within a
re-entrant shared library
This function can be used instead of trying to resolve s2n_errno directly
in runtimes where thread-local variables may not be easily accessible.
Gets the category of error from an error.
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.
Clean up the memory used to contain the stack trace.
Query the connection for the selected application protocol.
Determines whether s2n-tls is operating in FIPS mode.
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.
Query the connection for the selected server name.
Export the s2n_stacktrace.
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.
Allows the caller to override s2n-tls’s internal memory handling functions.
Performs the initial “handshake” phase of a TLS connection and must be called before any s2n_recv() or s2n_send() calls.
Accept early data offered by the client.
Get the early data context set by the user.
Get the length of the early data context set by the user.
Reject early data offered by the client.
Frees the memory associated with the s2n_offered_psk object.
Gets the PSK identity and PSK identity length for a given offered PSK object.
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.
Returns the offered PSK list to its original read state.
Creates a new s2n offered PSK object.
An offered PSK object represents a single PSK sent by the client.
Allows users of s2n-tls to peek inside the data buffer of an s2n-tls connection to see if there more data to be read without actually reading it.
Reports how many bytes of unprocessed TLS records are buffered due to the optimization
enabled by s2n_connection_set_recv_buffering.
Prints the s2n stack trace to a file. The file descriptor is expected to be
open and ready for writing.
Configures a particular pre-shared key to allow early data.
Frees the memory associated with the external PSK object.
Sets the optional application_protocol associated with the given pre-shared key.
Sets the optional user early data context associated with the given pre-shared key.
Sets the hash algorithm for a given external PSK object. The supported PSK hash
algorithms are as listed in the enum s2n_psk_hmac above.
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.
Sets the out-of-band/externally provisioned secret for a given external PSK object.
Allows the caller to override s2n-tls’s entropy functions.
Decrypts and reads *size to buf data from the associated
connection.
Called by the server to begin negotiation and accept any early data the client sends.
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.
Called by the client to begin negotiation and send early data.
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.
Gets the session ticket data from a session ticket object.
Gets the length of the session ticket from a session ticket object.
Gets the lifetime in seconds of the session ticket from a session ticket object.
Sets the server name for the connection.
Attempts a closure at the TLS layer. Does not close the underlying transport. This call may block in either direction.
Attempts to close the write side of the TLS connection.
Checks if s2n stack trace captures are enabled.
Configures the s2n stack trace captures option.
Translates an s2n_error code to a human readable string explaining the error.
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.
Translates an s2n_error code to a human readable string.
Translates an s2n_error code to a filename and line number.