AWS s2n-tls v1.5.5-6ca63e42
s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be simple, small, fast, and with security as a priority.
Loading...
Searching...
No Matches
Macros | Typedefs | Enumerations | Functions | Variables
s2n.h File Reference
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <sys/types.h>
#include <sys/uio.h>

Go to the source code of this file.

Macros

#define S2N_API
 
#define S2N_SUCCESS   0
 
#define S2N_FAILURE   -1
 
#define S2N_CALLBACK_BLOCKED   -2
 
#define S2N_MINIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION   2
 
#define S2N_MAXIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION   3
 
#define S2N_SSLv2   20
 
#define S2N_SSLv3   30
 
#define S2N_TLS10   31
 
#define S2N_TLS11   32
 
#define S2N_TLS12   33
 
#define S2N_TLS13   34
 
#define S2N_UNKNOWN_PROTOCOL_VERSION   0
 

Typedefs

typedef int(* s2n_clock_time_nanoseconds) (void *, uint64_t *)
 
typedef int(* s2n_cache_retrieve_callback) (struct s2n_connection *conn, void *, const void *key, uint64_t key_size, void *value, uint64_t *value_size)
 
typedef int(* s2n_cache_store_callback) (struct s2n_connection *conn, void *, uint64_t ttl_in_seconds, const void *key, uint64_t key_size, const void *value, uint64_t value_size)
 
typedef int(* s2n_cache_delete_callback) (struct s2n_connection *conn, void *, const void *key, uint64_t key_size)
 
typedef int(* s2n_mem_init_callback) (void)
 
typedef int(* s2n_mem_cleanup_callback) (void)
 
typedef int(* s2n_mem_malloc_callback) (void **ptr, uint32_t requested, uint32_t *allocated)
 
typedef int(* s2n_mem_free_callback) (void *ptr, uint32_t size)
 
typedef int(* s2n_rand_init_callback) (void)
 
typedef int(* s2n_rand_cleanup_callback) (void)
 
typedef int(* s2n_rand_seed_callback) (void *data, uint32_t size)
 
typedef int(* s2n_rand_mix_callback) (void *data, uint32_t size)
 
typedef struct s2n_pkey s2n_cert_public_key
 
typedef struct s2n_pkey s2n_cert_private_key
 
typedef struct s2n_cert_chain_and_key *(* s2n_cert_tiebreak_callback) (struct s2n_cert_chain_and_key *cert1, struct s2n_cert_chain_and_key *cert2, uint8_t *name, uint32_t name_len)
 
typedef uint8_t(* s2n_verify_host_fn) (const char *host_name, size_t host_name_len, void *data)
 
typedef int s2n_client_hello_fn(struct s2n_connection *conn, void *ctx)
 
typedef int s2n_recv_fn(void *io_context, uint8_t *buf, uint32_t len)
 
typedef int s2n_send_fn(void *io_context, const uint8_t *buf, uint32_t len)
 
typedef int(* s2n_session_ticket_fn) (struct s2n_connection *conn, void *ctx, struct s2n_session_ticket *ticket)
 
typedef int(* s2n_psk_selection_callback) (struct s2n_connection *conn, void *context, struct s2n_offered_psk_list *psk_list)
 
typedef int(* s2n_async_pkey_fn) (struct s2n_connection *conn, struct s2n_async_pkey_op *op)
 
typedef int(* s2n_key_log_fn) (void *ctx, struct s2n_connection *conn, uint8_t *logline, size_t len)
 
typedef int(* s2n_early_data_cb) (struct s2n_connection *conn, struct s2n_offered_early_data *early_data)
 

Enumerations

enum  s2n_error_type {
  S2N_ERR_T_OK = 0 , S2N_ERR_T_IO , S2N_ERR_T_CLOSED , S2N_ERR_T_BLOCKED ,
  S2N_ERR_T_ALERT , S2N_ERR_T_PROTO , S2N_ERR_T_INTERNAL , S2N_ERR_T_USAGE
}
 
enum  s2n_fips_mode { S2N_FIPS_MODE_DISABLED = 0 , S2N_FIPS_MODE_ENABLED }
 
enum  s2n_tls_extension_type {
  S2N_EXTENSION_SERVER_NAME = 0 , S2N_EXTENSION_MAX_FRAG_LEN = 1 , S2N_EXTENSION_OCSP_STAPLING = 5 , S2N_EXTENSION_SUPPORTED_GROUPS = 10 ,
  S2N_EXTENSION_EC_POINT_FORMATS = 11 , S2N_EXTENSION_SIGNATURE_ALGORITHMS = 13 , S2N_EXTENSION_ALPN = 16 , S2N_EXTENSION_CERTIFICATE_TRANSPARENCY = 18 ,
  S2N_EXTENSION_SUPPORTED_VERSIONS = 43 , S2N_EXTENSION_RENEGOTIATION_INFO = 65281
}
 
enum  s2n_max_frag_len { S2N_TLS_MAX_FRAG_LEN_512 = 1 , S2N_TLS_MAX_FRAG_LEN_1024 = 2 , S2N_TLS_MAX_FRAG_LEN_2048 = 3 , S2N_TLS_MAX_FRAG_LEN_4096 = 4 }
 
enum  s2n_verify_after_sign { S2N_VERIFY_AFTER_SIGN_DISABLED , S2N_VERIFY_AFTER_SIGN_ENABLED }
 
enum  s2n_status_request_type { S2N_STATUS_REQUEST_NONE = 0 , S2N_STATUS_REQUEST_OCSP = 1 }
 
enum  s2n_ct_support_level { S2N_CT_SUPPORT_NONE = 0 , S2N_CT_SUPPORT_REQUEST = 1 }
 
enum  s2n_alert_behavior { S2N_ALERT_FAIL_ON_WARNINGS = 0 , S2N_ALERT_IGNORE_WARNINGS = 1 }
 
enum  s2n_mode { S2N_SERVER , S2N_CLIENT }
 
enum  s2n_client_hello_cb_mode { S2N_CLIENT_HELLO_CB_BLOCKING , S2N_CLIENT_HELLO_CB_NONBLOCKING }
 
enum  s2n_blinding { S2N_BUILT_IN_BLINDING , S2N_SELF_SERVICE_BLINDING }
 
enum  s2n_peer_key_update { S2N_KEY_UPDATE_NOT_REQUESTED = 0 , S2N_KEY_UPDATE_REQUESTED }
 
enum  s2n_blocked_status {
  S2N_NOT_BLOCKED = 0 , S2N_BLOCKED_ON_READ , S2N_BLOCKED_ON_WRITE , S2N_BLOCKED_ON_APPLICATION_INPUT ,
  S2N_BLOCKED_ON_EARLY_DATA
}
 
enum  s2n_cert_auth_type { S2N_CERT_AUTH_NONE , S2N_CERT_AUTH_REQUIRED , S2N_CERT_AUTH_OPTIONAL }
 
enum  s2n_tls_signature_algorithm {
  S2N_TLS_SIGNATURE_ANONYMOUS = 0 , S2N_TLS_SIGNATURE_RSA = 1 , S2N_TLS_SIGNATURE_ECDSA = 3 , S2N_TLS_SIGNATURE_RSA_PSS_RSAE = 224 ,
  S2N_TLS_SIGNATURE_RSA_PSS_PSS
}
 
enum  s2n_tls_hash_algorithm {
  S2N_TLS_HASH_NONE = 0 , S2N_TLS_HASH_MD5 = 1 , S2N_TLS_HASH_SHA1 = 2 , S2N_TLS_HASH_SHA224 = 3 ,
  S2N_TLS_HASH_SHA256 = 4 , S2N_TLS_HASH_SHA384 = 5 , S2N_TLS_HASH_SHA512 = 6 , S2N_TLS_HASH_MD5_SHA1 = 224
}
 
enum  s2n_psk_hmac { S2N_PSK_HMAC_SHA256 , S2N_PSK_HMAC_SHA384 }
 
enum  s2n_psk_mode { S2N_PSK_MODE_RESUMPTION , S2N_PSK_MODE_EXTERNAL }
 
enum  s2n_async_pkey_validation_mode { S2N_ASYNC_PKEY_VALIDATION_FAST , S2N_ASYNC_PKEY_VALIDATION_STRICT }
 
enum  s2n_async_pkey_op_type { S2N_ASYNC_DECRYPT , S2N_ASYNC_SIGN }
 
enum  s2n_early_data_status_t { S2N_EARLY_DATA_STATUS_OK , S2N_EARLY_DATA_STATUS_NOT_REQUESTED , S2N_EARLY_DATA_STATUS_REJECTED , S2N_EARLY_DATA_STATUS_END }
 
enum  s2n_serialization_version { S2N_SERIALIZED_CONN_NONE = 0 , S2N_SERIALIZED_CONN_V1 = 1 }
 

Functions

S2N_API int * s2n_errno_location (void)
 
S2N_API int s2n_error_get_type (int error)
 
S2N_API int s2n_crypto_disable_init (void)
 
S2N_API int s2n_disable_atexit (void)
 
S2N_API unsigned long s2n_get_openssl_version (void)
 
S2N_API int s2n_init (void)
 
S2N_API int s2n_cleanup (void)
 
S2N_API int s2n_get_fips_mode (s2n_fips_mode *fips_mode)
 
S2N_API struct s2n_config * s2n_config_new (void)
 
S2N_API struct s2n_config * s2n_config_new_minimal (void)
 
S2N_API int s2n_config_free (struct s2n_config *config)
 
S2N_API int s2n_config_free_dhparams (struct s2n_config *config)
 
S2N_API int s2n_config_free_cert_chain_and_key (struct s2n_config *config)
 
S2N_API int s2n_config_set_wall_clock (struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx)
 
S2N_API int s2n_config_set_monotonic_clock (struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx)
 
S2N_API const char * s2n_strerror (int error, const char *lang)
 
S2N_API const char * s2n_strerror_debug (int error, const char *lang)
 
S2N_API const char * s2n_strerror_name (int error)
 
S2N_API const char * s2n_strerror_source (int error)
 
S2N_API bool s2n_stack_traces_enabled (void)
 
S2N_API int s2n_stack_traces_enabled_set (bool newval)
 
S2N_API int s2n_calculate_stacktrace (void)
 
S2N_API int s2n_print_stacktrace (FILE *fptr)
 
S2N_API int s2n_free_stacktrace (void)
 
S2N_API int s2n_get_stacktrace (struct s2n_stacktrace *trace)
 
S2N_API int s2n_config_set_cache_store_callback (struct s2n_config *config, s2n_cache_store_callback cache_store_callback, void *data)
 
S2N_API int s2n_config_set_cache_retrieve_callback (struct s2n_config *config, s2n_cache_retrieve_callback cache_retrieve_callback, void *data)
 
S2N_API int s2n_config_set_cache_delete_callback (struct s2n_config *config, s2n_cache_delete_callback cache_delete_callback, void *data)
 
S2N_API int s2n_mem_set_callbacks (s2n_mem_init_callback mem_init_callback, s2n_mem_cleanup_callback mem_cleanup_callback, s2n_mem_malloc_callback mem_malloc_callback, s2n_mem_free_callback mem_free_callback)
 
S2N_API int s2n_rand_set_callbacks (s2n_rand_init_callback rand_init_callback, s2n_rand_cleanup_callback rand_cleanup_callback, s2n_rand_seed_callback rand_seed_callback, s2n_rand_mix_callback rand_mix_callback)
 
S2N_API struct s2n_cert_chain_and_key * s2n_cert_chain_and_key_new (void)
 
S2N_API int s2n_cert_chain_and_key_load_pem (struct s2n_cert_chain_and_key *chain_and_key, const char *chain_pem, const char *private_key_pem)
 
S2N_API int s2n_cert_chain_and_key_load_pem_bytes (struct s2n_cert_chain_and_key *chain_and_key, uint8_t *chain_pem, uint32_t chain_pem_len, uint8_t *private_key_pem, uint32_t private_key_pem_len)
 
S2N_API int s2n_cert_chain_and_key_load_public_pem_bytes (struct s2n_cert_chain_and_key *chain_and_key, uint8_t *chain_pem, uint32_t chain_pem_len)
 
S2N_API int s2n_cert_chain_and_key_free (struct s2n_cert_chain_and_key *cert_and_key)
 
S2N_API int s2n_cert_chain_and_key_set_ctx (struct s2n_cert_chain_and_key *cert_and_key, void *ctx)
 
S2N_API void * s2n_cert_chain_and_key_get_ctx (struct s2n_cert_chain_and_key *cert_and_key)
 
S2N_API s2n_cert_private_keys2n_cert_chain_and_key_get_private_key (struct s2n_cert_chain_and_key *cert_and_key)
 
S2N_API int s2n_cert_chain_and_key_set_ocsp_data (struct s2n_cert_chain_and_key *chain_and_key, const uint8_t *data, uint32_t length)
 
S2N_API int s2n_cert_chain_and_key_set_sct_list (struct s2n_cert_chain_and_key *chain_and_key, const uint8_t *data, uint32_t length)
 
S2N_API int s2n_config_set_cert_tiebreak_callback (struct s2n_config *config, s2n_cert_tiebreak_callback cert_tiebreak_cb)
 
S2N_API int s2n_config_add_cert_chain_and_key (struct s2n_config *config, const char *cert_chain_pem, const char *private_key_pem)
 
S2N_API int s2n_config_add_cert_chain_and_key_to_store (struct s2n_config *config, struct s2n_cert_chain_and_key *cert_key_pair)
 
S2N_API int s2n_config_set_cert_chain_and_key_defaults (struct s2n_config *config, struct s2n_cert_chain_and_key **cert_key_pairs, uint32_t num_cert_key_pairs)
 
S2N_API int s2n_config_set_verification_ca_location (struct s2n_config *config, const char *ca_pem_filename, const char *ca_dir)
 
S2N_API int s2n_config_add_pem_to_trust_store (struct s2n_config *config, const char *pem)
 
S2N_API int s2n_config_wipe_trust_store (struct s2n_config *config)
 
S2N_API int s2n_config_load_system_certs (struct s2n_config *config)
 
S2N_API int s2n_config_set_verify_after_sign (struct s2n_config *config, s2n_verify_after_sign mode)
 
S2N_API int s2n_config_set_send_buffer_size (struct s2n_config *config, uint32_t size)
 
S2N_API int s2n_config_set_recv_multi_record (struct s2n_config *config, bool enabled)
 
S2N_API int s2n_config_set_verify_host_callback (struct s2n_config *config, s2n_verify_host_fn, void *data)
 
S2N_API int s2n_config_set_check_stapled_ocsp_response (struct s2n_config *config, uint8_t check_ocsp)
 
S2N_API int s2n_config_disable_x509_time_verification (struct s2n_config *config)
 
S2N_API int s2n_config_disable_x509_verification (struct s2n_config *config)
 
S2N_API int s2n_config_set_max_cert_chain_depth (struct s2n_config *config, uint16_t max_depth)
 
S2N_API int s2n_config_add_dhparams (struct s2n_config *config, const char *dhparams_pem)
 
S2N_API int s2n_config_set_cipher_preferences (struct s2n_config *config, const char *version)
 
S2N_API int s2n_config_append_protocol_preference (struct s2n_config *config, const uint8_t *protocol, uint8_t protocol_len)
 
S2N_API int s2n_config_set_protocol_preferences (struct s2n_config *config, const char *const *protocols, int protocol_count)
 
S2N_API int s2n_config_set_status_request_type (struct s2n_config *config, s2n_status_request_type type)
 
S2N_API int s2n_config_set_ct_support_level (struct s2n_config *config, s2n_ct_support_level level)
 
S2N_API int s2n_config_set_alert_behavior (struct s2n_config *config, s2n_alert_behavior alert_behavior)
 
S2N_API int s2n_config_set_extension_data (struct s2n_config *config, s2n_tls_extension_type type, const uint8_t *data, uint32_t length)
 
S2N_API int s2n_config_send_max_fragment_length (struct s2n_config *config, s2n_max_frag_len mfl_code)
 
S2N_API int s2n_config_accept_max_fragment_length (struct s2n_config *config)
 
S2N_API int s2n_config_set_session_state_lifetime (struct s2n_config *config, uint64_t lifetime_in_secs)
 
S2N_API int s2n_config_set_session_tickets_onoff (struct s2n_config *config, uint8_t enabled)
 
S2N_API int s2n_config_set_session_cache_onoff (struct s2n_config *config, uint8_t enabled)
 
S2N_API int s2n_config_set_ticket_encrypt_decrypt_key_lifetime (struct s2n_config *config, uint64_t lifetime_in_secs)
 
S2N_API int s2n_config_set_ticket_decrypt_key_lifetime (struct s2n_config *config, uint64_t lifetime_in_secs)
 
S2N_API int s2n_config_add_ticket_crypto_key (struct s2n_config *config, const uint8_t *name, uint32_t name_len, uint8_t *key, uint32_t key_len, uint64_t intro_time_in_seconds_from_epoch)
 
S2N_API int s2n_config_require_ticket_forward_secrecy (struct s2n_config *config, bool enabled)
 
S2N_API int s2n_config_set_ctx (struct s2n_config *config, void *ctx)
 
S2N_API int s2n_config_get_ctx (struct s2n_config *config, void **ctx)
 
S2N_API struct s2n_connection * s2n_connection_new (s2n_mode mode)
 
S2N_API int s2n_connection_set_config (struct s2n_connection *conn, struct s2n_config *config)
 
S2N_API int s2n_connection_set_ctx (struct s2n_connection *conn, void *ctx)
 
S2N_API void * s2n_connection_get_ctx (struct s2n_connection *conn)
 
S2N_API int s2n_config_set_client_hello_cb (struct s2n_config *config, s2n_client_hello_fn client_hello_callback, void *ctx)
 
S2N_API int s2n_config_set_client_hello_cb_mode (struct s2n_config *config, s2n_client_hello_cb_mode cb_mode)
 
S2N_API int s2n_client_hello_cb_done (struct s2n_connection *conn)
 
S2N_API int s2n_connection_server_name_extension_used (struct s2n_connection *conn)
 
S2N_API struct s2n_client_hello * s2n_connection_get_client_hello (struct s2n_connection *conn)
 
S2N_API struct s2n_client_hello * s2n_client_hello_parse_message (const uint8_t *bytes, uint32_t size)
 
S2N_API int s2n_client_hello_free (struct s2n_client_hello **ch)
 
S2N_API ssize_t s2n_client_hello_get_raw_message_length (struct s2n_client_hello *ch)
 
S2N_API ssize_t s2n_client_hello_get_raw_message (struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length)
 
S2N_API ssize_t s2n_client_hello_get_cipher_suites_length (struct s2n_client_hello *ch)
 
S2N_API ssize_t s2n_client_hello_get_cipher_suites (struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length)
 
S2N_API ssize_t s2n_client_hello_get_extensions_length (struct s2n_client_hello *ch)
 
S2N_API ssize_t s2n_client_hello_get_extensions (struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length)
 
S2N_API ssize_t s2n_client_hello_get_extension_length (struct s2n_client_hello *ch, s2n_tls_extension_type extension_type)
 
S2N_API ssize_t s2n_client_hello_get_extension_by_id (struct s2n_client_hello *ch, s2n_tls_extension_type extension_type, uint8_t *out, uint32_t max_length)
 
S2N_API int s2n_client_hello_has_extension (struct s2n_client_hello *ch, uint16_t extension_iana, bool *exists)
 
S2N_API int s2n_client_hello_get_session_id_length (struct s2n_client_hello *ch, uint32_t *out_length)
 
S2N_API int s2n_client_hello_get_session_id (struct s2n_client_hello *ch, uint8_t *out, uint32_t *out_length, uint32_t max_length)
 
S2N_API int s2n_client_hello_get_compression_methods_length (struct s2n_client_hello *ch, uint32_t *out_length)
 
S2N_API int s2n_client_hello_get_compression_methods (struct s2n_client_hello *ch, uint8_t *list, uint32_t list_length, uint32_t *out_length)
 
S2N_API int s2n_client_hello_get_legacy_protocol_version (struct s2n_client_hello *ch, uint8_t *out)
 
S2N_API int s2n_client_hello_get_supported_groups (struct s2n_client_hello *ch, uint16_t *groups, uint16_t groups_count_max, uint16_t *groups_count)
 
S2N_API int s2n_client_hello_get_server_name_length (struct s2n_client_hello *ch, uint16_t *length)
 
S2N_API int s2n_client_hello_get_server_name (struct s2n_client_hello *ch, uint8_t *server_name, uint16_t length, uint16_t *out_length)
 
S2N_API int s2n_connection_set_fd (struct s2n_connection *conn, int fd)
 
S2N_API int s2n_connection_set_read_fd (struct s2n_connection *conn, int readfd)
 
S2N_API int s2n_connection_set_write_fd (struct s2n_connection *conn, int writefd)
 
S2N_API int s2n_connection_get_read_fd (struct s2n_connection *conn, int *readfd)
 
S2N_API int s2n_connection_get_write_fd (struct s2n_connection *conn, int *writefd)
 
S2N_API int s2n_connection_use_corked_io (struct s2n_connection *conn)
 
S2N_API int s2n_connection_set_recv_ctx (struct s2n_connection *conn, void *ctx)
 
S2N_API int s2n_connection_set_send_ctx (struct s2n_connection *conn, void *ctx)
 
S2N_API int s2n_connection_set_recv_cb (struct s2n_connection *conn, s2n_recv_fn recv)
 
S2N_API int s2n_connection_set_send_cb (struct s2n_connection *conn, s2n_send_fn send)
 
S2N_API int s2n_connection_prefer_throughput (struct s2n_connection *conn)
 
S2N_API int s2n_connection_prefer_low_latency (struct s2n_connection *conn)
 
S2N_API int s2n_connection_set_recv_buffering (struct s2n_connection *conn, bool enabled)
 
