Crate s2n_tls_sys
source ·Modules
Structs
Opaque async private key operation handle
Opaque certificate type.
Opaque certificate chain and key type.
Opaque client hello handle
An opaque configuration object, used by clients and servers for holding cryptographic certificates, keys and preferences.
An opaque connection. Used to track each s2n connection.
Opaque key type.
Opaque pre shared key handle
Opaque stack trace structure.
Functions
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.
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().Copies into the
out
buffer max_length
bytes of a given extension type on the ClientHelloQuery 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().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. For SSLv2 ClientHello messages, the raw message contains only
the cipher_specs, session_id and members portions of the hello message
(see RFC5246). To access other
members, you may use s2n_connection_get_client_hello_version(),
s2n_connection_get_client_protocol_version() and s2n_connection_get_session_id_length()
accessors functions.Function to determine the size of the raw Client Hello buffer.
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
Used to check if a particular extension exists in the client hello.
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. Note that the trust store will be initialized with the common locations
for the host operating system by default. To completely override those locations,
call s2n_config_wipe_trust_store before calling this function.
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
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()Create a new s2n_config object. This object can (and should) be associated with many connection objects.
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.
Set a custom send buffer size.
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 an S2N_CLIENT to request the server certificate status 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.
To completely override those locations, call s2n_config_wipe_trust_store() before calling
this function.
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).
Clear the trust store.
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.
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 client certificate chain and places it in the
der_cert_chain_out
buffer. cert_chain_len
is updated
to match the size the chain buffer.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”.
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 bytesGets 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 is 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.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 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.
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.
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.
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() except that the latter’s
offs
parameter is implicitly assumed to be 0.
Therefore in the partial write case, the caller would have to make sure that 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.
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.
Type Definitions
Callback function for handling private key operations
Cache callback function that allows the caller to set a callback function
that will be used to delete SSL session data from a cache.
Cache callback function that allows the caller to retrieve SSL session data
from a cache.
Cache callback function that allows the caller to store SSL session data in a
cache.
Opaque private key type.
Opaque public key type.
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 type used to get the system time.
A callback which can be implemented to accept or reject early data.
Callback function for handling key log events
Will be called when
s2n_cleanup
is executed.Frees memory allocated by s2n_mem_malloc_callback.
Called when
s2n_init
is executed.A function that can allocate at least
requested
bytes of memory.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.
A callback function that will be called when
s2n_cleanup
is executed.A callback function that will be called when s2n-tls is initialized.
A callback function that will be used to mix in entropy every time the RNG
is invoked.
A callback function that will be used to provide entropy to the s2n-tls
random number generators.
Function pointer for a user provided send callback.
Function pointer for a user provided send callback.
Callback function for receiving a session ticket.
A callback function invoked (usually multiple times) during X.509 validation for each
name encountered in the leaf certificate.