S2N_API uint32_t s2n_peek_buffered (struct s2n_connection *conn)
 
S2N_API int s2n_connection_set_dynamic_buffers (struct s2n_connection *conn, bool enabled)
 
S2N_API int s2n_connection_set_dynamic_record_threshold (struct s2n_connection *conn, uint32_t resize_threshold, uint16_t timeout_threshold)
 
S2N_API int s2n_connection_set_verify_host_callback (struct s2n_connection *conn, s2n_verify_host_fn host_fn, void *data)
 
S2N_API int s2n_connection_set_blinding (struct s2n_connection *conn, s2n_blinding blinding)
 
S2N_API uint64_t s2n_connection_get_delay (struct s2n_connection *conn)
 
S2N_API int s2n_config_set_max_blinding_delay (struct s2n_config *config, uint32_t seconds)
 
S2N_API int s2n_connection_set_cipher_preferences (struct s2n_connection *conn, const char *version)
 
S2N_API int s2n_connection_request_key_update (struct s2n_connection *conn, s2n_peer_key_update peer_request)
 
S2N_API int s2n_connection_append_protocol_preference (struct s2n_connection *conn, const uint8_t *protocol, uint8_t protocol_len)
 
S2N_API int s2n_connection_set_protocol_preferences (struct s2n_connection *conn, const char *const *protocols, int protocol_count)
 
S2N_API int s2n_set_server_name (struct s2n_connection *conn, const char *server_name)
 
S2N_API const char * s2n_get_server_name (struct s2n_connection *conn)
 
S2N_API const char * s2n_get_application_protocol (struct s2n_connection *conn)
 
S2N_API const uint8_t * s2n_connection_get_ocsp_response (struct s2n_connection *conn, uint32_t *length)
 
S2N_API const uint8_t * s2n_connection_get_sct_list (struct s2n_connection *conn, uint32_t *length)
 
S2N_API int s2n_negotiate (struct s2n_connection *conn, s2n_blocked_status *blocked)
 
S2N_API ssize_t s2n_send (struct s2n_connection *conn, const void *buf, ssize_t size, s2n_blocked_status *blocked)
 
S2N_API ssize_t s2n_sendv (struct s2n_connection *conn, const struct iovec *bufs, ssize_t count, s2n_blocked_status *blocked)
 
S2N_API ssize_t s2n_sendv_with_offset (struct s2n_connection *conn, const struct iovec *bufs, ssize_t count, ssize_t offs, s2n_blocked_status *blocked)
 
S2N_API ssize_t s2n_recv (struct s2n_connection *conn, void *buf, ssize_t size, s2n_blocked_status *blocked)
 
S2N_API uint32_t s2n_peek (struct s2n_connection *conn)
 
S2N_API int s2n_connection_free_handshake (struct s2n_connection *conn)
 
S2N_API int s2n_connection_release_buffers (struct s2n_connection *conn)
 
S2N_API int s2n_connection_wipe (struct s2n_connection *conn)
 
S2N_API int s2n_connection_free (struct s2n_connection *conn)
 
S2N_API int s2n_shutdown (struct s2n_connection *conn, s2n_blocked_status *blocked)
 
S2N_API int s2n_shutdown_send (struct s2n_connection *conn, s2n_blocked_status *blocked)
 
S2N_API int s2n_config_get_client_auth_type (struct s2n_config *config, s2n_cert_auth_type *client_auth_type)
 
S2N_API int s2n_config_set_client_auth_type (struct s2n_config *config, s2n_cert_auth_type client_auth_type)
 
S2N_API int s2n_connection_get_client_auth_type (struct s2n_connection *conn, s2n_cert_auth_type *client_auth_type)
 
S2N_API int s2n_connection_set_client_auth_type (struct s2n_connection *conn, s2n_cert_auth_type client_auth_type)
 
S2N_API int s2n_connection_get_client_cert_chain (struct s2n_connection *conn, uint8_t **der_cert_chain_out, uint32_t *cert_chain_len)
 
S2N_API int s2n_config_set_initial_ticket_count (struct s2n_config *config, uint8_t num)
 
S2N_API int s2n_connection_add_new_tickets_to_send (struct s2n_connection *conn, uint8_t num)
 
S2N_API int s2n_connection_get_tickets_sent (struct s2n_connection *conn, uint16_t *num)
 
S2N_API int s2n_connection_set_server_keying_material_lifetime (struct s2n_connection *conn, uint32_t lifetime_in_secs)
 
S2N_API int s2n_config_set_session_ticket_cb (struct s2n_config *config, s2n_session_ticket_fn callback, void *ctx)
 
S2N_API int s2n_session_ticket_get_data_len (struct s2n_session_ticket *ticket, size_t *data_len)
 
S2N_API int s2n_session_ticket_get_data (struct s2n_session_ticket *ticket, size_t max_data_len, uint8_t *data)
 
S2N_API int s2n_session_ticket_get_lifetime (struct s2n_session_ticket *ticket, uint32_t *session_lifetime)
 
S2N_API int s2n_connection_set_session (struct s2n_connection *conn, const uint8_t *session, size_t length)
 
S2N_API int s2n_connection_get_session (struct s2n_connection *conn, uint8_t *session, size_t max_length)
 
S2N_API int s2n_connection_get_session_ticket_lifetime_hint (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_session_length (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_session_id_length (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_session_id (struct s2n_connection *conn, uint8_t *session_id, size_t max_length)
 
S2N_API int s2n_connection_is_session_resumed (struct s2n_connection *conn)
 
S2N_API int s2n_connection_is_ocsp_stapled (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_selected_signature_algorithm (struct s2n_connection *conn, s2n_tls_signature_algorithm *chosen_alg)
 
S2N_API int s2n_connection_get_selected_digest_algorithm (struct s2n_connection *conn, s2n_tls_hash_algorithm *chosen_alg)
 
S2N_API int s2n_connection_get_selected_client_cert_signature_algorithm (struct s2n_connection *conn, s2n_tls_signature_algorithm *chosen_alg)
 
S2N_API int s2n_connection_get_selected_client_cert_digest_algorithm (struct s2n_connection *conn, s2n_tls_hash_algorithm *chosen_alg)
 
S2N_API struct s2n_cert_chain_and_key * s2n_connection_get_selected_cert (struct s2n_connection *conn)
 
S2N_API int s2n_cert_chain_get_length (const struct s2n_cert_chain_and_key *chain_and_key, uint32_t *cert_length)
 
S2N_API int s2n_cert_chain_get_cert (const struct s2n_cert_chain_and_key *chain_and_key, struct s2n_cert **out_cert, const uint32_t cert_idx)
 
S2N_API int s2n_cert_get_der (const struct s2n_cert *cert, const uint8_t **out_cert_der, uint32_t *cert_length)
 
S2N_API int s2n_connection_get_peer_cert_chain (const struct s2n_connection *conn, struct s2n_cert_chain_and_key *cert_chain)
 
S2N_API int s2n_cert_get_x509_extension_value_length (struct s2n_cert *cert, const uint8_t *oid, uint32_t *ext_value_len)
 
S2N_API int s2n_cert_get_x509_extension_value (struct s2n_cert *cert, const uint8_t *oid, uint8_t *ext_value, uint32_t *ext_value_len, bool *critical)
 
S2N_API int s2n_cert_get_utf8_string_from_extension_data_length (const uint8_t *extension_data, uint32_t extension_len, uint32_t *utf8_str_len)
 
S2N_API int s2n_cert_get_utf8_string_from_extension_data (const uint8_t *extension_data, uint32_t extension_len, uint8_t *out_data, uint32_t *out_len)
 
S2N_API struct s2n_psk * s2n_external_psk_new (void)
 
S2N_API int s2n_psk_free (struct s2n_psk **psk)
 
S2N_API int s2n_psk_set_identity (struct s2n_psk *psk, const uint8_t *identity, uint16_t identity_size)
 
S2N_API int s2n_psk_set_secret (struct s2n_psk *psk, const uint8_t *secret, uint16_t secret_size)
 
S2N_API int s2n_psk_set_hmac (struct s2n_psk *psk, s2n_psk_hmac hmac)
 
S2N_API int s2n_connection_append_psk (struct s2n_connection *conn, struct s2n_psk *psk)
 
S2N_API int s2n_config_set_psk_mode (struct s2n_config *config, s2n_psk_mode mode)
 
S2N_API int s2n_connection_set_psk_mode (struct s2n_connection *conn, s2n_psk_mode mode)
 
S2N_API int s2n_connection_get_negotiated_psk_identity_length (struct s2n_connection *conn, uint16_t *identity_length)
 
S2N_API int s2n_connection_get_negotiated_psk_identity (struct s2n_connection *conn, uint8_t *identity, uint16_t max_identity_length)
 
S2N_API struct s2n_offered_psk * s2n_offered_psk_new (void)
 
S2N_API int s2n_offered_psk_free (struct s2n_offered_psk **psk)
 
S2N_API int s2n_offered_psk_get_identity (struct s2n_offered_psk *psk, uint8_t **identity, uint16_t *size)
 
S2N_API bool s2n_offered_psk_list_has_next (struct s2n_offered_psk_list *psk_list)
 
S2N_API int s2n_offered_psk_list_next (struct s2n_offered_psk_list *psk_list, struct s2n_offered_psk *psk)
 
S2N_API int s2n_offered_psk_list_reread (struct s2n_offered_psk_list *psk_list)
 
S2N_API int s2n_offered_psk_list_choose_psk (struct s2n_offered_psk_list *psk_list, struct s2n_offered_psk *psk)
 
S2N_API int s2n_config_set_psk_selection_callback (struct s2n_config *config, s2n_psk_selection_callback cb, void *context)
 
S2N_API uint64_t s2n_connection_get_wire_bytes_in (struct s2n_connection *conn)
 
S2N_API uint64_t s2n_connection_get_wire_bytes_out (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_client_protocol_version (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_server_protocol_version (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_actual_protocol_version (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_client_hello_version (struct s2n_connection *conn)
 
S2N_API int s2n_client_hello_get_legacy_record_version (struct s2n_client_hello *ch, uint8_t *out)
 
S2N_API int s2n_connection_client_cert_used (struct s2n_connection *conn)
 
S2N_API const char * s2n_connection_get_cipher (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_master_secret (const struct s2n_connection *conn, uint8_t *secret_bytes, size_t max_size)
 
S2N_API int s2n_connection_tls_exporter (struct s2n_connection *conn, const uint8_t *label, uint32_t label_length, const uint8_t *context, uint32_t context_length, uint8_t *output, uint32_t output_length)
 
S2N_API int s2n_connection_get_cipher_iana_value (struct s2n_connection *conn, uint8_t *first, uint8_t *second)
 
S2N_API int s2n_connection_is_valid_for_cipher_preferences (struct s2n_connection *conn, const char *version)
 
S2N_API const char * s2n_connection_get_curve (struct s2n_connection *conn)
 
S2N_API const char * s2n_connection_get_kem_name (struct s2n_connection *conn)
 
S2N_API const char * s2n_connection_get_kem_group_name (struct s2n_connection *conn)
 
S2N_API int s2n_connection_get_alert (struct s2n_connection *conn)
 
S2N_API const char * s2n_connection_get_handshake_type_name (struct s2n_connection *conn)
 
S2N_API const char * s2n_connection_get_last_message_name (struct s2n_connection *conn)
 
S2N_API int s2n_config_set_async_pkey_callback (struct s2n_config *config, s2n_async_pkey_fn fn)
 
S2N_API int s2n_async_pkey_op_perform (struct s2n_async_pkey_op *op, s2n_cert_private_key *key)
 
S2N_API int s2n_async_pkey_op_apply (struct s2n_async_pkey_op *op, struct s2n_connection *conn)
 
S2N_API int s2n_async_pkey_op_free (struct s2n_async_pkey_op *op)
 
S2N_API int s2n_config_set_async_pkey_validation_mode (struct s2n_config *config, s2n_async_pkey_validation_mode mode)
 
S2N_API int s2n_async_pkey_op_get_op_type (struct s2n_async_pkey_op *op, s2n_async_pkey_op_type *type)
 
S2N_API int s2n_async_pkey_op_get_input_size (struct s2n_async_pkey_op *op, uint32_t *data_len)
 
S2N_API int s2n_async_pkey_op_get_input (struct s2n_async_pkey_op *op, uint8_t *data, uint32_t data_len)
 
S2N_API int s2n_async_pkey_op_set_output (struct s2n_async_pkey_op *op, const uint8_t *data, uint32_t data_len)
 
S2N_API int s2n_config_set_key_log_cb (struct s2n_config *config, s2n_key_log_fn callback, void *ctx)
 
S2N_API int s2n_config_enable_cert_req_dss_legacy_compat (struct s2n_config *config)
 
S2N_API int s2n_config_set_server_max_early_data_size (struct s2n_config *config, uint32_t max_early_data_size)
 
S2N_API int s2n_connection_set_server_max_early_data_size (struct s2n_connection *conn, uint32_t max_early_data_size)
 
S2N_API int s2n_connection_set_server_early_data_context (struct s2n_connection *conn, const uint8_t *context, uint16_t context_size)
 
S2N_API int s2n_psk_configure_early_data (struct s2n_psk *psk, uint32_t max_early_data_size, uint8_t cipher_suite_first_byte, uint8_t cipher_suite_second_byte)
 
S2N_API int s2n_psk_set_application_protocol (struct s2n_psk *psk, const uint8_t *application_protocol, uint8_t size)
 
S2N_API int s2n_psk_set_early_data_context (struct s2n_psk *psk, const uint8_t *context, uint16_t size)
 
S2N_API int s2n_connection_get_early_data_status (struct s2n_connection *conn, s2n_early_data_status_t *status)
 
S2N_API int s2n_connection_get_remaining_early_data_size (struct s2n_connection *conn, uint32_t *allowed_early_data_size)
 
S2N_API int s2n_connection_get_max_early_data_size (struct s2n_connection *conn, uint32_t *max_early_data_size)
 
S2N_API int s2n_send_early_data (struct s2n_connection *conn, const uint8_t *data, ssize_t data_len, ssize_t *data_sent, s2n_blocked_status *blocked)
 
S2N_API int s2n_recv_early_data (struct s2n_connection *conn, uint8_t *data, ssize_t max_data_len, ssize_t *data_received, s2n_blocked_status *blocked)
 
S2N_API int s2n_config_set_early_data_cb (struct s2n_config *config, s2n_early_data_cb cb)
 
S2N_API int s2n_offered_early_data_get_context_length (struct s2n_offered_early_data *early_data, uint16_t *context_len)
 
S2N_API int s2n_offered_early_data_get_context (struct s2n_offered_early_data *early_data, uint8_t *context, uint16_t max_len)
 
S2N_API int s2n_offered_early_data_reject (struct s2n_offered_early_data *early_data)
 
S2N_API int s2n_offered_early_data_accept (struct s2n_offered_early_data *early_data)
 
S2N_API int s2n_config_get_supported_groups (struct s2n_config *config, uint16_t *groups, uint16_t groups_count_max, uint16_t *groups_count)
 
S2N_API int s2n_config_set_serialization_version (struct s2n_config *config, s2n_serialization_version version)
 
S2N_API int s2n_connection_serialization_length (struct s2n_connection *conn, uint32_t *length)
 
S2N_API int s2n_connection_serialize (struct s2n_connection *conn, uint8_t *buffer, uint32_t buffer_length)
 
S2N_API int s2n_connection_deserialize (struct s2n_connection *conn, uint8_t *buffer, uint32_t buffer_length)
 
S2N_API int s2n_config_set_cert_authorities_from_trust_store (struct s2n_config *config)
 

Variables

S2N_API __thread int s2n_errno
 

Detailed Description

s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to be simple, small, fast, and with security as a priority.
It is released and licensed under the Apache License 2.0.

Macro Definition Documentation

◆ S2N_API

#define S2N_API

Marks a function as belonging to the public s2n API.

◆ S2N_CALLBACK_BLOCKED

#define S2N_CALLBACK_BLOCKED   -2

Callback return code

◆ S2N_FAILURE

#define S2N_FAILURE   -1

Function return code

◆ S2N_MAXIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION

#define S2N_MAXIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION   3

s2n maximum supported TLS record major version

◆ S2N_MINIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION

#define S2N_MINIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION   2

s2n minimum supported TLS record major version

◆ S2N_SSLv2

#define S2N_SSLv2   20

s2n SSL 2.0 Version Constant

◆ S2N_SSLv3

#define S2N_SSLv3   30

s2n SSL 3.0 Version Constant

◆ S2N_SUCCESS

#define S2N_SUCCESS   0

Function return code

◆ S2N_TLS10

#define S2N_TLS10   31

s2n TLS 1.0 Version Constant

◆ S2N_TLS11

#define S2N_TLS11   32

s2n TLS 1.1 Version Constant

◆ S2N_TLS12

#define S2N_TLS12   33

s2n TLS 1.2 Version Constant

◆ S2N_TLS13

#define S2N_TLS13   34

s2n TLS 1.3 Version Constant

◆ S2N_UNKNOWN_PROTOCOL_VERSION

#define S2N_UNKNOWN_PROTOCOL_VERSION   0

s2n Unknown TLS Version

Typedef Documentation

◆ s2n_async_pkey_fn

typedef int(* s2n_async_pkey_fn) (struct s2n_connection *conn, struct s2n_async_pkey_op *op)

Callback function for handling private key operations

Invoked every time an operation requiring the private key is encountered during the handshake.

Safety

  • op is owned by the application and MUST be freed.
Parameters
connConnection which triggered the callback
opAn opaque object representing the private key operation

◆ s2n_cache_delete_callback

typedef int(* s2n_cache_delete_callback) (struct s2n_connection *conn, void *, const void *key, uint64_t key_size)

Cache callback function that allows the caller to set a callback function that will be used to delete SSL session data from a cache.

The callback function takes four arguments: a pointer to s2n_connection object, a pointer to arbitrary data for use within the callback, a pointer to a key which can be used to delete the cached entry, and a 64 bit unsigned integer specifying the size of this key.

◆ s2n_cache_retrieve_callback

typedef int(* s2n_cache_retrieve_callback) (struct s2n_connection *conn, void *, const void *key, uint64_t key_size, void *value, uint64_t *value_size)

Cache callback function that allows the caller to retrieve SSL session data from a cache.

The callback function takes six arguments: a pointer to the s2n_connection object, a pointer to arbitrary data for use within the callback, a pointer to a key which can be used to retrieve the cached entry, a 64 bit unsigned integer specifying the size of this key, a pointer to a memory location where the value should be stored, and a pointer to a 64 bit unsigned integer specifying the size of this value.

Initially *value_size will be set to the amount of space allocated for the value, the callback should set *value_size to the actual size of the data returned. If there is insufficient space, -1 should be returned. If the cache is not ready to provide data for the request, S2N_CALLBACK_BLOCKED should be returned.

This will cause s2n_negotiate() to return S2N_BLOCKED_ON_APPLICATION_INPUT.

◆ s2n_cache_store_callback

typedef int(* s2n_cache_store_callback) (struct s2n_connection *conn, void *, uint64_t ttl_in_seconds, const void *key, uint64_t key_size, const void *value, uint64_t value_size)

Cache callback function that allows the caller to store SSL session data in a cache.

The callback function takes seven arguments: a pointer to the s2n_connection object, a pointer to arbitrary data for use within the callback, a 64-bit unsigned integer specifying the number of seconds the session data may be stored for, a pointer to a key which can be used to retrieve the cached entry, a 64 bit unsigned integer specifying the size of this key, a pointer to a value which should be stored, and a 64 bit unsigned integer specified the size of this value.

◆ s2n_cert_private_key

typedef struct s2n_pkey s2n_cert_private_key

Opaque private key type.

◆ s2n_cert_public_key

typedef struct s2n_pkey s2n_cert_public_key

Opaque public key type.

◆ s2n_cert_tiebreak_callback

typedef struct s2n_cert_chain_and_key *(* s2n_cert_tiebreak_callback) (struct s2n_cert_chain_and_key *cert1, struct s2n_cert_chain_and_key *cert2, uint8_t *name, uint32_t name_len)

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.

Currently, the only builtin resolution for domain name conflicts is certificate type(RSA, ECDSA, etc). The callback should return a pointer to the s2n_cert_chain_and_key that should be used for dns name name.

If NULL is returned, the first certificate will be used. Typically an application will use properties like trust and expiry to implement tiebreaking.

◆ s2n_client_hello_fn

typedef int s2n_client_hello_fn(struct s2n_connection *conn, void *ctx)

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.

◆ s2n_clock_time_nanoseconds

typedef int(* s2n_clock_time_nanoseconds) (void *, uint64_t *)

Callback function type used to get the system time.

Parameters
void*A pointer to arbitrary data for use within the callback
uint64_t*A pointer that the callback will set to the time in nanoseconds The function should return 0 on success and -1 on failure.

◆ s2n_early_data_cb

typedef int(* s2n_early_data_cb) (struct s2n_connection *conn, struct s2n_offered_early_data *early_data)

A callback which can be implemented to accept or reject early data.

This callback is triggered only after the server has determined early data is otherwise acceptable according to the TLS early data specification. Implementations therefore only need to cover application-specific checks, not the standard TLS early data validation.

This callback can be synchronous or asynchronous. For asynchronous behavior, return success without calling s2n_offered_early_data_reject or s2n_offered_early_data_accept. early_data will still be a valid reference, and the connection will block until s2n_offered_early_data_reject or s2n_offered_early_data_accept is called.

Parameters
connA pointer to the connection
early_dataA pointer which can be used to access information about the proposed early data and then accept or reject it.
Returns
A POSIX error signal. If unsuccessful, the connection will be closed with an error.

◆ s2n_key_log_fn

typedef int(* s2n_key_log_fn) (void *ctx, struct s2n_connection *conn, uint8_t *logline, size_t len)

Callback function for handling key log events

THIS SHOULD BE USED FOR DEBUGGING PURPOSES ONLY!

Each log line is formatted with the NSS Key Log Format without a newline.

Safety

  • ctx MUST be cast into the same type of pointer that was originally created
  • logline bytes MUST be copied or discarded before this function returns
Parameters
ctxContext for the callback
connConnection for which the log line is being emitted
loglinePointer to the log line data
lenLength of the log line data

◆ s2n_mem_cleanup_callback

typedef int(* s2n_mem_cleanup_callback) (void)

Will be called when s2n_cleanup is executed.

◆ s2n_mem_free_callback

typedef int(* s2n_mem_free_callback) (void *ptr, uint32_t size)

Frees memory allocated by s2n_mem_malloc_callback.

◆ s2n_mem_init_callback

typedef int(* s2n_mem_init_callback) (void)

Called when s2n_init is executed.

◆ s2n_mem_malloc_callback

typedef int(* s2n_mem_malloc_callback) (void **ptr, uint32_t requested, uint32_t *allocated)

A function that can allocate at least requested bytes of memory.

It stores the location of that memory in ***ptr** and the size of the allocated data in ***allocated**. The function may choose to allocate more memory than was requested. s2n-tls will consider all allocated memory available for use, and will attempt to free all allocated memory when able.

◆ s2n_psk_selection_callback

typedef int(* s2n_psk_selection_callback) (struct s2n_connection *conn, void *context, struct s2n_offered_psk_list *psk_list)

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.

Safety

context is a void pointer and the caller is responsible for ensuring it is cast to the correct type. After the completion of this callback, the pointer to psk_list is invalid.

Parameters
connA pointer to the s2n_connection object.
contextA pointer to a context for the caller to pass state to the callback, if needed.
psk_listA pointer to the offered PSK list being read.

◆ s2n_rand_cleanup_callback

typedef int(* s2n_rand_cleanup_callback) (void)

A callback function that will be called when s2n_cleanup is executed.

◆ s2n_rand_init_callback

typedef int(* s2n_rand_init_callback) (void)

A callback function that will be called when s2n-tls is initialized.

◆ s2n_rand_mix_callback

typedef int(* s2n_rand_mix_callback) (void *data, uint32_t size)

A callback function that will be used to mix in entropy every time the RNG is invoked.

◆ s2n_rand_seed_callback

typedef int(* s2n_rand_seed_callback) (void *data, uint32_t size)

A callback function that will be used to provide entropy to the s2n-tls random number generators.

◆ s2n_recv_fn

typedef int s2n_recv_fn(void *io_context, uint8_t *buf, uint32_t len)

Function pointer for a user provided send callback.

◆ s2n_send_fn

typedef int s2n_send_fn(void *io_context, const uint8_t *buf, uint32_t len)

Function pointer for a user provided send callback.

◆ s2n_session_ticket_fn

typedef int(* s2n_session_ticket_fn) (struct s2n_connection *conn, void *ctx, struct s2n_session_ticket *ticket)

Callback function for receiving a session ticket.

This function will be called each time a session ticket is received, which may be multiple times for TLS1.3.

Safety

ctx is a void pointer and the caller is responsible for ensuring it is cast to the correct type. ticket is valid only within the scope of this callback.

Parameters
connA pointer to the connection object.
ctxContext for the session ticket callback function.
ticketPointer to the received session ticket object.

◆ s2n_verify_host_fn

typedef uint8_t(* s2n_verify_host_fn) (const char *host_name, size_t host_name_len, void *data)

A callback function invoked (usually multiple times) during X.509 validation for each name encountered in the leaf certificate.

Return 1 to trust that hostname or 0 to not trust the hostname.

If this function returns 1, then the certificate is considered trusted and that portion of the X.509 validation will succeed.

If no hostname results in a 1 being returned, the certificate will be untrusted and the validation will terminate immediately.

Data is a opaque user context set in s2n_config_set_verify_host_callback() or s2n_connection_set_verify_host_callback().

Enumeration Type Documentation

◆ s2n_alert_behavior

Sets whether or not a connection should terminate on receiving a WARNING alert from its peer.

alert_behavior can take the following values:

  • S2N_ALERT_FAIL_ON_WARNINGS default behavior: s2n-tls will terminate the connection if its peer sends a WARNING alert.
  • S2N_ALERT_IGNORE_WARNINGS - with the exception of close_notify s2n-tls will ignore all WARNING alerts and keep communicating with its peer. This setting is ignored in TLS1.3
Note
TLS1.3 terminates a connection for all alerts except user_canceled.
Warning
S2N_ALERT_FAIL_ON_WARNINGS is the recommended behavior. Past TLS protocol vulnerabilities have involved downgrading alerts to warnings.

◆ s2n_async_pkey_op_type

The type of private key operation

◆ s2n_async_pkey_validation_mode

Sets whether or not a connection should enforce strict signature validation during the s2n_async_pkey_op_apply call.

mode can take the following values:

  • S2N_ASYNC_PKEY_VALIDATION_FAST - default behavior: s2n-tls will perform only the minimum validation required for safe use of the asyn pkey operation.
  • S2N_ASYNC_PKEY_VALIDATION_STRICT - in addition to the previous checks, s2n-tls will also ensure that the signature created as a result of the async private key sign operation matches the public key on the connection.

◆ s2n_blinding

Used to opt-out of s2n-tls's built-in blinding. Blinding is a mitigation against timing side-channels which in some cases can leak information about encrypted data. By default s2n-tls will cause a thread to sleep between 10 and 30 seconds whenever tampering is detected.

Setting the S2N_SELF_SERVICE_BLINDING option with s2n_connection_set_blinding() turns off this behavior. This is useful for applications that are handling many connections in a single thread. In that case, if s2n_recv() or s2n_negotiate() return an error, self-service applications should call s2n_connection_get_delay() and pause activity on the connection for the specified number of nanoseconds before calling close() or shutdown().

◆ s2n_blocked_status

Used in non-blocking mode to indicate in which direction s2n-tls became blocked on I/O before it returned control to the caller. This allows an application to avoid retrying s2n-tls operations until I/O is possible in that direction.

◆ s2n_cert_auth_type

Used to declare what type of client certificate authentication to use.

A s2n_connection will enforce client certificate authentication (mTLS) differently based on the s2n_cert_auth_type and s2n_mode (client/server) of the connection, as described below.

Server behavior:

  • None (default): Will not request client authentication.
  • Optional: Request the client's certificate and validate it. If no certificate is received then no validation is performed.
  • Required: Request the client's certificate and validate it. Abort the handshake if a client certificate is not received.

Client behavior:

  • None: Abort the handshake if the server requests client authentication.
  • Optional (default): Sends the client certificate if the server requests client authentication. No certificate is sent if the application hasn't provided a certificate.
  • Required: Send the client certificate. Abort the handshake if the server doesn't request client authentication or if the application hasn't provided a certificate.

◆ s2n_client_hello_cb_mode

Client Hello callback modes

  • S2N_CLIENT_HELLO_CB_BLOCKING (default):
    • In this mode s2n-tls expects the callback to complete its work and return the appropriate response code before the handshake continues. If any of the connection properties were changed based on the server_name extension the callback must either return a value greater than 0 or invoke s2n_connection_server_name_extension_used, otherwise the callback returns 0 to continue the handshake.
  • S2N_CLIENT_HELLO_CB_NONBLOCKING:
    • In non-blocking mode, s2n-tls expects the callback to not complete its work. If the callback returns a response code of 0, s2n-tls will return S2N_FAILURE with S2N_ERR_T_BLOCKED error type and s2n_blocked_status set to S2N_BLOCKED_ON_APPLICATION_INPUT. The handshake is paused and further calls to s2n_negotiate will continue to return the same error until s2n_client_hello_cb_done is invoked for the s2n_connection to resume the handshake. If any of the connection properties were changed on the basis of the server_name extension then s2n_connection_server_name_extension_used must be invoked before marking the callback done.

◆ s2n_ct_support_level

Enum to set Certificate Transparency Support level.

◆ s2n_early_data_status_t

The status of early data on a connection.

S2N_EARLY_DATA_STATUS_OK: Early data is in progress. S2N_EARLY_DATA_STATUS_NOT_REQUESTED: The client did not request early data, so none was sent or received. S2N_EARLY_DATA_STATUS_REJECTED: The client requested early data, but the server rejected the request. Early data may have been sent, but was not received. S2N_EARLY_DATA_STATUS_END: All early data was successfully sent and received.

◆ s2n_error_type

Used to help applications determine why an s2n-tls function failed.

This enum is optimized for use in C switch statements. Each value in the enum represents an error "category".

s2n-tls organizes errors into different "types" to allow applications to handle error values without catching all possibilities. Applications using non-blocking I/O should check the error type to determine if the I/O operation failed because it would block or for some other error. To retrieve the type for a given error use s2n_error_get_type(). Applications should perform any error handling logic using these high level types.

See the Error Handling section for how the errors should be interpreted.

Enumerator
S2N_ERR_T_OK 

No error

S2N_ERR_T_IO 

Underlying I/O operation failed, check system errno

S2N_ERR_T_CLOSED 

EOF

S2N_ERR_T_BLOCKED 

Underlying I/O operation would block

S2N_ERR_T_ALERT 

Incoming Alert

S2N_ERR_T_PROTO 

Failure in some part of the TLS protocol. Ex: CBC verification failure

S2N_ERR_T_INTERNAL 

Error internal to s2n-tls. A precondition could have failed.

S2N_ERR_T_USAGE 

User input error. Ex: Providing an invalid cipher preference version

◆ s2n_max_frag_len

◆ s2n_mode

enum s2n_mode

Used to declare connections as server or client type, respectively.

◆ s2n_peer_key_update

Used to indicate the type of key update that is being requested. For further information refer to s2n_connection_request_key_update.

◆ s2n_psk_hmac

Pre-shared key (PSK) Hash Algorithm - RFC 8446 Section-2.2

◆ s2n_psk_mode

The list of PSK modes supported by s2n-tls for TLS versions >= TLS1.3. Currently s2n-tls supports two modes - S2N_PSK_MODE_RESUMPTION, which represents the PSKs established using the previous connection via session resumption, and S2N_PSK_MODE_EXTERNAL, which represents PSKs established out-of-band/externally using a secure mutually agreed upon mechanism.

◆ s2n_status_request_type

Enum used to define the type, if any, of certificate status request a connection should make during the handshake. The only supported status request type is OCSP, S2N_STATUS_REQUEST_OCSP.

◆ s2n_tls_extension_type

TLS extensions supported by s2n-tls

◆ s2n_tls_hash_algorithm

◆ s2n_tls_signature_algorithm

Function Documentation

◆ s2n_async_pkey_op_apply()

S2N_API int s2n_async_pkey_op_apply ( struct s2n_async_pkey_op *  op,
struct s2n_connection *  conn 
)

Finalizes a private key operation and unblocks the connection.

Safety

  • conn must match the connection that originally triggered the callback.
  • Must be called after the operation is performed.
  • Can only be called once. Any subsequent calls will produce a S2N_ERR_T_USAGE error.
  • Safe to call from inside s2n_async_pkey_fn
  • Safe to call from a different thread, as long as no other thread is operating on op.
Parameters
opAn opaque object representing the private key operation
connThe connection associated with the operation that should be unblocked

◆ s2n_async_pkey_op_free()

S2N_API int s2n_async_pkey_op_free ( struct s2n_async_pkey_op *  op)

Frees the opaque structure representing a private key operation.

Safety

  • MUST be called for every operation passed to s2n_async_pkey_fn
  • Safe to call before or after the connection that created the operation is freed
Parameters
opAn opaque object representing the private key operation

◆ s2n_async_pkey_op_get_input()

S2N_API int s2n_async_pkey_op_get_input ( struct s2n_async_pkey_op *  op,
uint8_t *  data,
uint32_t  data_len 
)

Returns the input to the private key operation.

When signing, the input is the digest to sign. When decrypting, the input is the data to decrypt.

Safety

  • data must be sufficiently large to contain the input. s2n_async_pkey_op_get_input_size can be called to determine how much memory is required.
  • s2n-tls does not take ownership of data. The application still owns the memory and must free it if necessary.
Parameters
opAn opaque object representing the private key operation
dataA pointer to a buffer to copy the input into
data_lenThe maximum size of the data buffer

◆ s2n_async_pkey_op_get_input_size()

S2N_API int s2n_async_pkey_op_get_input_size ( struct s2n_async_pkey_op *  op,
uint32_t *  data_len 
)

Returns the size of the input to the private key operation.

Parameters
opAn opaque object representing the private key operation
data_lenA pointer to be set to the size

◆ s2n_async_pkey_op_get_op_type()

S2N_API int s2n_async_pkey_op_get_op_type ( struct s2n_async_pkey_op *  op,
s2n_async_pkey_op_type type 
)

Returns the type of the private key operation.

Parameters
opAn opaque object representing the private key operation
typeA pointer to be set to the type

◆ s2n_async_pkey_op_perform()

S2N_API int s2n_async_pkey_op_perform ( struct s2n_async_pkey_op *  op,
s2n_cert_private_key key 
)

Performs a private key operation using the given private key.

Safety

  • Can only be called once. Any subsequent calls will produce a S2N_ERR_T_USAGE error.
  • Safe to call from inside s2n_async_pkey_fn
  • Safe to call from a different thread, as long as no other thread is operating on op.
Parameters
opAn opaque object representing the private key operation
keyThe private key used for the operation. It can be extracted from conn through the s2n_connection_get_selected_cert and s2n_cert_chain_and_key_get_private_key calls

◆ s2n_async_pkey_op_set_output()

S2N_API int s2n_async_pkey_op_set_output ( struct s2n_async_pkey_op *  op,
const uint8_t *  data,
uint32_t  data_len 
)

Sets the output of the private key operation.

Safety

  • s2n-tls does not take ownership of data. The application still owns the memory and must free it if necessary.
Parameters
opAn opaque object representing the private key operation
dataA pointer to a buffer containing the output
data_lenThe size of the data buffer

◆ s2n_calculate_stacktrace()

S2N_API int s2n_calculate_stacktrace ( void  )

Calculates the s2n stack trace.

Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_and_key_free()

S2N_API int s2n_cert_chain_and_key_free ( struct s2n_cert_chain_and_key *  cert_and_key)

Frees the memory associated with an s2n_cert_chain_and_key object.

Parameters
cert_and_keyThe certificate chain and private key handle
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_and_key_get_ctx()

S2N_API void * s2n_cert_chain_and_key_get_ctx ( struct s2n_cert_chain_and_key *  cert_and_key)

Get the user supplied context from the s2n_cert_chain_and_key object.

Parameters
cert_and_keyThe certificate chain and private key handle
Returns
The user supplied pointer from s2n_cert_chain_and_key_set_ctx()

◆ s2n_cert_chain_and_key_get_private_key()

S2N_API s2n_cert_private_key * s2n_cert_chain_and_key_get_private_key ( struct s2n_cert_chain_and_key *  cert_and_key)

Get the private key from the s2n_cert_chain_and_key object.

Parameters
cert_and_keyThe certificate chain and private key handle
Returns
A pointer to the s2n_cert_private_key

◆ s2n_cert_chain_and_key_load_pem()

S2N_API int s2n_cert_chain_and_key_load_pem ( struct s2n_cert_chain_and_key *  chain_and_key,
const char *  chain_pem,
const char *  private_key_pem 
)

Associates a certificate chain and private key with an s2n_cert_chain_and_key object.

cert_chain_pem should be a PEM encoded certificate chain, with the first certificate in the chain being your leaf certificate. private_key_pem should be a PEM encoded private key corresponding to the leaf certificate.

Note
Prefer using s2n_cert_chain_and_key_load_pem_bytes.
Parameters
chain_and_keyThe certificate chain and private key handle
chain_pemA byte array of a PEM encoded certificate chain.
private_key_pemA byte array of a PEM encoded key.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_and_key_load_pem_bytes()

S2N_API int s2n_cert_chain_and_key_load_pem_bytes ( struct s2n_cert_chain_and_key *  chain_and_key,
uint8_t *  chain_pem,
uint32_t  chain_pem_len,
uint8_t *  private_key_pem,
uint32_t  private_key_pem_len 
)

Associates a certificate chain and private key with an s2n_cert_chain_and_key object.

cert_chain_pem should be a PEM encoded certificate chain, with the first certificate in the chain being your leaf certificate. private_key_pem should be a PEM encoded private key corresponding to the leaf certificate.

Parameters
chain_and_keyThe certificate chain and private key handle
chain_pemA byte array of a PEM encoded certificate chain.
chain_pem_lenSize of chain_pem
private_key_pemA byte array of a PEM encoded key.
private_key_pem_lenSize of private_key_pem
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_and_key_load_public_pem_bytes()

S2N_API int s2n_cert_chain_and_key_load_public_pem_bytes ( struct s2n_cert_chain_and_key *  chain_and_key,
uint8_t *  chain_pem,
uint32_t  chain_pem_len 
)

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.

Parameters
chain_and_keyThe certificate chain and private key handle
chain_pemA byte array of a PEM encoded certificate chain.
chain_pem_lenSize of chain_pem
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_and_key_new()

S2N_API struct s2n_cert_chain_and_key * s2n_cert_chain_and_key_new ( void  )

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.

Returns
A new object used to represent a certificate-chain/key pair

◆ s2n_cert_chain_and_key_set_ctx()

S2N_API int s2n_cert_chain_and_key_set_ctx ( struct s2n_cert_chain_and_key *  cert_and_key,
void *  ctx 
)

Adds a context to the s2n_cert_chain_and_key object.

Parameters
cert_and_keyThe certificate chain and private key handle
ctxAn opaque pointer to user supplied data.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_and_key_set_ocsp_data()

S2N_API int s2n_cert_chain_and_key_set_ocsp_data ( struct s2n_cert_chain_and_key *  chain_and_key,
const uint8_t *  data,
uint32_t  length 
)

Set the raw OCSP stapling data for a certificate chain.

Parameters
chain_and_keyThe certificate chain handle
dataA pointer to the raw OCSP stapling data bytes. The data will be copied.
lengthThe length of the data bytes.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_and_key_set_sct_list()

S2N_API int s2n_cert_chain_and_key_set_sct_list ( struct s2n_cert_chain_and_key *  chain_and_key,
const uint8_t *  data,
uint32_t  length 
)

Set the signed certificate timestamp (SCT) for a certificate chain. This is used for Certificate Transparency.

Parameters
chain_and_keyThe certificate chain handle
dataA pointer to the SCT data. The data will be copied.
lengthThe length of the data bytes.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_cert_chain_get_cert()

S2N_API int s2n_cert_chain_get_cert ( const struct s2n_cert_chain_and_key *  chain_and_key,
struct s2n_cert **  out_cert,
const uint32_t  cert_idx 
)

Returns the certificate out_cert present at the index cert_idx of the certificate chain chain_and_key.

Note that the index of the leaf certificate is zero. If the certificate chain chain_and_key is NULL or the certificate index value is not in the acceptable range for the input certificate chain, an error is returned.

Safety

There is no memory allocation required for out_cert buffer prior to calling the s2n_cert_chain_get_cert API. The out_cert will contain the pointer to the s2n_cert initialized within the input s2n_cert_chain_and_key chain_and_key. The pointer to the output s2n certificate out_cert is valid until chain_and_key is freed up. If a caller wishes to persist the out_cert beyond the lifetime of chain_and_key, the contents would need to be copied prior to freeing chain_and_key.

Parameters
chain_and_keyA pointer to the s2n_cert_chain_and_key object being read.
out_certA pointer to the output s2n_cert out_cert present at the index cert_idx of the certificate chain chain_and_key.
cert_idxThe certificate index for the requested certificate within the s2n certificate chain.

◆ s2n_cert_chain_get_length()

S2N_API int s2n_cert_chain_get_length ( const struct s2n_cert_chain_and_key *  chain_and_key,
uint32_t *  cert_length 
)
Parameters
chain_and_keyA pointer to the s2n_cert_chain_and_key object being read.
cert_lengthThis return value represents the length of the s2n certificate chain chain_and_key.
Returns
the length of the s2n certificate chain chain_and_key.

◆ s2n_cert_get_der()

S2N_API int s2n_cert_get_der ( const struct s2n_cert *  cert,
const uint8_t **  out_cert_der,
uint32_t *  cert_length 
)

Returns the s2n certificate in DER format along with its length.

The API gets the s2n certificate cert in DER format. The certificate is returned in the out_cert_der buffer. Here, cert_len represents the length of the certificate.

A caller can use certificate parsing tools such as the ones provided by OpenSSL to parse the DER encoded certificate chain returned.

Safety

The memory for the out_cert_der buffer is allocated and owned by s2n-tls. Since the size of the certificate can potentially be very large, a pointer to internal connection data is returned instead of copying the contents into a caller-provided buffer.

The pointer to the output buffer out_cert_der is valid only while the connection exists. The s2n_connection_free API frees the memory associated with the out_cert_der buffer and after the s2n_connection_wipe API is called the memory pointed by out_cert_der is invalid.

If a caller wishes to persist the out_cert_der beyond the lifetime of the connection, the contents would need to be copied prior to the connection termination.

Parameters
certA pointer to the s2n_cert object being read.
out_cert_derA pointer to the output buffer which will hold the s2n certificate cert in DER format.
cert_lengthThis return value represents the length of the certificate.

◆ s2n_cert_get_utf8_string_from_extension_data()

S2N_API int s2n_cert_get_utf8_string_from_extension_data ( const uint8_t *  extension_data,
uint32_t  extension_len,
uint8_t *  out_data,
uint32_t *  out_len 
)

Returns the UTF8 String representation of the DER encoded ASN.1 X.509 certificate extension data.

Parameters
extension_dataA pointer to the DER encoded ASN.1 X.509 certificate extension value being read.
extension_lenrepresents the length of the input buffer extension_data.
out_dataA pointer to the output buffer which will hold the UTF8 String representation of the DER encoded ASN.1 X.509 certificate extension data returned.
out_lenThis value is both an input and output parameter and represents the length of the output buffer out_data. When used as an input parameter, the caller must use this parameter to convey the maximum length of out_data. When used as an output parameter, out_len holds the actual length of UTF8 String returned.

◆ s2n_cert_get_utf8_string_from_extension_data_length()

S2N_API int s2n_cert_get_utf8_string_from_extension_data_length ( const uint8_t *  extension_data,
uint32_t  extension_len,
uint32_t *  utf8_str_len 
)

Returns the UTF8 String length of the ASN.1 X.509 certificate extension data.

Parameters
extension_dataA pointer to the DER encoded ASN.1 X.509 certificate extension value being read.
extension_lenrepresents the length of the input buffer extension_data.
utf8_str_lenThis return value contains the UTF8 String length of the ASN.1 X.509 certificate extension data.

◆ s2n_cert_get_x509_extension_value()

S2N_API int s2n_cert_get_x509_extension_value ( struct s2n_cert *  cert,
const uint8_t *  oid,
uint8_t *  ext_value,
uint32_t *  ext_value_len,
bool *  critical 
)

Returns the DER encoding of an ASN.1 X.509 certificate extension value, it's length and a boolean critical.

Parameters
certA pointer to the s2n_cert object being read.
oidA null-terminated cstring that contains the OID of the X.509 certificate extension to be read.
ext_valueA pointer to the output buffer which will hold the DER encoding of an ASN.1 X.509 certificate extension value returned.
ext_value_lenThis value is both an input and output parameter and represents the length of the output buffer ext_value. When used as an input parameter, the caller must use this parameter to convey the maximum length of ext_value. When used as an output parameter, ext_value_len holds the actual length of the DER encoding of the ASN.1 X.509 certificate extension value returned.
criticalThis return value contains the boolean value for critical.

◆ s2n_cert_get_x509_extension_value_length()

S2N_API int s2n_cert_get_x509_extension_value_length ( struct s2n_cert *  cert,
const uint8_t *  oid,
uint32_t *  ext_value_len 
)

Returns the length of the DER encoded extension value of the ASN.1 X.509 certificate extension.

Parameters
certA pointer to the s2n_cert object being read.
oidA null-terminated cstring that contains the OID of the X.509 certificate extension to be read.
ext_value_lenThis return value contains the length of DER encoded extension value of the ASN.1 X.509 certificate extension.

◆ s2n_cleanup()

S2N_API int s2n_cleanup ( void  )

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.

Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_client_hello_cb_done()

S2N_API int s2n_client_hello_cb_done ( struct s2n_connection *  conn)

Marks the non-blocking callback as complete. Can be invoked from within the callback when operating in non-blocking mode to continue the handshake.

Parameters
connThe connection object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_client_hello_free()

S2N_API int s2n_client_hello_free ( struct s2n_client_hello **  ch)

Frees an s2n_client_hello structure.

This method should be called to free s2n_client_hellos returned by s2n_client_hello_parse_message. It will error if passed an s2n_client_hello returned by s2n_connection_get_client_hello and owned by the connection.

Parameters
chThe structure to be freed.
Returns
S2N_SUCCESS on success, S2N_FAILURE on failure.

◆ s2n_client_hello_get_cipher_suites()

S2N_API ssize_t s2n_client_hello_get_cipher_suites ( struct s2n_client_hello *  ch,
uint8_t *  out,
uint32_t  max_length 
)

Copies into the out buffer max_length bytes of the cipher_suites on the ClientHello.

Note: SSLv2 ClientHello cipher suites follow a different structure than modern ClientHello messages. See RFC5246. To determine whether a ClientHello is an SSLv2 ClientHello, you will need to use s2n_connection_get_client_hello_version().

Parameters
chThe Client Hello handle
outThe destination buffer for the raw Client Hello cipher suites
max_lengthThe size of out in bytes
Returns
The number of copied bytes

◆ s2n_client_hello_get_cipher_suites_length()

S2N_API ssize_t s2n_client_hello_get_cipher_suites_length ( struct s2n_client_hello *  ch)

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

Parameters
chThe Client Hello handle
Returns
the number of bytes the cipher_suites takes on the ClientHello message received by the server

◆ s2n_client_hello_get_compression_methods()

S2N_API int s2n_client_hello_get_compression_methods ( struct s2n_client_hello *  ch,
uint8_t *  list,
uint32_t  list_length,
uint32_t *  out_length 
)

Retrieves the list of compression methods sent in the Client Hello.

Use s2n_client_hello_get_compression_methods_length() to retrieve how much memory should be allocated for the buffer in advance.

Note
Compression methods were removed in TLS1.3 and therefore the only valid value in this list is the "null" compression method when TLS1.3 is negotiated.
s2n-tls has never supported compression methods in any TLS version and therefore a compression method will never be negotiated or used.
Parameters
chA pointer to the Client Hello
listA pointer to some memory that s2n will write the compression methods to. This memory MUST be the size of list_length
list_lengthThe size of list.
out_lengthAn out pointer. s2n will set its value to the size of the compression methods list in bytes.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_client_hello_get_compression_methods_length()

S2N_API int s2n_client_hello_get_compression_methods_length ( struct s2n_client_hello *  ch,
uint32_t *  out_length 
)

Get the length of the compression methods list sent in the Client Hello.

Parameters
chA pointer to the Client Hello
out_lengthAn out pointer. Will be set to the length of the compression methods list in bytes.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_client_hello_get_extension_by_id()

S2N_API ssize_t s2n_client_hello_get_extension_by_id ( struct s2n_client_hello *  ch,
s2n_tls_extension_type  extension_type,
uint8_t *  out,
uint32_t  max_length 
)

Copies into the out buffer max_length bytes of a given extension type on the ClientHello

ch is a pointer to the s2n_client_hello of the s2n_connection which can be obtained using s2n_connection_get_client_hello().

Parameters
chA pointer to the Client Hello
extension_typeIndicates the desired extension
outA pointer to the buffer that s2n will write the client session id to. This buffer MUST be the size of max_length
max_lengthThe size of out.
Returns
The number of copied bytes

◆ s2n_client_hello_get_extension_length()

S2N_API ssize_t s2n_client_hello_get_extension_length ( struct s2n_client_hello *  ch,
s2n_tls_extension_type  extension_type 
)

Query the ClientHello message received by the server. Use this function to allocate the out buffer for other client hello extension functions.

Parameters
chA pointer to the Client Hello
extension_typeIndicates the desired extension
Returns
The number of bytes the given extension type takes

◆ s2n_client_hello_get_extensions()

S2N_API ssize_t s2n_client_hello_get_extensions ( struct s2n_client_hello *  ch,
uint8_t *  out,
uint32_t  max_length 
)

Copies into the out buffer max_length bytes of the extensions in the ClientHello.

Parameters
chThe Client Hello handle
outThe destination buffer for the raw Client Hello extensions
max_lengthThe size of out in bytes
Returns
The number of copied bytes

◆ s2n_client_hello_get_extensions_length()

S2N_API ssize_t s2n_client_hello_get_extensions_length ( struct s2n_client_hello *  ch)

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

Parameters
chThe Client Hello handle
Returns
the number of bytes the extensions take in the ClientHello message received by the server

◆ s2n_client_hello_get_legacy_protocol_version()

S2N_API int s2n_client_hello_get_legacy_protocol_version ( struct s2n_client_hello *  ch,
uint8_t *  out 
)

Access the Client Hello protocol version

Note
This field is a legacy field in TLS1.3 and is no longer used to negotiate the protocol version of the connection. It will be set to TLS1.2 even if TLS1.3 is negotiated. Therefore this method should only be used for logging or fingerprinting.
Parameters
chA pointer to the client hello struct
outThe protocol version in the client hello.

◆ s2n_client_hello_get_legacy_record_version()

S2N_API int s2n_client_hello_get_legacy_record_version ( struct s2n_client_hello *  ch,
uint8_t *  out 
)

Access the protocol version from the header of the first record that contained the ClientHello message.

Note
This field has been deprecated and should not be confused with the client hello version. It is often set very low, usually to TLS1.0 for compatibility reasons, and should never be set higher than TLS1.2. Therefore this method should only be used for logging or fingerprinting.
Parameters
connA pointer to the client hello struct
outThe protocol version in the record header containing the Client Hello.

◆ s2n_client_hello_get_raw_message()

S2N_API ssize_t s2n_client_hello_get_raw_message ( struct s2n_client_hello *  ch,
uint8_t *  out,
uint32_t  max_length 
)

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.

Note: SSLv2 ClientHello messages follow a different structure than more modern ClientHello messages. See RFC5246. In addition, due to how s2n-tls parses SSLv2 ClientHellos, the raw message is missing the first three bytes (the msg_type and version) and instead begins with the cipher_specs. To determine whether a ClientHello is an SSLv2 ClientHello, you will need to use s2n_connection_get_client_hello_version(). To get the protocol version advertised in the SSLv2 ClientHello (which may be higher than SSLv2), you will need to use s2n_connection_get_client_protocol_version().

Parameters
chThe Client Hello handle
outThe destination buffer for the raw Client Hello
max_lengthThe size of out in bytes
Returns
The number of copied bytes

◆ s2n_client_hello_get_raw_message_length()

S2N_API ssize_t s2n_client_hello_get_raw_message_length ( struct s2n_client_hello *  ch)

Function to determine the size of the raw Client Hello buffer.

Can be used to determine the necessary size of the out buffer for s2n_client_hello_get_raw_message()

Parameters
chThe Client Hello handle
Returns
The size of the ClientHello message received by the server

◆ s2n_client_hello_get_server_name()

S2N_API int s2n_client_hello_get_server_name ( struct s2n_client_hello *  ch,
uint8_t *  server_name,
uint16_t  length,
uint16_t *  out_length 
)

Gets the first server name in a Client Hello.

Use s2n_client_hello_get_server_name_length() to get the amount of memory needed for the buffer.

Parameters
chA pointer to the ClientHello
server_nameA pointer to the memory which will be populated with the server name
lengthThe maximum amount of data that can be written to server_name
out_lengthA pointer which will be populated with the size of the server name

◆ s2n_client_hello_get_server_name_length()

S2N_API int s2n_client_hello_get_server_name_length ( struct s2n_client_hello *  ch,
uint16_t *  length 
)

Gets the length of the first server name in a Client Hello.

Parameters
chA pointer to the ClientHello
lengthA pointer which will be populated with the length of the server name

◆ s2n_client_hello_get_session_id()

S2N_API int s2n_client_hello_get_session_id ( struct s2n_client_hello *  ch,
uint8_t *  out,
uint32_t *  out_length,
uint32_t  max_length 
)

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.

Retrieve the session id as sent by the client in the ClientHello message. The session id on the s2n_connection may change later when the server sends the ServerHello; see s2n_connection_get_session_id for how to get the final session id used for future session resumption.

Use s2n_client_hello_get_session_id_length() to get the the ClientHello session id length in bytes. ch is a pointer to the s2n_client_hello of the s2n_connection which can be obtained using s2n_connection_get_client_hello().

Parameters
chA pointer to the Client Hello
outA pointer to the buffer that s2n will write the client session id to. This buffer MUST be the size of max_length
out_lengthAn out pointer. s2n will set it's value to the size of the session_id in bytes.
max_lengthThe size of out.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_client_hello_get_session_id_length()

S2N_API int s2n_client_hello_get_session_id_length ( struct s2n_client_hello *  ch,
uint32_t *  out_length 
)

Get the the ClientHello session id length in bytes

ch is a pointer to the s2n_client_hello of the s2n_connection which can be obtained using s2n_connection_get_client_hello().

Parameters
chA pointer to the Client Hello
out_lengthAn out pointer. s2n will set it's value to the size of the session_id in bytes.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_client_hello_get_supported_groups()

S2N_API int s2n_client_hello_get_supported_groups ( struct s2n_client_hello *  ch,
uint16_t *  groups,
uint16_t  groups_count_max,
uint16_t *  groups_count 
)

Retrieves the supported groups received from the client in the supported groups extension.

IANA values for each of the received supported groups are written to the provided groups array, and groups_count is set to the number of received supported groups.

groups_count_max should be set to the maximum capacity of the groups array. If groups_count_max is less than the number of received supported groups, this function will error. To determine how large groups should be in advance, use s2n_client_hello_get_extension_length() with the S2N_EXTENSION_SUPPORTED_GROUPS extension type, and divide the value by 2.

If no supported groups extension was received from the peer, or the received supported groups extension is malformed, this function will error.

Parameters
chA pointer to the ClientHello. Can be retrieved from a connection via s2n_connection_get_client_hello().
groupsThe array to populate with the received supported groups.
groups_count_maxThe maximum number of supported groups that can fit in the groups array.
groups_countReturns the number of received supported groups.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure.

◆ s2n_client_hello_has_extension()

S2N_API int s2n_client_hello_has_extension ( struct s2n_client_hello *  ch,
uint16_t  extension_iana,
bool *  exists 
)

Used to check if a particular extension exists in the client hello.

ch is a pointer to the s2n_client_hello of the s2n_connection which can be obtained using s2n_connection_get_client_hello().

Parameters
chA pointer to the client hello object
extension_ianaThe iana value of the extension
existsA pointer that will be set to whether or not the extension exists

◆ s2n_client_hello_parse_message()

S2N_API struct s2n_client_hello * s2n_client_hello_parse_message ( const uint8_t *  bytes,
uint32_t  size 
)

Creates an s2n_client_hello from bytes representing a ClientHello message.

The input bytes should include the message header (message type and length), but not the record header.

Unlike s2n_connection_get_client_hello, the s2n_client_hello returned by this method is owned by the application and must be freed with s2n_client_hello_free.

This method does not support SSLv2 ClientHellos.

Parameters
bytesThe raw bytes representing the ClientHello.
sizeThe size of raw_message.
Returns
A new s2n_client_hello on success, or NULL on failure.

◆ s2n_config_accept_max_fragment_length()

S2N_API int s2n_config_accept_max_fragment_length ( struct s2n_config *  config)

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

Note
Some TLS implementations do not respect their peer's max fragment length extension.
Parameters
configThe configuration object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_add_cert_chain_and_key()

S2N_API int s2n_config_add_cert_chain_and_key ( struct s2n_config *  config,
const char *  cert_chain_pem,
const char *  private_key_pem 
)

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.

Deprecated:
Use s2n_config_add_cert_chain_and_key_to_store instead.
Parameters
configThe configuration object being updated
cert_chain_pemA byte array of a PEM encoded certificate chain.
private_key_pemA byte array of a PEM encoded key.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure.

◆ s2n_config_add_cert_chain_and_key_to_store()

S2N_API int s2n_config_add_cert_chain_and_key_to_store ( struct s2n_config *  config,
struct s2n_cert_chain_and_key *  cert_key_pair 
)

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

In the case of no certificate matching the client's SNI extension or if no SNI extension was sent by the client, the certificate from the first call to s2n_config_add_cert_chain_and_key_to_store() will be selected. Use s2n_config_set_cert_chain_and_key_defaults() to set different defaults.

Warning
It is not recommended to free or modify the cert_key_pair as any subsequent changes will be reflected in the config.
Parameters
configThe configuration object being updated
cert_key_pairThe certificate chain and private key handle
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_add_dhparams()

S2N_API int s2n_config_add_dhparams ( struct s2n_config *  config,
const char *  dhparams_pem 
)

Associates a set of Diffie-Hellman parameters with an s2n_config object.

Note
dhparams_pem should be PEM encoded DH parameters.
Parameters
configThe configuration object being updated
dhparams_pemA string containing the PEM encoded DH parameters.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_add_pem_to_trust_store()

S2N_API int s2n_config_add_pem_to_trust_store ( struct s2n_config *  config,
const char *  pem 
)

Adds a PEM to the trust store. This will allocate memory, and load pem into the trust store.

When configs are created with s2n_config_new(), the trust store is initialized with default system certificates. To completely override these certificates, call s2n_config_wipe_trust_store() before calling this function.

Note
This API uses the s2n-tls PEM parsing implementation, which is more strict than typical libcrypto implementations such as OpenSSL. An error is returned if any unexpected data is encountered while parsing pem. This allows applications to be made aware of any malformed certificates rather than attempt to negotiate with a partial trust store. However, some PEMs may need to be loaded that are not under control of the application, such as system trust stores. In this case, s2n_config_set_verification_ca_location() may be used, which performs more widely compatible and permissive parsing from the linked libcrypto.
Parameters
configThe configuration object being updated
pemThe string value of the PEM certificate.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_add_ticket_crypto_key()

S2N_API int s2n_config_add_ticket_crypto_key ( struct s2n_config *  config,
const uint8_t *  name,
uint32_t  name_len,
uint8_t *  key,
uint32_t  key_len,
uint64_t  intro_time_in_seconds_from_epoch 
)

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.

Parameters
configThe configuration object being updated
nameName of the session ticket key that should be randomly generated to avoid collisions
name_lenLength of session ticket key name
keyKey used to perform encryption/decryption of session ticket
key_lenLength of the session ticket key
intro_time_in_seconds_from_epochTime at which the session ticket key is introduced. If this is 0, then intro_time_in_seconds_from_epoch is set to now.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_append_protocol_preference()

S2N_API int s2n_config_append_protocol_preference ( struct s2n_config *  config,
const uint8_t *  protocol,
uint8_t  protocol_len 
)

Appends the provided application protocol to the preference list

The data provided in protocol parameter will be copied into an internal buffer

Parameters
configThe configuration object being updated
protocolA pointer to a byte array value
protocol_lenThe length of bytes that should be read from protocol. Note: this value cannot be 0, otherwise an error will be returned.

◆ s2n_config_disable_x509_time_verification()

S2N_API int s2n_config_disable_x509_time_verification ( struct s2n_config *  config)

Disables timestamp validation for received certificates.

By default, s2n-tls checks the notBefore and notAfter fields on the certificates it receives during the handshake. If the current date is not within the range of these fields for any certificate in the chain of trust, s2n_negotiate() will error. This validation is in accordance with RFC 5280, section 6.1.3 a.2: https://datatracker.ietf.org/doc/html/rfc5280#section-6.1.3.

This API will disable this timestamp validation, permitting negotiation with peers that send expired certificates, or certificates that are not yet considered valid.

Warning
Applications calling this API should seriously consider the security implications of disabling this validation. The validity period of a certificate corresponds to the range of time in which the CA is guaranteed to maintain information regarding the certificate's revocation status. As such, it may not be possible to obtain accurate revocation information for certificates with invalid timestamps. Applications disabling this validation MUST implement some external method for limiting certificate lifetime.
Parameters
configThe associated connection config.
Returns
S2N_SUCCESS on success, S2N_FAILURE on failure.

◆ s2n_config_disable_x509_verification()

S2N_API int s2n_config_disable_x509_verification ( struct s2n_config *  config)

Turns off all X.509 validation during the negotiation phase of the connection. This should only be used for testing or debugging purposes.

Parameters
configThe configuration object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_enable_cert_req_dss_legacy_compat()

S2N_API int s2n_config_enable_cert_req_dss_legacy_compat ( struct s2n_config *  config)

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

Parameters
configConfig to enable legacy DSS certificates for

◆ s2n_config_free()

S2N_API int s2n_config_free ( struct s2n_config *  config)

Frees the memory associated with an s2n_config object.

Parameters
configThe configuration object being freed
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_free_cert_chain_and_key()

S2N_API int s2n_config_free_cert_chain_and_key ( struct s2n_config *  config)

Frees the certificate chain and key associated with an s2n_config object.

Parameters
configThe configuration object with DH params being freed
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_free_dhparams()

S2N_API int s2n_config_free_dhparams ( struct s2n_config *  config)

Frees the DH params associated with an s2n_config object.

Parameters
configThe configuration object with DH params being freed
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_get_client_auth_type()

S2N_API int s2n_config_get_client_auth_type ( struct s2n_config *  config,
s2n_cert_auth_type client_auth_type 
)

Gets Client Certificate authentication method the s2n_config object is using.

Parameters
configA pointer to a s2n_config object
client_auth_typeA pointer to a client auth policy. This will be updated to the s2n_config value.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_get_ctx()

S2N_API int s2n_config_get_ctx ( struct s2n_config *  config,
void **  ctx 
)

Gets the user defined context from the s2n_config object. The context is set by calling s2n_config_set_ctx()

Parameters
configThe configuration object being accessed
ctxA pointer to the user defined ctx.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_get_supported_groups()

S2N_API int s2n_config_get_supported_groups ( struct s2n_config *  config,
uint16_t *  groups,
uint16_t  groups_count_max,
uint16_t *  groups_count 
)

Retrieves the list of supported groups configured by the security policy associated with config.

The retrieved list of groups will contain all of the supported groups for a security policy that are compatible with the build of s2n-tls. For instance, PQ kem groups that are not supported by the linked libcrypto will not be written. Otherwise, all of the supported groups configured for the security policy will be written. This API can be used with the s2n_client_hello_get_supported_groups() API as a means of comparing compatibility between a client and server.

IANA values for each of the supported groups are written to the provided groups array, and groups_count is set to the number of written supported groups.

groups_count_max should be set to the maximum capacity of the groups array. If groups_count_max is less than the number of supported groups configured by the security policy, this function will error.

Note that this API retrieves only the groups from a security policy that are available to negotiate via the supported groups extension, and does not return TLS 1.2 PQ kem groups that are negotiated in the supported PQ kem parameters extension.

Parameters
configA pointer to the s2n_config object from which the supported groups will be retrieved.
groupsThe array to populate with the supported groups.
groups_count_maxThe maximum number of supported groups that can fit in the groups array.
groups_countSet to the number of supported groups written to groups.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure.

◆ s2n_config_load_system_certs()

S2N_API int s2n_config_load_system_certs ( struct s2n_config *  config)

Loads default system certificates into the trust store.

s2n_config_new_minimal() doesn't load default system certificates into the config's trust store by default. If config was created with s2n_config_new_minimal, this function can be used to load system certificates into the trust store.

Note
This API will error if called on a config that has already loaded system certificates into its trust store, which includes all configs created with s2n_config_new().
Parameters
configThe configuration object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_new()

S2N_API struct s2n_config * s2n_config_new ( void  )

Creates a new s2n_config object. This object can (and should) be associated with many connection objects.

The returned config will be initialized with default system certificates in its trust store.

The returned config should be freed with s2n_config_free() after it's no longer in use by any connection.

Returns
A new configuration object suitable for configuring connections and associating certs and keys.

◆ s2n_config_new_minimal()

S2N_API struct s2n_config * s2n_config_new_minimal ( void  )

Creates a new s2n_config object with minimal default options.

This function has better performance than s2n_config_new() because it does not load default system certificates into the trust store by default. To add system certificates to this config, call s2n_config_load_system_certs().

The returned config should be freed with s2n_config_free() after it's no longer in use by any connection.

Returns
A new configuration object suitable for configuring connections and associating certs and keys.

◆ s2n_config_require_ticket_forward_secrecy()

S2N_API int s2n_config_require_ticket_forward_secrecy ( struct s2n_config *  config,
bool  enabled 
)

Requires that session tickets are only used when forward secrecy is possible.

Restricts session resumption to TLS1.3, as the tickets used in TLS1.2 resumption are not forward secret. Clients should not expect to receive new session tickets and servers will not send new session tickets when TLS1.2 is negotiated and ticket forward secrecy is required.

Note
The default behavior is that forward secrecy is not required.
Parameters
configThe config object being updated
enabledIndicates if forward secrecy is required or not on tickets
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_send_max_fragment_length()

S2N_API int s2n_config_send_max_fragment_length ( struct s2n_config *  config,
s2n_max_frag_len  mfl_code 
)

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.

Note
Some TLS implementations do not respect their peer's max fragment length extension.
Parameters
configThe configuration object being updated
mfl_codeThe selected MFL size
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_alert_behavior()

S2N_API int s2n_config_set_alert_behavior ( struct s2n_config *  config,
s2n_alert_behavior  alert_behavior 
)

Sets the config's alert behavior based on the s2n_alert_behavior enum.

Parameters
configThe configuration object being updated
alert_behaviorThe desired alert behavior.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_async_pkey_callback()

S2N_API int s2n_config_set_async_pkey_callback ( struct s2n_config *  config,
s2n_async_pkey_fn  fn 
)

Sets up the callback to invoke when private key operations occur.

Parameters
configConfig to set the callback
fnThe function that should be called for each private key operation

◆ s2n_config_set_async_pkey_validation_mode()

S2N_API int s2n_config_set_async_pkey_validation_mode ( struct s2n_config *  config,
s2n_async_pkey_validation_mode  mode 
)

Configures whether or not s2n-tls will perform potentially expensive validation of the results of a private key operation.

Parameters
configConfig to set the validation mode for
modeWhat level of validation to perform

◆ s2n_config_set_cache_delete_callback()

S2N_API int s2n_config_set_cache_delete_callback ( struct s2n_config *  config,
s2n_cache_delete_callback  cache_delete_callback,
void *  data 
)

Allows the caller to set a callback function that will be used to delete SSL session data from a cache.

Parameters
configThe configuration object being updated
cache_delete_callbackThe cache delete callback function.
dataAn opaque context pointer that the callback will be invoked with.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_cache_retrieve_callback()

S2N_API int s2n_config_set_cache_retrieve_callback ( struct s2n_config *  config,
s2n_cache_retrieve_callback  cache_retrieve_callback,
void *  data 
)

Allows the caller to set a callback function that will be used to retrieve SSL session data from a cache.

Parameters
configThe configuration object being updated
cache_retrieve_callbackThe cache retrieve callback function.
dataAn opaque context pointer that the callback will be invoked with.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_cache_store_callback()

S2N_API int s2n_config_set_cache_store_callback ( struct s2n_config *  config,
s2n_cache_store_callback  cache_store_callback,
void *  data 
)

Allows the caller to set a callback function that will be used to store SSL session data in a cache.

Parameters
configThe configuration object being updated
cache_store_callbackThe cache store callback function.
dataAn opaque context pointer that the callback will be invoked with.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_cert_chain_and_key_defaults()

S2N_API int s2n_config_set_cert_chain_and_key_defaults ( struct s2n_config *  config,
struct s2n_cert_chain_and_key **  cert_key_pairs,
uint32_t  num_cert_key_pairs 
)

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.

Only one certificate can be set as the default per auth method (one RSA default, one ECDSA default, etc.). All previous default certificates will be cleared and re-set when this API is called.

This API is called for a specific s2n_config object. s2n-tls will attempt to automatically choose default certificates for each auth method (key type) based on the order that s2n_cert_chain_and_key are added to the s2n_config using one of the APIs listed above. s2n_config_set_cert_chain_and_key_defaults can be called at any time; s2n-tls will clear defaults and no longer attempt to automatically choose any default certificates.

Parameters
configThe configuration object being updated
cert_key_pairsAn array of certificate chain and private key handles
num_cert_key_pairsThe amount of handles in cert_key_pairs
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_cert_tiebreak_callback()

S2N_API int s2n_config_set_cert_tiebreak_callback ( struct s2n_config *  config,
s2n_cert_tiebreak_callback  cert_tiebreak_cb 
)

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.

Parameters
configThe configuration object being updated
cert_tiebreak_cbThe pointer to the certificate tiebreak function
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_check_stapled_ocsp_response()

S2N_API int s2n_config_set_check_stapled_ocsp_response ( struct s2n_config *  config,
uint8_t  check_ocsp 
)

Toggles whether or not to validate stapled OCSP responses.

1 means OCSP responses will be validated when they are encountered, while 0 means this step will be skipped.

The default value is 1 if the underlying libCrypto implementation supports OCSP.

Parameters
configThe configuration object being updated
check_ocspThe desired OCSP response check configuration
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_cipher_preferences()

S2N_API int s2n_config_set_cipher_preferences ( struct s2n_config *  config,
const char *  version 
)

Sets the security policy that includes the cipher/kem/signature/ecc preferences and protocol version.

See the USAGE-GUIDE.md for how to use security policies.

◆ s2n_config_set_client_auth_type()

S2N_API int s2n_config_set_client_auth_type ( struct s2n_config *  config,
s2n_cert_auth_type  client_auth_type 
)

Sets whether or not a Client Certificate should be required to complete the TLS Connection.

If this is set to S2N_CERT_AUTH_OPTIONAL the server will request a client certificate but allow the client to not provide one. Rejecting a client certificate when using S2N_CERT_AUTH_OPTIONAL will terminate the handshake.

Parameters
configA pointer to a s2n_config object
client_auth_typeThe client auth policy for the connection
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_client_hello_cb()

S2N_API int s2n_config_set_client_hello_cb ( struct s2n_config *  config,
s2n_client_hello_fn  client_hello_callback,
void *  ctx 
)

Allows the caller to set a callback function that will be called after ClientHello was parsed.

Parameters
configThe configuration object being updated
client_hello_callbackThe client hello callback function
ctxA pointer to a user defined context that the Client Hello callback will be invoked with.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_client_hello_cb_mode()

S2N_API int s2n_config_set_client_hello_cb_mode ( struct s2n_config *  config,
s2n_client_hello_cb_mode  cb_mode 
)

Sets the callback execution mode.

See s2n_client_hello_cb_mode for each mode's behavior.

Parameters
configThe configuration object being updated
cb_modeThe desired callback mode
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_ct_support_level()

S2N_API int s2n_config_set_ct_support_level ( struct s2n_config *  config,
s2n_ct_support_level  level 
)

Set the Certificate Transparency Support level.

Parameters
configThe configuration object being updated
levelThe desired Certificate Transparency Support configuration
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_ctx()

S2N_API int s2n_config_set_ctx ( struct s2n_config *  config,
void *  ctx 
)

Sets user defined context on the s2n_config object.

Parameters
configThe configuration object being updated
ctxA pointer to the user defined ctx.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_early_data_cb()

S2N_API int s2n_config_set_early_data_cb ( struct s2n_config *  config,
s2n_early_data_cb  cb 
)

Set a callback to accept or reject early data.

Parameters
configA pointer to the connection config
cbA pointer to the implementation of the callback.
Returns
A POSIX error signal. If successful, the callback was set.

◆ s2n_config_set_extension_data()

S2N_API int s2n_config_set_extension_data ( struct s2n_config *  config,
s2n_tls_extension_type  type,
const uint8_t *  data,
uint32_t  length 
)

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.

Deprecated:
Use s2n_cert_chain_and_key_set_ocsp_data and s2n_cert_chain_and_key_set_sct_list instead.
Parameters
configThe configuration object being updated
typeThe extension type
dataData for the extension
lengthLength of the data buffer

◆ s2n_config_set_initial_ticket_count()

S2N_API int s2n_config_set_initial_ticket_count ( struct s2n_config *  config,
uint8_t  num 
)

Sets the initial number of session tickets to send after a >=TLS1.3 handshake. The default value is one ticket.

Parameters
configA pointer to the config object.
numThe number of session tickets that will be sent.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_key_log_cb()

S2N_API int s2n_config_set_key_log_cb ( struct s2n_config *  config,
s2n_key_log_fn  callback,
void *  ctx 
)

Sets a key logging callback on the provided config

THIS SHOULD BE USED FOR DEBUGGING PURPOSES ONLY!

Setting this function enables configurations to emit secrets in the NSS Key Log Format

Safety

  • callback MUST cast ctx into the same type of pointer that was originally created
  • ctx MUST live for at least as long as it is set on the config
Parameters
configConfig to set the callback
callbackThe function that should be called for each secret log entry
ctxThe context to be passed when the callback is called

◆ s2n_config_set_max_blinding_delay()

S2N_API int s2n_config_set_max_blinding_delay ( struct s2n_config *  config,
uint32_t  seconds 
)

Configures the maximum blinding delay enforced after errors.

Blinding protects your application from timing side channel attacks like Lucky13. While s2n-tls implements other, more specific mitigations for known timing side channels, blinding is important as a defense against currently unknown or unreported timing attacks.

Setting a maximum delay lower than the recommended default (30s) will make timing attacks against your application easier. The lower you set the delay, the fewer requests and less total time an attacker will require to execute an attack. If you must lower the delay for reasons such as client timeouts, then you should choose the highest value practically possible to limit your risk.

If you lower the blinding delay, you should also consider implementing monitoring and filtering to detect and reject suspicious traffic that could be gathering timing information from a potential side channel. Timing attacks usually involve repeatedly triggering TLS errors.

Warning
Do NOT set a lower blinding delay unless you understand the risks and have other mitigations for timing side channels in place.
Note
This delay needs to be set lower than any timeouts, such as your TCP socket timeout.
Parameters
configThe config object being updated.
secondsThe maximum number of seconds that s2n-tls will delay for in the event of a sensitive error.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure.

◆ s2n_config_set_max_cert_chain_depth()

S2N_API int s2n_config_set_max_cert_chain_depth ( struct s2n_config *  config,
uint16_t  max_depth 
)

Sets the maximum allowed depth of a cert chain used for X509 validation. The default value is

  1. 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.
Parameters
configThe configuration object being updated
max_depthThe number of allowed certificates in the certificate chain
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_monotonic_clock()

S2N_API int s2n_config_set_monotonic_clock ( struct s2n_config *  config,
s2n_clock_time_nanoseconds  clock_fn,
void *  ctx 
)

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.

s2n-tls uses this clock for timers.

Parameters
configThe configuration object being updated
clock_fnThe monotonic time callback function
ctxAn opaque pointer that the callback will be invoked with
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_protocol_preferences()

S2N_API int s2n_config_set_protocol_preferences ( struct s2n_config *  config,
const char *const *  protocols,
int  protocol_count 
)

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.

When acting as an S2N_CLIENT the protocol list is included in the Client Hello message as the ALPN extension.

As an S2N_SERVER, the list is used to negotiate a mutual application protocol with the client. After the negotiation for the connection has completed, the agreed upon protocol can be retrieved with s2n_get_application_protocol()

Parameters
configThe configuration object being updated
protocolsThe list of preferred protocols, in order of preference
protocol_countThe size of the protocols list
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_psk_mode()

S2N_API int s2n_config_set_psk_mode ( struct s2n_config *  config,
s2n_psk_mode  mode 
)

Sets the PSK mode on the s2n config object. The supported PSK modes are listed in the enum s2n_psk_mode above.

Parameters
configA pointer to the s2n_config object being updated.
modeThe PSK mode to be set.

◆ s2n_config_set_psk_selection_callback()

S2N_API int s2n_config_set_psk_selection_callback ( struct s2n_config *  config,
s2n_psk_selection_callback  cb,
void *  context 
)

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.

Parameters
configA pointer to the s2n_config object.
cbThe function that should be called when the callback is triggered.
contextA pointer to a context for the caller to pass state to the callback, if needed.

◆ s2n_config_set_recv_multi_record()

S2N_API int s2n_config_set_recv_multi_record ( struct s2n_config *  config,
bool  enabled 
)

Enable or disable receiving of multiple TLS records in a single s2n_recv call

By default, s2n-tls returns from s2n_recv() after reading a single TLS record. Enabling receiving of multiple records will instead cause s2n_recv() to attempt to read until the application-provided output buffer is full. This may be more efficient, especially if larger receive buffers are used.

Note
If this option is enabled with blocking IO, the call to s2n_recv() will not return until either the application-provided output buffer is full or the peer closes the connection. This may lead to unintentionally long waits if the peer does not send enough data.
Parameters
configThe configuration object being updated
enabledSet to true if multiple record receive is to be enabled; false to disable.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_send_buffer_size()

S2N_API int s2n_config_set_send_buffer_size ( struct s2n_config *  config,
uint32_t  size 
)

Set a custom send buffer size.

This buffer is used to stage records for sending. By default, enough memory is allocated to hold a single record of the maximum size configured for the connection. With the default fragment size, that is about 8K bytes.

Less memory can be allocated for the send buffer, but this will result in smaller, more fragmented records and increased overhead. While the absolute minimum size required is 1034 bytes, at least 2K bytes is recommended for reasonable record sizes.

More memory can be allocated for the send buffer. This will result in s2n-tls buffering multiple records before sending them, reducing system write calls. At least 17K bytes is recommended for this use case, or at least 35K bytes if larger fragment sizes are used via s2n_connection_prefer_throughput().

Parameters
configThe configuration object being updated
sizeThe desired custom buffer size.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_serialization_version()

S2N_API int s2n_config_set_serialization_version ( struct s2n_config *  config,
s2n_serialization_version  version 
)

Set what version to use when serializing connections

A version is required to serialize connections. Versioning ensures that all features negotiated during the handshake will be available wherever the connection is deserialized. Applications may need to update this version to pick up new features, since versioning may disable newer TLS features to ensure compatibility.

Parameters
configA pointer to the config object.
versionThe requested version.
Returns
S2N_SUCCESS on success, S2N_FAILURE on error.

◆ s2n_config_set_server_max_early_data_size()

S2N_API int s2n_config_set_server_max_early_data_size ( struct s2n_config *  config,
uint32_t  max_early_data_size 
)

Sets the maximum bytes of early data the server will accept.

The default maximum is 0. If the maximum is 0, the server rejects all early data requests. The config maximum can be overridden by the connection maximum or the maximum on an external pre-shared key.

Parameters
configA pointer to the config
max_early_data_sizeThe maximum early data that the server will accept
Returns
A POSIX error signal. If successful, the maximum early data size was updated.

◆ s2n_config_set_session_cache_onoff()

S2N_API int s2n_config_set_session_cache_onoff ( struct s2n_config *  config,
uint8_t  enabled 
)

Enable or disable session caching.

Note
Session caching will not be turned on unless all three session cache callbacks are set prior to calling this function.
Parameters
configThe configuration object being updated
enabledThe configuration object being updated. Set to 1 to enable. Set to 0 to disable.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_session_state_lifetime()

S2N_API int s2n_config_set_session_state_lifetime ( struct s2n_config *  config,
uint64_t  lifetime_in_secs 
)

Sets the lifetime of the cached session state. The default value is 15 hours.

Parameters
configThe configuration object being updated
lifetime_in_secsThe desired lifetime of the session state in seconds
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_session_ticket_cb()

S2N_API int s2n_config_set_session_ticket_cb ( struct s2n_config *  config,
s2n_session_ticket_fn  callback,
void *  ctx 
)

Sets a session ticket callback to be called when a client receives a new session ticket.

Safety

callback MUST cast ctx into the same type of pointer that was originally created. ctx MUST be valid for the lifetime of the config, or until a different context is set.

Parameters
configA pointer to the config object.
callbackThe function that should be called when the callback is triggered.
ctxThe context to be passed when the callback is called.

◆ s2n_config_set_session_tickets_onoff()

S2N_API int s2n_config_set_session_tickets_onoff ( struct s2n_config *  config,
uint8_t  enabled 
)

Enable or disable session resumption using session ticket.

Parameters
configThe configuration object being updated
enabledThe configuration object being updated. Set to 1 to enable. Set to 0 to disable.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_status_request_type()

S2N_API int s2n_config_set_status_request_type ( struct s2n_config *  config,
s2n_status_request_type  type 
)

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.

Note
SHA-1 is the only supported hash algorithm for the certID field. This is different from the hash algorithm used for the OCSP signature. See RFC 6960 for more information. While unlikely to be the case, if support for a different hash algorithm is required, the s2n-tls validation can be disabled with s2n_config_set_check_stapled_ocsp_response() and the response can be retrieved for manual validation with s2n_connection_get_ocsp_response().
Parameters
configThe configuration object being updated
typeThe desired request status type
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_ticket_decrypt_key_lifetime()

S2N_API int s2n_config_set_ticket_decrypt_key_lifetime ( struct s2n_config *  config,
uint64_t  lifetime_in_secs 
)

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.

Note
The default value is 13 hours.
Parameters
configThe configuration object being updated
lifetime_in_secsThe desired lifetime of decrypting and encrypting tickets in seconds
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_ticket_encrypt_decrypt_key_lifetime()

S2N_API int s2n_config_set_ticket_encrypt_decrypt_key_lifetime ( struct s2n_config *  config,
uint64_t  lifetime_in_secs 
)

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.

Note
The default value is 2 hours.
Parameters
configThe configuration object being updated
lifetime_in_secsThe desired lifetime of decrypting and encrypting tickets in seconds
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_verification_ca_location()

S2N_API int s2n_config_set_verification_ca_location ( struct s2n_config *  config,
const char *  ca_pem_filename,
const char *  ca_dir 
)

Adds to the trust store from a CA file or directory containing trusted certificates.

When configs are created with s2n_config_new(), the trust store is initialized with default system certificates. To completely override these certificates, call s2n_config_wipe_trust_store() before calling this function.

Note
The trust store will be initialized with the common locations for the host operating system by default.
Warning
This API uses the PEM parsing implementation from the linked libcrypto. This implementation will typically make a best-effort attempt to parse all of the certificates in the provided file or directory. This permissive approach may silently ignore malformed certificates, leading to possible connection failures if a certificate was expected to exist in the trust store but was skipped while parsing. As such, this API should only be used on PEMs that are known to be well-formed and parsable with the linked libcrypto, such as the system trust store. For all other PEMs, s2n_config_add_pem_to_trust_store() should be used instead, which parses more strictly.
Parameters
configThe configuration object being updated
ca_pem_filenameA string for the file path of the CA PEM file.
ca_dirA string for the directory of the CA PEM files.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_verify_after_sign()

S2N_API int s2n_config_set_verify_after_sign ( struct s2n_config *  config,
s2n_verify_after_sign  mode 
)

Toggle whether generated signatures are verified before being sent.

Although signatures produced by the underlying libcrypto should always be valid, hardware faults, bugs in the signing implementation, or other uncommon factors can cause unexpected mistakes in the final signatures. Because these mistakes can leak information about the private key, applications with low trust in their hardware or libcrypto may want to verify signatures before sending them.

However, this feature will significantly impact handshake latency. Additionally, most libcrypto implementations already check for common errors in signatures.

◆ s2n_config_set_verify_host_callback()

S2N_API int s2n_config_set_verify_host_callback ( struct s2n_config *  config,
s2n_verify_host_fn  ,
void *  data 
)

Sets the callback to use for verifying that a hostname from an X.509 certificate is trusted.

The default behavior is to require that the hostname match the server name set with s2n_set_server_name(). This will likely lead to all client certificates being rejected, so the callback will need to be overriden when using client authentication.

This change will be inherited by s2n_connections using this config. If a separate callback for different connections using the same config is desired, see s2n_connection_set_verify_host_callback().

Parameters
configThe configuration object being updated
dataA user supplied opaque context to pass back to the callback
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_set_wall_clock()

S2N_API int s2n_config_set_wall_clock ( struct s2n_config *  config,
s2n_clock_time_nanoseconds  clock_fn,
void *  ctx 
)

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

s2n-tls uses this clock for timestamps.

Parameters
configThe configuration object being updated
clock_fnThe wall clock time callback function
ctxAn opaque pointer that the callback will be invoked with
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_config_wipe_trust_store()

S2N_API int s2n_config_wipe_trust_store ( struct s2n_config *  config)

Clears the trust store of all certificates.

When configs are created with s2n_config_new(), the trust store is initialized with default system certificates. To completely override these certificates, call this function before functions like s2n_config_set_verification_ca_location() or s2n_config_add_pem_to_trust_store().

Parameters
configThe configuration object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_add_new_tickets_to_send()

S2N_API int s2n_connection_add_new_tickets_to_send ( struct s2n_connection *  conn,
uint8_t  num 
)

Increases the number of session tickets to send after a >=TLS1.3 handshake.

Parameters
connA pointer to the connection object.
numThe number of additional session tickets to send.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_append_protocol_preference()

S2N_API int s2n_connection_append_protocol_preference ( struct s2n_connection *  conn,
const uint8_t *  protocol,
uint8_t  protocol_len 
)

Appends the provided application protocol to the preference list

The data provided in protocol parameter will be copied into an internal buffer

Parameters
connThe connection object being updated
protocolA pointer to a slice of bytes
protocol_lenThe length of bytes that should be read from protocol. Note: this value cannot be 0, otherwise an error will be returned.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_append_psk()

S2N_API int s2n_connection_append_psk ( struct s2n_connection *  conn,
struct s2n_psk *  psk 
)

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.

Parameters
connA pointer to the s2n_connection object that contains the list of PSKs supported.
pskA pointer to the s2n_psk object to be appended to the list of PSKs on the s2n connection.

◆ s2n_connection_client_cert_used()

S2N_API int s2n_connection_client_cert_used ( struct s2n_connection *  conn)

Check if Client Auth was used for a connection.

Parameters
connA pointer to the connection
Returns
1 if the handshake completed and Client Auth was negotiated during then handshake.

◆ s2n_connection_deserialize()

S2N_API int s2n_connection_deserialize ( struct s2n_connection *  conn,
uint8_t *  buffer,
uint32_t  buffer_length 
)

Deserializes the provided buffer into the s2n_connection parameter.

Warning
s2n-tls DOES NOT check the integrity of the provided buffer. s2n-tls may successfully deserialize a corrupted buffer which WILL cause a connection failure when attempting to resume sending/receiving encrypted data. To avoid this, it is recommended to MAC and encrypt the serialized connection before sending it off-box and deserializing it.
Only a minimal amount of information about the original TLS connection is serialized. Therefore, after deserialization, the connection will behave like a new s2n_connection from the s2n_connection_new() call, except that it can read/write encrypted data from a peer. Any desired config-level or connection-level configuration will need to be re-applied to the deserialized connection. For this same reason none of the connection getters will return useful information about the original connection after deserialization. Any information about the original connection needs to be retrieved before serialization.
Parameters
connA pointer to the connection object. Should be a new s2n_connection object.
bufferA pointer to the buffer where the serialized connection will be read from.
buffer_lengthMaximum amount of data that can be read from the buffer parameter.
Returns
S2N_SUCCESS on success, S2N_FAILURE on error.

◆ s2n_connection_free()

S2N_API int s2n_connection_free ( struct s2n_connection *  conn)

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.

Parameters
connA pointer to the s2n_connection object
Returns
0 on success. -1 on failure

◆ s2n_connection_free_handshake()

S2N_API int s2n_connection_free_handshake ( struct s2n_connection *  conn)

Wipes and releases buffers and memory allocated during the TLS handshake.

Note
This function should be called after the handshake is successfully negotiated and logging or recording of handshake data is complete.
Parameters
connA pointer to the s2n_connection object
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_get_actual_protocol_version()

S2N_API int s2n_connection_get_actual_protocol_version ( struct s2n_connection *  conn)

Access the protocol version selected for the connection.

Note
The return value corresponds to the macros defined as S2N_SSLv2, S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
Parameters
connA pointer to the connection
Returns
The protocol version actually negotiated by the handshake

◆ s2n_connection_get_alert()

S2N_API int s2n_connection_get_alert ( struct s2n_connection *  conn)

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.

Parameters
connA pointer to the s2n connection
Returns
The TLS alert code that caused a connection to be shut down

◆ s2n_connection_get_cipher()

S2N_API const char * s2n_connection_get_cipher ( struct s2n_connection *  conn)

A function that provides a human readable string of the cipher suite that was chosen for a connection.

Warning
The string "TLS_NULL_WITH_NULL_NULL" is returned before the TLS handshake has been performed. This does not mean that the ciphersuite "TLS_NULL_WITH_NULL_NULL" will be used by the connection, it is merely being used as a placeholder.
Note
This function is only accurate after the TLS handshake.
Parameters
connA pointer to the connection
Returns
A string indicating the cipher suite negotiated by s2n in OpenSSL format.

◆ s2n_connection_get_cipher_iana_value()

S2N_API int s2n_connection_get_cipher_iana_value ( struct s2n_connection *  conn,
uint8_t *  first,
uint8_t *  second 
)

Returns the IANA value for the connection's negotiated cipher suite.

The value is returned in the form of first,second, in order to closely match the values defined in the IANA Registry. For example if the connection's negotiated cipher suite is TLS_AES_128_GCM_SHA256, which is registered as 0x13,0x01, then first = 0x13 and second = 0x01.

This method will only succeed after the cipher suite has been negotiated with the peer.

Parameters
connA pointer to the connection being read
firstA pointer to a single byte, which will be updated with the first byte in the registered IANA value.
secondA pointer to a single byte, which will be updated with the second byte in the registered IANA value.
Returns
A POSIX error signal. If an error was returned, the values contained in first and second should be considered invalid.

◆ s2n_connection_get_client_auth_type()

S2N_API int s2n_connection_get_client_auth_type ( struct s2n_connection *  conn,
s2n_cert_auth_type client_auth_type 
)

Gets Client Certificate authentication method the s2n_connection object is using.

Parameters
connA pointer to the s2n_connection object
client_auth_typeA pointer to a client auth policy. This will be updated to the s2n_connection value.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_get_client_cert_chain()

S2N_API int s2n_connection_get_client_cert_chain ( struct s2n_connection *  conn,
uint8_t **  der_cert_chain_out,
uint32_t *  cert_chain_len 
)

Gets the raw certificate chain received from the client.

The retrieved certificate chain has the format described by the TLS 1.2 RFC: https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.2. Each certificate is a DER-encoded ASN.1 X.509, prepended by a 3 byte network-endian length value. Note that this format is used regardless of the connection's protocol version.

Warning
The buffer pointed to by cert_chain_out shares its lifetime with the s2n_connection object.
Parameters
connA pointer to the s2n_connection object
cert_chain_outA pointer that's set to the client certificate chain.
cert_chain_lenA pointer that's set to the size of the cert_chain_out buffer.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_get_client_hello()

S2N_API struct s2n_client_hello * s2n_connection_get_client_hello ( struct s2n_connection *  conn)

Get the Client Hello from a s2n_connection.

Earliest point during the handshake when this structure is available for use is in the client_hello_callback (see s2n_config_set_client_hello_cb()).

Parameters
connThe connection object containing the client hello
Returns
A handle to the s2n_client_hello structure holding the client hello message sent by the client during the handshake. NULL is returned if a Client Hello has not yet been received and parsed.

◆ s2n_connection_get_client_hello_version()

S2N_API int s2n_connection_get_client_hello_version ( struct s2n_connection *  conn)

Access the client hello protocol version for the connection.

Note
The return value corresponds to the macros defined as S2N_SSLv2, S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
Parameters
connA pointer to the connection
Returns
The protocol version used to send the initial client hello message.

◆ s2n_connection_get_client_protocol_version()

S2N_API int s2n_connection_get_client_protocol_version ( struct s2n_connection *  conn)

Access the protocol version supported by the client.

Note
The return value corresponds to the macros defined as S2N_SSLv2, S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
Parameters
connA pointer to the connection
Returns
returns the highest protocol version supported by the client

◆ s2n_connection_get_ctx()

S2N_API void * s2n_connection_get_ctx ( struct s2n_connection *  conn)

Gets user defined context from a s2n_connection object.

Parameters
connThe connection object that contains the desired context

◆ s2n_connection_get_curve()

S2N_API const char * s2n_connection_get_curve ( struct s2n_connection *  conn)

Function to get the human readable elliptic curve name for the connection.

Parameters
connA pointer to the s2n connection
Returns
A string indicating the elliptic curve used during ECDHE key exchange. The string "NONE" is returned if no curve was used.

◆ s2n_connection_get_delay()

S2N_API uint64_t s2n_connection_get_delay ( struct s2n_connection *  conn)

Query the connection object for the configured blinding delay.

Parameters
connThe connection object being updated
Returns
the number of nanoseconds an application using self-service blinding should pause before calling close() or shutdown().

◆ s2n_connection_get_early_data_status()

S2N_API int s2n_connection_get_early_data_status ( struct s2n_connection *  conn,
s2n_early_data_status_t status 
)

Reports the current state of early data for a connection.

See s2n_early_data_status_t for all possible states.

Parameters
connA pointer to the connection
statusA pointer which will be set to the current early data status
Returns
A POSIX error signal.

◆ s2n_connection_get_handshake_type_name()

S2N_API const char * s2n_connection_get_handshake_type_name ( struct s2n_connection *  conn)

Function to return the last TLS handshake type that was processed. The returned format is a human readable string.

Parameters
connA pointer to the s2n connection
Returns
A human-readable handshake type name, e.g. "NEGOTIATED|FULL_HANDSHAKE|PERFECT_FORWARD_SECRECY"

◆ s2n_connection_get_kem_group_name()

S2N_API const char * s2n_connection_get_kem_group_name ( struct s2n_connection *  conn)

Function to get the human readable KEM group name for the connection.

Parameters
connA pointer to the s2n connection
Returns
A human readable string for the KEM group. If the connection is < TLS1.3 or there is no KEM group configured returns "NONE"

◆ s2n_connection_get_kem_name()

S2N_API const char * s2n_connection_get_kem_name ( struct s2n_connection *  conn)

Function to get the human readable KEM name for the connection.

Parameters
connA pointer to the s2n connection
Returns
A human readable string for the KEM group. If there is no KEM configured returns "NONE"

◆ s2n_connection_get_last_message_name()

S2N_API const char * s2n_connection_get_last_message_name ( struct s2n_connection *  conn)

Function to return the last TLS message that was processed. The returned format is a human readable string.

Parameters
connA pointer to the s2n connection
Returns
The last message name in the TLS state machine, e.g. "SERVER_HELLO", "APPLICATION_DATA".

◆ s2n_connection_get_master_secret()

S2N_API int s2n_connection_get_master_secret ( const struct s2n_connection *  conn,
uint8_t *  secret_bytes,
size_t  max_size 
)

Provides access to the TLS master secret.

This is a dangerous method and should not be used unless absolutely necessary. Mishandling the master secret can compromise both the current connection and any past or future connections that use the same master secret due to session resumption.

This method is only supported for older TLS versions, and will report an S2N_ERR_INVALID_STATE usage error if called for a TLS1.3 connection. TLS1.3 includes a new key schedule that derives independent secrets from the master secret for specific purposes, such as separate traffic, session ticket, and exporter secrets. Using the master secret directly circumvents that security feature, reducing the security of the protocol.

If you need cryptographic material tied to the current TLS session, consider s2n_connection_tls_exporter instead. Although s2n_connection_tls_exporter currently only supports TLS1.3, there is also an RFC that describes exporters for older TLS versions: https://datatracker.ietf.org/doc/html/rfc5705 Using the master secret as-is or defining your own exporter is dangerous.

Parameters
connA pointer to the connection.
secret_bytesMemory to copy the master secret into. The secret is always 48 bytes long.
max_sizeThe size of the memory available at secret_bytes. Must be at least 48 bytes.
Returns
S2N_SUCCESS on success, S2N_FAILURE otherwise. secret_bytes will be set on success.

◆ s2n_connection_get_max_early_data_size()

S2N_API int s2n_connection_get_max_early_data_size ( struct s2n_connection *  conn,
uint32_t *  max_early_data_size 
)

Reports the maximum size of the early data allowed by a connection.

This is the maximum amount of early data that can ever be sent and received for a connection. It is not affected by the actual status of the early data, so can be non-zero even if early data is rejected or not requested.

Parameters
connA pointer to the connection
max_early_data_sizeA pointer which will be set to the maximum early data allowed by conn
Returns
A POSIX error signal.

◆ s2n_connection_get_negotiated_psk_identity()

S2N_API int s2n_connection_get_negotiated_psk_identity ( struct s2n_connection *  conn,
uint8_t *  identity,
uint16_t  max_identity_length 
)

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.

Safety

The negotiated PSK identity will be copied into the identity buffer on success. Therefore, the identity buffer must have enough memory to fit the identity length.

Parameters
connA pointer to the s2n_connection object.
identityThe negotiated PSK identity obtained from the s2n_connection object.
max_identity_lengthThe maximum length for the PSK identity. If the negotiated psk_identity length is greater than this max_identity_length value an error will be returned.

◆ s2n_connection_get_negotiated_psk_identity_length()

S2N_API int s2n_connection_get_negotiated_psk_identity_length ( struct s2n_connection *  conn,
uint16_t *  identity_length 
)

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.

This API can be used to determine if the negotiated PSK exists. If negotiated PSK exists a call to this API returns a value greater than zero. If the negotiated PSK does not exist, the value 0 is returned.

Parameters
connA pointer to the s2n_connection object that successfully negotiated a PSK connection.
identity_lengthThe length of the negotiated PSK identity.

◆ s2n_connection_get_ocsp_response()

S2N_API const uint8_t * s2n_connection_get_ocsp_response ( struct s2n_connection *  conn,
uint32_t *  length 
)

Query the connection for a buffer containing the OCSP response.

Parameters
connThe connection object being queried
lengthA pointer that is set to the certificate transparency response buffer's size
Returns
A pointer to the OCSP response sent by a server during the handshake. If no status response is received, NULL is returned.

◆ s2n_connection_get_peer_cert_chain()

S2N_API int s2n_connection_get_peer_cert_chain ( const struct s2n_connection *  conn,
struct s2n_cert_chain_and_key *  cert_chain 
)

Returns the validated peer certificate chain as a s2n_cert_chain_and_key opaque object.

The s2n_cert_chain_and_key parameter must be allocated by the caller using the s2n_cert_chain_and_key_new API prior to this function call and must be empty. To free the memory associated with the s2n_cert_chain_and_key object use the s2n_cert_chain_and_key_free API.

Parameters
connA pointer to the s2n_connection object being read.
cert_chainThe returned validated peer certificate chain cert_chain retrieved from the s2n connection.

◆ s2n_connection_get_read_fd()

S2N_API int s2n_connection_get_read_fd ( struct s2n_connection *  conn,
int *  readfd 
)

Gets the assigned file descriptor for the read channel of an s2n connection.

Parameters
connA pointer to the s2n connection
readfdpointer to place the used file descriptor.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_get_remaining_early_data_size()

S2N_API int s2n_connection_get_remaining_early_data_size ( struct s2n_connection *  conn,
uint32_t *  allowed_early_data_size 
)

Reports the remaining size of the early data allowed by a connection.

If early data was rejected or not requested, the remaining early data size is 0. Otherwise, the remaining early data size is the maximum early data allowed by the connection, minus the early data sent or received so far.

Parameters
connA pointer to the connection
allowed_early_data_sizeA pointer which will be set to the remaining early data currently allowed by conn
Returns
A POSIX error signal.

◆ s2n_connection_get_sct_list()

S2N_API const uint8_t * s2n_connection_get_sct_list ( struct s2n_connection *  conn,
uint32_t *  length 
)

Query the connection for a buffer containing the Certificate Transparency response.

Parameters
connThe connection object being queried
lengthA pointer that is set to the certificate transparency response buffer's size
Returns
A pointer to the certificate transparency response buffer.

◆ s2n_connection_get_selected_cert()

S2N_API struct s2n_cert_chain_and_key * s2n_connection_get_selected_cert ( struct s2n_connection *  conn)

Get the certificate used during the TLS handshake

  • If conn is a server connection, the certificate selected will depend on the ServerName sent by the client and supported ciphers.
  • If conn is a client connection, the certificate sent in response to a CertificateRequest message is returned. Currently s2n-tls supports loading only one certificate in client mode. Note that not all TLS endpoints will request a certificate.
Parameters
connA pointer to the s2n_connection object
Returns
NULL if the certificate selection phase of the handshake has not completed or if a certificate was not requested by the peer

◆ s2n_connection_get_selected_client_cert_digest_algorithm()

S2N_API int s2n_connection_get_selected_client_cert_digest_algorithm ( struct s2n_connection *  conn,
s2n_tls_hash_algorithm chosen_alg 
)

Get the client certificate's digest algorithm.

Parameters
connA pointer to the s2n_connection object
chosen_algA pointer to a s2n_tls_hash_algorithm object. This is an output parameter.
Returns
S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.

◆ s2n_connection_get_selected_client_cert_signature_algorithm()

S2N_API int s2n_connection_get_selected_client_cert_signature_algorithm ( struct s2n_connection *  conn,
s2n_tls_signature_algorithm chosen_alg 
)

Get the client certificate's signature algorithm.

Parameters
connA pointer to the s2n_connection object
chosen_algA pointer to a s2n_tls_signature_algorithm object. This is an output parameter.
Returns
S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.

◆ s2n_connection_get_selected_digest_algorithm()

S2N_API int s2n_connection_get_selected_digest_algorithm ( struct s2n_connection *  conn,
s2n_tls_hash_algorithm chosen_alg 
)

Get the connection's selected digest algorithm.

Parameters
connA pointer to the s2n_connection object
chosen_algA pointer to a s2n_tls_hash_algorithm object. This is an output parameter.
Returns
S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.

◆ s2n_connection_get_selected_signature_algorithm()

S2N_API int s2n_connection_get_selected_signature_algorithm ( struct s2n_connection *  conn,
s2n_tls_signature_algorithm chosen_alg 
)

Get the connection's selected signature algorithm.

Parameters
connA pointer to the s2n_connection object
chosen_algA pointer to a s2n_tls_signature_algorithm object. This is an output parameter.
Returns
S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.

◆ s2n_connection_get_server_protocol_version()

S2N_API int s2n_connection_get_server_protocol_version ( struct s2n_connection *  conn)

Access the protocol version supported by the server.

Note
The return value corresponds to the macros defined as S2N_SSLv2, S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
Parameters
connA pointer to the connection
Returns
Returns the highest protocol version supported by the server

◆ s2n_connection_get_session()

S2N_API int s2n_connection_get_session ( struct s2n_connection *  conn,
uint8_t *  session,
size_t  max_length 
)

Serializes the session state from connection and copies into the session buffer and returns the number of copied bytes

Note
This function is not recommended for > TLS 1.2 because in TLS1.3 servers can send multiple session tickets and this function will only return the most recently received ticket.
Parameters
connA pointer to the s2n_connection object
sessionA pointer to a buffer of size max_length
max_lengthThe size of the session buffer
Returns
The number of copied bytes

◆ s2n_connection_get_session_id()

S2N_API int s2n_connection_get_session_id ( struct s2n_connection *  conn,
uint8_t *  session_id,
size_t  max_length 
)

Gets the latest session id from the connection, copies it into the session_id buffer, and returns the number of copied bytes.

The session id may change between s2n receiving the ClientHello and sending the ServerHello, but this function will always describe the latest session id.

See s2n_client_hello_get_session_id() to get the session id as it was sent by the client in the ClientHello message.

Parameters
connA pointer to the s2n_connection object
session_idA pointer to a buffer of size max_length
max_lengthThe size of the session_id buffer
Returns
The number of copied bytes.

◆ s2n_connection_get_session_id_length()

S2N_API int s2n_connection_get_session_id_length ( struct s2n_connection *  conn)

Gets the latest session id's length from the connection.

Use this to query the session id size before copying it into a buffer.

Parameters
connA pointer to the s2n_connection object
Returns
The latest session id length from the connection. Session id length will be 0 for TLS versions >= TLS1.3 as stateful session resumption has not yet been implemented in TLS1.3.

◆ s2n_connection_get_session_length()

S2N_API int s2n_connection_get_session_length ( struct s2n_connection *  conn)

Use this to query the serialized session state size before copying it into a buffer.

Parameters
connA pointer to the s2n_connection object
Returns
number of bytes needed to store serialized session state

◆ s2n_connection_get_session_ticket_lifetime_hint()

S2N_API int s2n_connection_get_session_ticket_lifetime_hint ( struct s2n_connection *  conn)

Retrieves a hint from the server indicating how long this ticket's lifetime is.

Note
This function is not recommended for > TLS 1.2 because in TLS1.3 servers can send multiple session tickets and this function will only return the most recently received ticket lifetime hint.
Parameters
connA pointer to the s2n_connection object
Returns
The session ticket lifetime hint in seconds from the server or -1 when session ticket was not used for resumption.

◆ s2n_connection_get_tickets_sent()

S2N_API int s2n_connection_get_tickets_sent ( struct s2n_connection *  conn,
uint16_t *  num 
)

Returns the number of session tickets issued by the server.

In TLS1.3, this number can be up to the limit configured by s2n_config_set_initial_ticket_count and s2n_connection_add_new_tickets_to_send. In earlier versions of TLS, this number will be either 0 or 1.

This method only works for server connections.

Parameters
connA pointer to the connection object.
numThe number of additional session tickets sent.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_get_wire_bytes_in()

S2N_API uint64_t s2n_connection_get_wire_bytes_in ( struct s2n_connection *  conn)

Get the number of bytes the connection has received.

Parameters
connA pointer to the connection
Returns
return the number of bytes received by s2n-tls "on the wire"

◆ s2n_connection_get_wire_bytes_out()

S2N_API uint64_t s2n_connection_get_wire_bytes_out ( struct s2n_connection *  conn)

Get the number of bytes the connection has transmitted out.

Parameters
connA pointer to the connection
Returns
return the number of bytes transmitted out by s2n-tls "on the wire"

◆ s2n_connection_get_write_fd()

S2N_API int s2n_connection_get_write_fd ( struct s2n_connection *  conn,
int *  writefd 
)

Gets the assigned file descriptor for the write channel of an s2n connection.

Parameters
connA pointer to the s2n connection
writefdpointer to place the used file descriptor.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_is_ocsp_stapled()

S2N_API int s2n_connection_is_ocsp_stapled ( struct s2n_connection *  conn)

Check if the connection is OCSP stapled.

Parameters
connA pointer to the s2n_connection object
Returns
1 if OCSP response was sent (if connection is in S2N_SERVER mode) or received (if connection is in S2N_CLIENT mode) during handshake, otherwise it returns 0.

◆ s2n_connection_is_session_resumed()

S2N_API int s2n_connection_is_session_resumed ( struct s2n_connection *  conn)

Check if the connection was resumed from an earlier handshake.

Parameters
connA pointer to the s2n_connection object
Returns
returns 1 if the handshake was abbreviated, otherwise returns 0

◆ s2n_connection_is_valid_for_cipher_preferences()

S2N_API int s2n_connection_is_valid_for_cipher_preferences ( struct s2n_connection *  conn,
const char *  version 
)

Function to check if the cipher used by current connection is supported by the current cipher preferences.

Parameters
connA pointer to the s2n connection
versionA 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.

◆ s2n_connection_new()

S2N_API struct s2n_connection * s2n_connection_new ( s2n_mode  mode)

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.

The mode parameters specifies if the caller is a server, or is a client. Connections objects are re-usable across many connections, and should be re-used (to avoid deallocating and allocating memory). You should wipe connections immediately after use.

Parameters
modeThe desired connection type
Returns
A s2n_connection handle

◆ s2n_connection_prefer_low_latency()

S2N_API int s2n_connection_prefer_low_latency ( struct s2n_connection *  conn)

Change the behavior of s2n-tls when sending data to prefer low latency.

Connections preferring low latency will be encrypted using small record sizes that can be decrypted sooner by the recipient.

Parameters
connThe connection object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_prefer_throughput()

S2N_API int s2n_connection_prefer_throughput ( struct s2n_connection *  conn)

Change the behavior of s2n-tls when sending data to prefer high throughput.

Connections preferring throughput will use large record sizes that minimize overhead.

Parameters
connThe connection object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_release_buffers()

S2N_API int s2n_connection_release_buffers ( struct s2n_connection *  conn)

Wipes and free the in and out buffers associated with a connection.

Note
This function may be called when a connection is in keep-alive or idle state to reduce memory overhead of long lived connections.
Parameters
connA pointer to the s2n_connection object
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_request_key_update()

S2N_API int s2n_connection_request_key_update ( struct s2n_connection *  conn,
s2n_peer_key_update  peer_request 
)

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.

Parameters
connThe connection object to trigger the key update on.
peer_requestIndicates if a key update should also be requested of the peer. When set to S2N_KEY_UPDATE_NOT_REQUESTED, then only the sending key of conn will be updated. If set to S2N_KEY_UPDATE_REQUESTED, then the sending key of conn will be updated AND the peer will be requested to update their sending key. Note that s2n-tls currently only supports peer_request being set to S2N_KEY_UPDATE_NOT_REQUESTED and will return S2N_FAILURE if any other value is used.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_serialization_length()

S2N_API int s2n_connection_serialization_length ( struct s2n_connection *  conn,
uint32_t *  length 
)

Retrieves the length of the serialized connection from s2n_connection_serialize(). Should be used to allocate enough memory for the serialized connection buffer.

Note
The size of the serialized connection changes based on parameters negotiated in the TLS handshake. Do not expect the size to always remain the same.
Parameters
connA pointer to the connection object.
lengthOutput parameter where the length will be written.
Returns
S2N_SUCCESS on success, S2N_FAILURE on error.

◆ s2n_connection_serialize()

S2N_API int s2n_connection_serialize ( struct s2n_connection *  conn,
uint8_t *  buffer,
uint32_t  buffer_length 
)

Serializes the s2n_connection into the provided buffer.

This API takes an established s2n-tls connection object and "serializes" it into a transferable object to be sent off-box or to another process. This transferable object can then be "deserialized" using the s2n_connection_deserialize method to instantiate an s2n-tls connection object that can talk to the original peer with the same encryption keys.

Warning
This feature is dangerous because it provides cryptographic material from a TLS session in plaintext. Users MUST both encrypt and MAC the contents of the outputted material to provide secrecy and integrity if this material is transported off-box. DO NOT store or send this material off-box without encryption.
Note
You MUST have used s2n_config_set_serialization_version() to set a version on the s2n_config object associated with this connection before this connection began its TLS handshake.
Call s2n_connection_serialization_length to retrieve the amount of memory needed for the buffer parameter.
This API will error if the handshake is not yet complete.
Parameters
connA pointer to the connection object.
bufferA pointer to the buffer where the serialized connection will be written.
buffer_lengthMaximum amount of data that can be written to the buffer param.
Returns
S2N_SUCCESS on success, S2N_FAILURE on error.

◆ s2n_connection_server_name_extension_used()

S2N_API int s2n_connection_server_name_extension_used ( struct s2n_connection *  conn)

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.

Parameters
connThe connection object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_blinding()

S2N_API int s2n_connection_set_blinding ( struct s2n_connection *  conn,
s2n_blinding  blinding 
)

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

Parameters
connThe connection object being updated
blindingThe desired blinding mode for the connection
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_cipher_preferences()

S2N_API int s2n_connection_set_cipher_preferences ( struct s2n_connection *  conn,
const char *  version 
)

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.

Parameters
connThe connection object being updated
versionThe human readable string representation of the security policy version.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_client_auth_type()

S2N_API int s2n_connection_set_client_auth_type ( struct s2n_connection *  conn,
s2n_cert_auth_type  client_auth_type 
)

Sets whether or not a Client Certificate should be required to complete the TLS Connection.

If this is set to S2N_CERT_AUTH_OPTIONAL the server will request a client certificate but allow the client to not provide one. Rejecting a client certificate when using S2N_CERT_AUTH_OPTIONAL will terminate the handshake.

Parameters
connA pointer to the s2n_connection object
client_auth_typeThe client auth policy for the connection
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_config()

S2N_API int s2n_connection_set_config ( struct s2n_connection *  conn,
struct s2n_config *  config 
)

Associates a configuration object with a connection.

Parameters
connThe connection object being associated
configThe configuration object being associated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_ctx()

S2N_API int s2n_connection_set_ctx ( struct s2n_connection *  conn,
void *  ctx 
)

Sets user defined context in s2n_connection object.

Parameters
connThe connection object being updated
ctxA pointer to the user defined context
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_dynamic_buffers()

S2N_API int s2n_connection_set_dynamic_buffers ( struct s2n_connection *  conn,
bool  enabled 
)

Configure the connection to free IO buffers when they are not currently in use.

This configuration can be used to minimize connection memory footprint size, at the cost of more calls to alloc and free. Some of these costs can be mitigated by configuring s2n-tls to use an allocator that includes thread-local caches or lock-free allocation patterns.

Parameters
connThe connection object being update
enabledSet to true if dynamic buffers are enabled; false if disabled
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_dynamic_record_threshold()

S2N_API int s2n_connection_set_dynamic_record_threshold ( struct s2n_connection *  conn,
uint32_t  resize_threshold,
uint16_t  timeout_threshold 
)

Changes the behavior of s2n-tls when sending data to initially prefer records small enough to fit in single ethernet frames.

When dynamic record sizing is active, the connection sends records small enough to fit in a single standard 1500 byte ethernet frame. Otherwise, the connection chooses record sizes according to the configured maximum fragment length.

Dynamic record sizing is active for the first resize_threshold bytes of a connection, and is reactivated whenever timeout_threshold seconds pass without sending data.

Parameters
connThe connection object being updated
resize_thresholdThe number of bytes to send before changing the record size. Maximum 8MiB.
timeout_thresholdReset record size back to a single segment after threshold seconds of inactivity
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_fd()

S2N_API int s2n_connection_set_fd ( struct s2n_connection *  conn,
int  fd 
)

Sets the file descriptor for a s2n connection.

Warning
If the read end of the pipe is closed unexpectedly, writing to the pipe will raise a SIGPIPE signal. s2n-tls does NOT handle SIGPIPE. A SIGPIPE signal will cause the process to terminate unless it is handled or ignored by the application.
Note
This file-descriptor should be active and connected
Parameters
connA pointer to the s2n connection
fdThe new file descriptor
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_protocol_preferences()

S2N_API int s2n_connection_set_protocol_preferences ( struct s2n_connection *  conn,
const char *const *  protocols,
int  protocol_count 
)

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.

Parameters
connThe connection object being updated
protocolsA pointer to an array of protocol strings
protocol_countThe number of protocols contained in protocols
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_psk_mode()

S2N_API int s2n_connection_set_psk_mode ( struct s2n_connection *  conn,
s2n_psk_mode  mode 
)

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.

Parameters
connA pointer to the s2n_connection object being updated.
modeThe PSK mode to be set.

◆ s2n_connection_set_read_fd()

S2N_API int s2n_connection_set_read_fd ( struct s2n_connection *  conn,
int  readfd 
)

Sets the file descriptor for the read channel of an s2n connection.

Warning
If the read end of the pipe is closed unexpectedly, writing to the pipe will raise a SIGPIPE signal. s2n-tls does NOT handle SIGPIPE. A SIGPIPE signal will cause the process to terminate unless it is handled or ignored by the application.
Note
This file-descriptor should be active and connected
Parameters
connA pointer to the s2n connection
readfdThe new read file descriptor
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_recv_buffering()

S2N_API int s2n_connection_set_recv_buffering ( struct s2n_connection *  conn,
bool  enabled 
)

Configure the connection to reduce potentially expensive calls to recv.

If this setting is disabled, s2n-tls will call read twice for every TLS record, which can be expensive but ensures that s2n-tls will always attempt to read the exact number of bytes it requires. If this setting is enabled, s2n-tls will instead reduce the number of calls to read by attempting to read as much data as possible in each read call, storing the extra in the existing IO buffers. This may cause it to request more data than will ever actually be available.

There is no additional memory cost of enabling this setting. It reuses the existing IO buffers.

This setting is disabled by default. Depending on how your application detects data available for reading, buffering reads may break your event loop. In particular, note that:

  1. File descriptor reads or calls to your custom s2n_recv_cb may request more data than is available. Reads must return partial data when available rather than blocking until all requested data is available.
  2. s2n_negotiate may read and buffer application data records. You must call s2n_recv at least once after negotiation to ensure that you handle any buffered data.
  3. s2n_recv may read and buffer more records than it parses and decrypts. You must call s2n_recv until it reports S2N_ERR_T_BLOCKED, rather than just until it reports S2N_SUCCESS.
  4. s2n_peek reports available decrypted data. It does not report any data buffered by this feature. However, s2n_peek_buffered does report data buffered by this feature.
  5. s2n_connection_release_buffers will not release the input buffer if it contains buffered data.

For example: if your event loop uses poll, you will receive a POLLIN event for your read file descriptor when new data is available. When you call s2n_recv to read that data, s2n-tls reads one or more TLS records from the file descriptor. If you stop calling s2n_recv before it reports S2N_ERR_T_BLOCKED, some of those records may remain in s2n-tls's read buffer. If you read part of a record, s2n_peek will report the remainder of that record as available. But if you don't read any of a record, it remains encrypted and is not reported by s2n_peek, but is still reported by s2n_peek_buffered. And because the data is buffered in s2n-tls instead of in the file descriptor, another call to poll will NOT report any more data available. Your application may hang waiting for more data.

Warning
This feature cannot be enabled for a connection that will enable kTLS for receiving.
This feature may work with blocking IO, if used carefully. Your blocking IO must support partial reads (so MSG_WAITALL cannot be used). You will either need to know exactly how much data your peer is sending, or will need to use s2n_peek and s2n_peek_buffered rather than relying on S2N_ERR_T_BLOCKED as noted in #3 above.
Parameters
connThe connection object being updated
enabledSet to true to enable, false to disable.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_recv_cb()

S2N_API int s2n_connection_set_recv_cb ( struct s2n_connection *  conn,
s2n_recv_fn  recv 
)

Configure a connection to use a recv callback to receive data.

Note
This callback may be blocking or nonblocking.
The callback may receive less than the requested length. The function should return the number of bytes received, or set errno and return an error code < 0.
Parameters
connThe connection object being updated
recvA recv callback function pointer
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_recv_ctx()

S2N_API int s2n_connection_set_recv_ctx ( struct s2n_connection *  conn,
void *  ctx 
)

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.

Note
The io_context passed to the callbacks may be set separately using s2n_connection_set_recv_ctx and s2n_connection_set_send_ctx.
Parameters
connThe connection object being updated
ctxA user provided context that the callback will be invoked with
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_send_cb()

S2N_API int s2n_connection_set_send_cb ( struct s2n_connection *  conn,
s2n_send_fn  send 
)

Configure a connection to use a send callback to send data.

Note
This callback may be blocking or nonblocking.
The callback may send less than the requested length. The function should return the number of bytes sent or set errno and return an error code < 0.
Parameters
connThe connection object being updated
sendA send callback function pointer
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_send_ctx()

S2N_API int s2n_connection_set_send_ctx ( struct s2n_connection *  conn,
void *  ctx 
)

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.

Note
The io_context passed to the callbacks may be set separately using s2n_connection_set_recv_ctx and s2n_connection_set_send_ctx.
Parameters
connThe connection object being updated
ctxA user provided context that the callback will be invoked with
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_server_early_data_context()

S2N_API int s2n_connection_set_server_early_data_context ( struct s2n_connection *  conn,
const uint8_t *  context,
uint16_t  context_size 
)

Sets the user context associated with early data on a server.

This context is passed to the s2n_early_data_cb callback to help decide whether to accept or reject early data.

Unlike most contexts, the early data context is a byte buffer instead of a void pointer. This is because we need to serialize the context into session tickets.

This API is intended for use with session resumption, and will not affect pre-shared keys.

Parameters
connA pointer to the connection
contextA pointer to the user context data. This data will be copied.
context_sizeThe size of the data to read from the context pointer.
Returns
A POSIX error signal. If successful, the context was updated.

◆ s2n_connection_set_server_keying_material_lifetime()

S2N_API int s2n_connection_set_server_keying_material_lifetime ( struct s2n_connection *  conn,
uint32_t  lifetime_in_secs 
)

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.

Parameters
connA pointer to the connection object.
lifetime_in_secsLifetime of keying material in seconds.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_server_max_early_data_size()

S2N_API int s2n_connection_set_server_max_early_data_size ( struct s2n_connection *  conn,
uint32_t  max_early_data_size 
)

Sets the maximum bytes of early data the server will accept.

The default maximum is 0. If the maximum is 0, the server rejects all early data requests. The connection maximum can be overridden by the maximum on an external pre-shared key.

Parameters
connA pointer to the connection
max_early_data_sizeThe maximum early data the server will accept
Returns
A POSIX error signal. If successful, the maximum early data size was updated.

◆ s2n_connection_set_session()

S2N_API int s2n_connection_set_session ( struct s2n_connection *  conn,
const uint8_t *  session,
size_t  length 
)

De-serializes the session state and updates the connection accordingly.

If this method fails, the connection should not be affected: calling s2n_negotiate with the connection should simply result in a full handshake.

Parameters
connA pointer to the s2n_connection object
sessionA pointer to a buffer of size length
lengthThe size of the session buffer
Returns
The number of copied bytes

◆ s2n_connection_set_verify_host_callback()

S2N_API int s2n_connection_set_verify_host_callback ( struct s2n_connection *  conn,
s2n_verify_host_fn  host_fn,
void *  data 
)

Sets the callback to use for verifying that a hostname from an X.509 certificate is trusted.

The default behavior is to require that the hostname match the server name set with s2n_set_server_name(). This will likely lead to all client certificates being rejected, so the callback will need to be overriden when using client authentication.

If a single callback for different connections using the same config is desired, see s2n_config_set_verify_host_callback().

Parameters
connA pointer to a s2n_connection object
host_fnA pointer to a callback function that s2n will invoke in order to verify the hostname of an X.509 certificate
dataOpaque pointer to data that the verify host function will be invoked with
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_set_write_fd()

S2N_API int s2n_connection_set_write_fd ( struct s2n_connection *  conn,
int  writefd 
)

Sets the assigned file descriptor for the write channel of an s2n connection.

Note
This file-descriptor should be active and connected
Parameters
connA pointer to the s2n connection
writefdThe new write file descriptor
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_tls_exporter()

S2N_API int s2n_connection_tls_exporter ( struct s2n_connection *  conn,
const uint8_t *  label,
uint32_t  label_length,
const uint8_t *  context,
uint32_t  context_length,
uint8_t *  output,
uint32_t  output_length 
)

Provides access to the TLS-Exporter functionality.

See https://datatracker.ietf.org/doc/html/rfc5705 and https://www.rfc-editor.org/rfc/rfc8446.

Note
This is currently only available with TLS 1.3 connections which have finished a handshake.
Parameters
connA pointer to the connection
Returns
A POSIX error signal. If an error was returned, the value contained in output should be considered invalid.

◆ s2n_connection_use_corked_io()

S2N_API int s2n_connection_use_corked_io ( struct s2n_connection *  conn)

Indicates to s2n that the connection is using corked IO.

Warning
This API should only be used when using managed send IO.
Parameters
connThe connection object being updated
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_connection_wipe()

S2N_API int s2n_connection_wipe ( struct s2n_connection *  conn)

Wipes an existing connection and allows it to be reused. Erases all data associated with a connection including pending reads.

Note
This function should be called after all I/O is completed and s2n_shutdown has been called.
Reusing the same connection handle(s) is more performant than repeatedly calling s2n_connection_new() and s2n_connection_free().
Parameters
connA pointer to the s2n_connection object
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_crypto_disable_init()

S2N_API int s2n_crypto_disable_init ( void  )

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.

Warning
This function must be called BEFORE s2n_init() to have any effect. It will return an error if s2n is already initialized.
Note
If you disable this and are using a version of OpenSSL/libcrypto < 1.1.x, you will be responsible for library init and cleanup (specifically OPENSSL_add_all_algorithms() or OPENSSL_init_crypto(), and EVP_* APIs will not be usable unless the library is initialized.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_disable_atexit()

S2N_API int s2n_disable_atexit ( void  )

Prevents S2N from installing an atexit handler, which allows safe shutdown of S2N from within a re-entrant shared library

Warning
This function must be called BEFORE s2n_init() to have any effect. It will return an error if s2n is already initialized.
Note
This will cause s2n_cleanup to do complete cleanup of s2n-tls when called from the main thread (the thread s2n_init was called from).
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_errno_location()

S2N_API int * s2n_errno_location ( void  )

This function can be used instead of trying to resolve s2n_errno directly in runtimes where thread-local variables may not be easily accessible.

Returns
The address of the thread-local s2n_errno variable

◆ s2n_error_get_type()

S2N_API int s2n_error_get_type ( int  error)

Gets the category of error from an error.

s2n-tls organizes errors into different "types" to allow applications to do logic on error values without catching all possibilities. Applications using non-blocking I/O should check error type to determine if the I/O operation failed because it would block or for some other error.

Parameters
errorThe error from s2n. Usually this is s2n_errno.
Returns
An s2n_error_type

◆ s2n_external_psk_new()

S2N_API struct s2n_psk * s2n_external_psk_new ( void  )

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.

Use s2n_psk_free to free the memory allocated to the s2n external PSK object created by this API.

Returns
struct s2n_psk* Returns a pointer to the newly created external PSK object.

◆ s2n_free_stacktrace()

S2N_API int s2n_free_stacktrace ( void  )

Clean up the memory used to contain the stack trace.

Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_get_application_protocol()

S2N_API const char * s2n_get_application_protocol ( struct s2n_connection *  conn)

Query the connection for the selected application protocol.

Parameters
connThe connection object being queried
Returns
The negotiated application protocol for a s2n_connection. In the event of no protocol being negotiated, NULL is returned.

◆ s2n_get_fips_mode()

S2N_API int s2n_get_fips_mode ( s2n_fips_mode *  fips_mode)

Determines whether s2n-tls is operating in FIPS mode.

s2n-tls enters FIPS mode on initialization when the linked libcrypto has FIPS mode enabled. Some libcryptos, such as AWS-LC-FIPS, have FIPS mode enabled by default. With other libcryptos, such as OpenSSL, FIPS mode must be enabled before initialization by calling FIPS_mode_set().

s2n-tls MUST be linked to a FIPS libcrypto and MUST be in FIPS mode in order to comply with FIPS requirements. Applications desiring FIPS compliance should use this API to ensure that s2n-tls has been properly linked with a FIPS libcrypto and has successfully entered FIPS mode.

Parameters
fips_modeSet to the FIPS mode of s2n-tls.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure.

◆ s2n_get_openssl_version()

S2N_API unsigned long s2n_get_openssl_version ( void  )

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.

Returns
the version number of OpenSSL that s2n-tls was compiled with

◆ s2n_get_server_name()

S2N_API const char * s2n_get_server_name ( struct s2n_connection *  conn)

Query the connection for the selected server name.

This can be used by a server to determine which server name the client is using. This function returns the first ServerName entry in the ServerNameList sent by the client. Subsequent entries are not returned.

Parameters
connThe connection object being queried
Returns
The server name associated with a connection, or NULL if none is found.

◆ s2n_get_stacktrace()

S2N_API int s2n_get_stacktrace ( struct s2n_stacktrace *  trace)

Export the s2n_stacktrace.

Parameters
traceA pointer to the s2n_stacktrace to fill.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_init()

S2N_API int s2n_init ( void  )

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.

Warning
This function is not thread safe and should only be called once.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_mem_set_callbacks()

S2N_API int s2n_mem_set_callbacks ( s2n_mem_init_callback  mem_init_callback,
s2n_mem_cleanup_callback  mem_cleanup_callback,
s2n_mem_malloc_callback  mem_malloc_callback,
s2n_mem_free_callback  mem_free_callback 
)

Allows the caller to override s2n-tls's internal memory handling functions.

Warning
This function must be called before s2n_init().
Parameters
mem_init_callbackThe s2n_mem_init_callback
mem_cleanup_callbackThe s2n_mem_cleanup_callback
mem_malloc_callbackThe s2n_mem_malloc_callback
mem_free_callbackThe s2n_mem_free_callback
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_negotiate()

S2N_API int s2n_negotiate ( struct s2n_connection *  conn,
s2n_blocked_status blocked 
)

Performs the initial "handshake" phase of a TLS connection and must be called before any s2n_recv() or s2n_send() calls.

Note
When using client authentication with TLS1.3, s2n_negotiate() will report a successful handshake to clients before the server validates the client certificate. If the server then rejects the client certificate, the client may later receive an alert while calling s2n_recv, potentially after already having sent application data with s2n_send.

See the following example for guidance on calling s2n_negotiate(): https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_negotiate.c

Parameters
connA pointer to the s2n_connection object
blockedA pointer which will be set to the blocked status if an S2N_ERR_T_BLOCKED error is returned.
Returns
S2N_SUCCESS if the handshake completed. S2N_FAILURE if the handshake encountered an error or is blocked.

◆ s2n_offered_early_data_accept()

S2N_API int s2n_offered_early_data_accept ( struct s2n_offered_early_data *  early_data)

Accept early data offered by the client.

Parameters
early_dataA pointer to the early data information
Returns
A POSIX error signal. If success, the client's early data will be accepted.

◆ s2n_offered_early_data_get_context()

S2N_API int s2n_offered_early_data_get_context ( struct s2n_offered_early_data *  early_data,
uint8_t *  context,
uint16_t  max_len 
)

Get the early data context set by the user.

Parameters
early_dataA pointer to the early data information
contextA byte buffer to copy the user context into
max_lenThe size of context. Must be >= to the result of s2n_offered_early_data_get_context_length.
Returns
A POSIX error signal.

◆ s2n_offered_early_data_get_context_length()

S2N_API int s2n_offered_early_data_get_context_length ( struct s2n_offered_early_data *  early_data,
uint16_t *  context_len 
)

Get the length of the early data context set by the user.

Parameters
early_dataA pointer to the early data information
context_lenThe length of the user context
Returns
A POSIX error signal.

◆ s2n_offered_early_data_reject()

S2N_API int s2n_offered_early_data_reject ( struct s2n_offered_early_data *  early_data)

Reject early data offered by the client.

Parameters
early_dataA pointer to the early data information
Returns
A POSIX error signal. If success, the client's early data will be rejected.

◆ s2n_offered_psk_free()

S2N_API int s2n_offered_psk_free ( struct s2n_offered_psk **  psk)

Frees the memory associated with the s2n_offered_psk object.

Parameters
pskA pointer to the s2n_offered_psk object to be freed.

◆ s2n_offered_psk_get_identity()

S2N_API int s2n_offered_psk_get_identity ( struct s2n_offered_psk *  psk,
uint8_t **  identity,
uint16_t *  size 
)

Gets the PSK identity and PSK identity length for a given offered PSK object.

Parameters
pskA pointer to the offered PSK object being read.
identityThe PSK identity being obtained.
sizeThe length of the PSK identity being obtained.

◆ s2n_offered_psk_list_choose_psk()

S2N_API int s2n_offered_psk_list_choose_psk ( struct s2n_offered_psk_list *  psk_list,
struct s2n_offered_psk *  psk 
)

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.

Parameters
psk_listA pointer to the server's known PSK list used to compare for a matching PSK with the client.
pskA pointer to the client's PSK object used to compare with the server's known PSK identities.

◆ s2n_offered_psk_list_has_next()

S2N_API bool s2n_offered_psk_list_has_next ( struct s2n_offered_psk_list *  psk_list)

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.

Safety

This API returns a pointer to the s2n-tls internal memory with limited lifetime. After the completion of s2n_psk_selection_callback this pointer is invalid.

Parameters
psk_listA pointer to the offered PSK list being read.
Returns
bool A boolean value representing whether an offered psk object is present next in line in the offered PSK list.

◆ s2n_offered_psk_list_next()

S2N_API int s2n_offered_psk_list_next ( struct s2n_offered_psk_list *  psk_list,
struct s2n_offered_psk *  psk 
)

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.

Parameters
psk_listA pointer to the offered PSK list being read.
pskA pointer to the next offered PSK object being obtained.

◆ s2n_offered_psk_list_reread()

S2N_API int s2n_offered_psk_list_reread ( struct s2n_offered_psk_list *  psk_list)

Returns the offered PSK list to its original read state.

When s2n_offered_psk_list_reread is called, s2n_offered_psk_list_next will return the first PSK in the offered PSK list.

Parameters
psk_listA pointer to the offered PSK list being reread.

◆ s2n_offered_psk_new()

S2N_API struct s2n_offered_psk * s2n_offered_psk_new ( void  )

Creates a new s2n offered PSK object. An offered PSK object represents a single PSK sent by the client.

Safety

Use s2n_offered_psk_free to free the memory allocated to the s2n offered PSK object created by this API.

Returns
struct s2n_offered_psk* Returns a pointer to the newly created offered PSK object.

◆ s2n_peek()

S2N_API uint32_t s2n_peek ( struct s2n_connection *  conn)

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.

This is useful when using select() on the underlying s2n-tls file descriptor with a message based application layer protocol. As a single call to s2n_recv may read all data off the underlying file descriptor, select() will be unable to tell you there if there is more application data ready for processing already loaded into the s2n-tls buffer.

Note
can then be used to determine if s2n_recv() needs to be called before more data comes in on the raw fd
Parameters
connA pointer to the s2n_connection object
Returns
The number of bytes that can be read from the connection

◆ s2n_peek_buffered()

S2N_API uint32_t s2n_peek_buffered ( struct s2n_connection *  conn)

Reports how many bytes of unprocessed TLS records are buffered due to the optimization enabled by s2n_connection_set_recv_buffering.

s2n_peek_buffered is not a replacement for s2n_peek. While s2n_peek reports application data that is ready for the application to read with no additional processing, s2n_peek_buffered reports raw TLS records that still need to be parsed and likely decrypted. Those records may contain application data, but they may also only contain TLS control messages.

If an application needs to determine whether there is any data left to handle (for example, before calling poll to wait on the read file descriptor) then that application must check both s2n_peek and s2n_peek_buffered.

Parameters
connA pointer to the s2n_connection object
Returns
The number of buffered encrypted bytes

◆ s2n_print_stacktrace()

S2N_API int s2n_print_stacktrace ( FILE *  fptr)

Prints the s2n stack trace to a file. The file descriptor is expected to be open and ready for writing.

Parameters
fptrA pointer to the file s2n-tls should write the stack trace to.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_psk_configure_early_data()

S2N_API int s2n_psk_configure_early_data ( struct s2n_psk *  psk,
uint32_t  max_early_data_size,
uint8_t  cipher_suite_first_byte,
uint8_t  cipher_suite_second_byte 
)

Configures a particular pre-shared key to allow early data.

max_early_data_size must be set to the maximum early data accepted by the server.

In order to use early data, the cipher suite set on the pre-shared key must match the cipher suite ultimately negotiated by the TLS handshake. Additionally, the cipher suite must have the same hmac algorithm as the pre-shared key.

Parameters
pskA pointer to the pre-shared key, created with s2n_external_psk_new.
max_early_data_sizeThe maximum early data that can be sent or received using this key.
cipher_suite_first_byteThe first byte in the registered IANA value of the associated cipher suite.
cipher_suite_second_byteThe second byte in the registered IANA value of the associated cipher suite.
Returns
A POSIX error signal. If successful, psk was updated.

◆ s2n_psk_free()

S2N_API int s2n_psk_free ( struct s2n_psk **  psk)

Frees the memory associated with the external PSK object.

Parameters
pskPointer to the PSK object to be freed.

◆ s2n_psk_set_application_protocol()

S2N_API int s2n_psk_set_application_protocol ( struct s2n_psk *  psk,
const uint8_t *  application_protocol,
uint8_t  size 
)

Sets the optional application_protocol associated with the given pre-shared key.

In order to use early data, the application_protocol set on the pre-shared key must match the application_protocol ultimately negotiated by the TLS handshake.

Parameters
pskA pointer to the pre-shared key, created with s2n_external_psk_new.
application_protocolA pointer to the associated application protocol data. This data will be copied.
sizeThe size of the data to read from the application_protocol pointer.
Returns
A POSIX error signal. If successful, the application protocol was set.

◆ s2n_psk_set_early_data_context()

S2N_API int s2n_psk_set_early_data_context ( struct s2n_psk *  psk,
const uint8_t *  context,
uint16_t  size 
)

Sets the optional user early data context associated with the given pre-shared key.

The early data context is passed to the s2n_early_data_cb callback to help decide whether to accept or reject early data.

Parameters
pskA pointer to the pre-shared key, created with s2n_external_psk_new.
contextA pointer to the associated user context data. This data will be copied.
sizeThe size of the data to read from the context pointer.
Returns
A POSIX error signal. If successful, the context was set.

◆ s2n_psk_set_hmac()

S2N_API int s2n_psk_set_hmac ( struct s2n_psk *  psk,
s2n_psk_hmac  hmac 
)

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.

Parameters
pskA pointer to the external PSK object to be updated with the PSK hash algorithm.
hmacThe PSK hash algorithm being set.

◆ s2n_psk_set_identity()

S2N_API int s2n_psk_set_identity ( struct s2n_psk *  psk,
const uint8_t *  identity,
uint16_t  identity_size 
)

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.

Safety

The identity is transmitted over the network unencrypted and is a non-secret value. Do not include confidential information in the identity.

Note that the identity is copied into s2n-tls memory and the caller is responsible for freeing the memory associated with the identity input.

Parameters
pskA pointer to a PSK object to be updated with the identity.
identityThe identity in raw bytes format to be copied.
identity_sizeThe length of the PSK identity being set.

◆ s2n_psk_set_secret()

S2N_API int s2n_psk_set_secret ( struct s2n_psk *  psk,
const uint8_t *  secret,
uint16_t  secret_size 
)

Sets the out-of-band/externally provisioned secret for a given external PSK object.

Safety

Note that the secret is copied into s2n-tls memory and the caller is responsible for freeing the memory associated with the secret input.

Deriving a shared secret from a password or other low-entropy source is not secure and is subject to dictionary attacks. See https://tools.ietf.org/rfc/rfc8446#section-2.2 for more information.

Parameters
pskA pointer to a PSK object to be updated with the secret.
secretThe secret in raw bytes format to be copied.
secret_sizeThe length of the pre-shared secret being set.

◆ s2n_rand_set_callbacks()

S2N_API int s2n_rand_set_callbacks ( s2n_rand_init_callback  rand_init_callback,
s2n_rand_cleanup_callback  rand_cleanup_callback,
s2n_rand_seed_callback  rand_seed_callback,
s2n_rand_mix_callback  rand_mix_callback 
)

Allows the caller to override s2n-tls's entropy functions.

Warning
This function must be called before s2n_init().
Note
The overriden random callbacks will not be used when s2n-tls is operating in FIPS mode.
Parameters
rand_init_callbackThe s2n_rand_init_callback
rand_cleanup_callbackThe s2n_rand_cleanup_callback
rand_seed_callbackThe s2n_rand_seed_callback
rand_mix_callbackThe s2n_rand_mix_callback
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_recv()

S2N_API ssize_t s2n_recv ( struct s2n_connection *  conn,
void *  buf,
ssize_t  size,
s2n_blocked_status blocked 
)

Decrypts and reads **size* to buf data from the associated connection.

Note
Unlike OpenSSL, repeated calls to s2n_recv should not duplicate the original parameters, but should update buf and size per the indication of size read.

See the following example for guidance on calling s2n_recv(): https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_recv.c

Parameters
connA pointer to the s2n_connection object
bufA pointer to a buffer that s2n will place read data into.
sizeSize of buf
blockedA pointer which will be set to the blocked status if an S2N_ERR_T_BLOCKED error is returned.
Returns
The number of bytes read on success. 0 if the connection was shutdown by the peer. S2N_FAILURE on failure.

◆ s2n_recv_early_data()

S2N_API int s2n_recv_early_data ( struct s2n_connection *  conn,
uint8_t *  data,
ssize_t  max_data_len,
ssize_t *  data_received,
s2n_blocked_status blocked 
)

Called by the server to begin negotiation and accept any early data the client sends.

See https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch14-early-data.md for usage and examples. DO NOT USE unless you have considered the security issues and implemented mitigation for anti-replay attacks.

Parameters
connA pointer to the connection
dataA pointer to a buffer to store the early data received
max_data_lenThe size of the early data buffer
data_receivedA pointer which will be set to the size of the early data received
blockedA pointer which will be set to the blocked status, as in s2n_negotiate.
Returns
A POSIX error signal. The error should be handled as in s2n_negotiate.

◆ s2n_send()

S2N_API ssize_t s2n_send ( struct s2n_connection *  conn,
const void *  buf,
ssize_t  size,
s2n_blocked_status blocked 
)

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.

Note
Partial writes are possible not just for non-blocking I/O, but also for connections aborted while active.
Unlike OpenSSL, repeated calls to s2n_send() should not duplicate the original parameters, but should update buf and size per the indication of size written.

See the following example for guidance on calling s2n_send(): https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_send.c

Parameters
connA pointer to the s2n_connection object
bufA pointer to a buffer that s2n will write data from
sizeThe size of buf
blockedA pointer which will be set to the blocked status if an S2N_ERR_T_BLOCKED error is returned.
Returns
The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.

◆ s2n_send_early_data()

S2N_API int s2n_send_early_data ( struct s2n_connection *  conn,
const uint8_t *  data,
ssize_t  data_len,
ssize_t *  data_sent,
s2n_blocked_status blocked 
)

Called by the client to begin negotiation and send early data.

See https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch14-early-data.md for usage and examples. DO NOT USE unless you have considered the security issues and implemented mitigation for anti-replay attacks.

Parameters
connA pointer to the connection
dataA pointer to the early data to be sent
data_lenThe size of the early data to send
data_sentA pointer which will be set to the size of the early data sent
blockedA pointer which will be set to the blocked status, as in s2n_negotiate.
Returns
A POSIX error signal. The error should be handled as in s2n_negotiate.

◆ s2n_sendv()

S2N_API ssize_t s2n_sendv ( struct s2n_connection *  conn,
const struct iovec *  bufs,
ssize_t  count,
s2n_blocked_status blocked 
)

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.

Parameters
connA pointer to the s2n_connection object
bufsA pointer to a vector of buffers that s2n will write data from.
countThe number of buffers in bufs
blockedA pointer which will be set to the blocked status if an S2N_ERR_T_BLOCKED error is returned.
Returns
The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.

◆ s2n_sendv_with_offset()

S2N_API ssize_t s2n_sendv_with_offset ( struct s2n_connection *  conn,
const struct iovec *  bufs,
ssize_t  count,
ssize_t  offs,
s2n_blocked_status blocked 
)

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.

Note
Partial writes are possible not just for non-blocking I/O, but also for connections aborted while active.
Unlike OpenSSL, repeated calls to s2n_sendv_with_offset() should not duplicate the original parameters, but should update bufs and count per the indication of size written.

See the following example for guidance on calling s2n_sendv_with_offset(): https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_send.c

Parameters
connA pointer to the s2n_connection object
bufsA pointer to a vector of buffers that s2n will write data from.
countThe number of buffers in bufs
offsThe write cursor offset. This should be updated as data is written. See the example code.
blockedA pointer which will be set to the blocked status if an S2N_ERR_T_BLOCKED error is returned.
Returns
The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.

◆ s2n_session_ticket_get_data()

S2N_API int s2n_session_ticket_get_data ( struct s2n_session_ticket *  ticket,
size_t  max_data_len,
uint8_t *  data 
)

Gets the session ticket data from a session ticket object.

Safety

The entire session ticket will be copied into data on success. Therefore, data MUST have enough memory to store the session ticket data.

Parameters
ticketPointer to the session ticket object.
max_data_lenMaximum length of data that can be written to the 'data' pointer.
dataPointer to where the session ticket data will be stored.

◆ s2n_session_ticket_get_data_len()

S2N_API int s2n_session_ticket_get_data_len ( struct s2n_session_ticket *  ticket,
size_t *  data_len 
)

Gets the length of the session ticket from a session ticket object.

Parameters
ticketPointer to the session ticket object.
data_lenPointer to be set to the length of the session ticket on success.

◆ s2n_session_ticket_get_lifetime()

S2N_API int s2n_session_ticket_get_lifetime ( struct s2n_session_ticket *  ticket,
uint32_t *  session_lifetime 
)

Gets the lifetime in seconds of the session ticket from a session ticket object.

Parameters
ticketPointer to the session ticket object.
session_lifetimePointer to a variable where the lifetime of the session ticket will be stored.

◆ s2n_set_server_name()

S2N_API int s2n_set_server_name ( struct s2n_connection *  conn,
const char *  server_name 
)

Sets the server name for the connection.

The provided server name will be sent by the client to the server in the server_name ClientHello extension. It may be desirable for clients to provide this information to facilitate secure connections to servers that host multiple 'virtual' servers at a single underlying network address.

s2n-tls does not place any restrictions on the provided server name. However, other TLS implementations might. Specifically, the TLS specification for the server_name extension requires that it be an ASCII-encoded DNS name without a trailing dot, and explicitly forbids literal IPv4 or IPv6 addresses.

Parameters
connThe connection object being queried
server_nameA pointer to a string containing the desired server name
Warning
server_name must be a NULL terminated string.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_shutdown()

S2N_API int s2n_shutdown ( struct s2n_connection *  conn,
s2n_blocked_status blocked 
)

Attempts a closure at the TLS layer. Does not close the underlying transport. This call may block in either direction.

Unlike other TLS implementations, s2n_shutdown attempts a graceful shutdown by default. It will not return with success unless a close_notify alert is successfully sent and received. As a result, s2n_shutdown may fail when interacting with a non-conformant TLS implementation.

Once s2n_shutdown is complete:

  • The s2n_connection handle cannot be used for reading for writing.
  • The underlying transport can be closed. Most likely via shutdown() or close().
  • The s2n_connection handle can be freed via s2n_connection_free() or reused via s2n_connection_wipe()
Parameters
connA pointer to the s2n_connection object
blockedA pointer which will be set to the blocked status if an S2N_ERR_T_BLOCKED error is returned.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_shutdown_send()

S2N_API int s2n_shutdown_send ( struct s2n_connection *  conn,
s2n_blocked_status blocked 
)

Attempts to close the write side of the TLS connection.

TLS1.3 supports closing the write side of a TLS connection while leaving the read side unaffected. This feature is usually referred to as "half-close". We send a close_notify alert, but do not wait for the peer to respond.

Like s2n_shutdown(), this method does not affect the underlying transport.

s2n_shutdown_send() may still be called for earlier TLS versions, but most TLS implementations will react by immediately discarding any pending writes and closing the connection.

Once s2n_shutdown_send() is complete:

  • The s2n_connection handle CANNOT be used for writing.
  • The s2n_connection handle CAN be used for reading.
  • The write side of the underlying transport can be closed. Most likely via shutdown().

The application should still call s2n_shutdown() or wait for s2n_recv() to return 0 to indicate end-of-data before cleaning up the connection or closing the read side of the underlying transport.

Parameters
connA pointer to the s2n_connection object
blockedA pointer which will be set to the blocked status if an S2N_ERR_T_BLOCKED error is returned.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_stack_traces_enabled()

S2N_API bool s2n_stack_traces_enabled ( void  )

Checks if s2n stack trace captures are enabled.

Returns
True if stack traces are enabled. False if they are disabled.

◆ s2n_stack_traces_enabled_set()

S2N_API int s2n_stack_traces_enabled_set ( bool  newval)

Configures the s2n stack trace captures option.

Parameters
newvalBoolean to determine if stack traces should be enabled. True to enable them. False to disable them.
Returns
S2N_SUCCESS on success. S2N_FAILURE on failure

◆ s2n_strerror()

S2N_API const char * s2n_strerror ( int  error,
const char *  lang 
)

Translates an s2n_error code to a human readable string explaining the error.

Parameters
errorThe error code to explain. Usually this is s2n_errno
langThe language to explain the error code. Pass "EN" or NULL for English.
Returns
The error string

◆ s2n_strerror_debug()

S2N_API const char * s2n_strerror_debug ( int  error,
const char *  lang 
)

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.

Parameters
errorThe error code to explain. Usually this is s2n_errno
langThe language to explain the error code. Pass "EN" or NULL for English.
Returns
The error string

◆ s2n_strerror_name()

S2N_API const char * s2n_strerror_name ( int  error)

Translates an s2n_error code to a human readable string.

Parameters
errorThe error code to explain. Usually this is s2n_errno
Returns
The error string

◆ s2n_strerror_source()

S2N_API const char * s2n_strerror_source ( int  error)

Translates an s2n_error code to a filename and line number.

Parameters
errorThe error code to explain. Usually this is s2n_errno.
Returns
The error string.

Variable Documentation

◆ s2n_errno

S2N_API __thread int s2n_errno
extern

s2n-tls functions that return 'int' return 0 to indicate success and -1 to indicate failure.

s2n-tls functions that return pointer types return NULL in the case of failure.

When an s2n-tls function returns a failure, s2n_errno will be set to a value corresponding to the error. This error value can be translated into a string explaining the error in English by calling s2n_strerror(s2n_errno, "EN"). A string containing human readable error name; can be generated with s2n_strerror_name. A string containing internal debug information, including filename and line number, can be generated with s2n_strerror_debug. A string containing only the filename and line number can be generated with s2n_strerror_source. This string is useful to include when reporting issues to the s2n-tls development team.

Warning
To avoid possible confusion, s2n_errno should be cleared after processing an error: s2n_errno = S2N_ERR_T_OK