DragonFly On-Line Manual Pages
ssl(3) OpenSSL ssl(3)
NAME
SSL - OpenSSL SSL/TLS library
SYNOPSIS
DESCRIPTION
The OpenSSL ssl library implements the Secure Sockets Layer (SSL v2/v3)
and Transport Layer Security (TLS v1) protocols. It provides a rich API
which is documented here.
At first the library must be initialized; see SSL_library_init(3).
Then an SSL_CTX object is created as a framework to establish TLS/SSL
enabled connections (see SSL_CTX_new(3)). Various options regarding
certificates, algorithms etc. can be set in this object.
When a network connection has been created, it can be assigned to an
SSL object. After the SSL object has been created using SSL_new(3),
SSL_set_fd(3) or SSL_set_bio(3) can be used to associate the network
connection with the object.
Then the TLS/SSL handshake is performed using SSL_accept(3) or
SSL_connect(3) respectively. SSL_read(3) and SSL_write(3) are used to
read and write data on the TLS/SSL connection. SSL_shutdown(3) can be
used to shut down the TLS/SSL connection.
DATA STRUCTURES
Currently the OpenSSL ssl library functions deals with the following
data structures:
SSL_METHOD (SSL Method)
That's a dispatch structure describing the internal ssl library
methods/functions which implement the various protocol versions
(SSLv1, SSLv2 and TLSv1). It's needed to create an SSL_CTX.
SSL_CIPHER (SSL Cipher)
This structure holds the algorithm information for a particular
cipher which are a core part of the SSL/TLS protocol. The available
ciphers are configured on a SSL_CTX basis and the actually used
ones are then part of the SSL_SESSION.
SSL_CTX (SSL Context)
That's the global context structure which is created by a server or
client once per program life-time and which holds mainly default
values for the SSL structures which are later created for the
connections.
SSL_SESSION (SSL Session)
This is a structure containing the current TLS/SSL session details
for a connection: SSL_CIPHERs, client and server certificates,
keys, etc.
SSL (SSL Connection)
That's the main SSL/TLS structure which is created by a server or
client per established connection. This actually is the core
structure in the SSL API. Under run-time the application usually
deals with this structure which has links to mostly all other
structures.
HEADER FILES
Currently the OpenSSL ssl library provides the following C header files
containing the prototypes for the data structures and and functions:
ssl.h
That's the common header file for the SSL/TLS API. Include it into
your program to make the API of the ssl library available. It
internally includes both more private SSL headers and headers from
the crypto library. Whenever you need hard-core details on the
internals of the SSL API, look inside this header file.
ssl2.h
That's the sub header file dealing with the SSLv2 protocol only.
Usually you don't have to include it explicitly because it's
already included by ssl.h.
ssl3.h
That's the sub header file dealing with the SSLv3 protocol only.
Usually you don't have to include it explicitly because it's
already included by ssl.h.
ssl23.h
That's the sub header file dealing with the combined use of the
SSLv2 and SSLv3 protocols. Usually you don't have to include it
explicitly because it's already included by ssl.h.
tls1.h
That's the sub header file dealing with the TLSv1 protocol only.
Usually you don't have to include it explicitly because it's
already included by ssl.h.
API FUNCTIONS
Currently the OpenSSL ssl library exports 214 API functions. They are
documented in the following:
DEALING WITH PROTOCOL METHODS
Here we document the various API functions which deal with the SSL/TLS
protocol methods defined in SSL_METHOD structures.
const SSL_METHOD *SSLv23_method(void);
Constructor for the version-flexible SSL_METHOD structure for
clients, servers or both. See SSL_CTX_new(3) for details.
const SSL_METHOD *SSLv23_client_method(void);
Constructor for the version-flexible SSL_METHOD structure for
clients.
const SSL_METHOD *SSLv23_client_method(void);
Constructor for the version-flexible SSL_METHOD structure for
servers.
const SSL_METHOD *TLSv1_2_method(void);
Constructor for the TLSv1.2 SSL_METHOD structure for clients,
servers or both.
const SSL_METHOD *TLSv1_2_client_method(void);
Constructor for the TLSv1.2 SSL_METHOD structure for clients.
const SSL_METHOD *TLSv1_2_server_method(void);
Constructor for the TLSv1.2 SSL_METHOD structure for servers.
const SSL_METHOD *TLSv1_1_method(void);
Constructor for the TLSv1.1 SSL_METHOD structure for clients,
servers or both.
const SSL_METHOD *TLSv1_1_client_method(void);
Constructor for the TLSv1.1 SSL_METHOD structure for clients.
const SSL_METHOD *TLSv1_1_server_method(void);
Constructor for the TLSv1.1 SSL_METHOD structure for servers.
const SSL_METHOD *TLSv1_method(void);
Constructor for the TLSv1 SSL_METHOD structure for clients, servers
or both.
const SSL_METHOD *TLSv1_client_method(void);
Constructor for the TLSv1 SSL_METHOD structure for clients.
const SSL_METHOD *TLSv1_server_method(void);
Constructor for the TLSv1 SSL_METHOD structure for servers.
const SSL_METHOD *SSLv3_method(void);
Constructor for the SSLv3 SSL_METHOD structure for clients, servers
or both.
const SSL_METHOD *SSLv3_client_method(void);
Constructor for the SSLv3 SSL_METHOD structure for clients.
const SSL_METHOD *SSLv3_server_method(void);
Constructor for the SSLv3 SSL_METHOD structure for servers.
const SSL_METHOD *SSLv2_method(void);
Constructor for the SSLv2 SSL_METHOD structure for clients, servers
or both.
const SSL_METHOD *SSLv2_client_method(void);
Constructor for the SSLv2 SSL_METHOD structure for clients.
const SSL_METHOD *SSLv2_server_method(void);
Constructor for the SSLv2 SSL_METHOD structure for servers.
DEALING WITH CIPHERS
Here we document the various API functions which deal with the SSL/TLS
ciphers defined in SSL_CIPHER structures.
char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int len);
Write a string to buf (with a maximum size of len) containing a
human readable description of cipher. Returns buf.
int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits);
Determine the number of bits in cipher. Because of export crippled
ciphers there are two bits: The bits the algorithm supports in
general (stored to alg_bits) and the bits which are actually used
(the return value).
const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher);
Return the internal name of cipher as a string. These are the
various strings defined by the SSL2_TXT_xxx, SSL3_TXT_xxx and
TLS1_TXT_xxx definitions in the header files.
char *SSL_CIPHER_get_version(SSL_CIPHER *cipher);
Returns a string like ""TLSv1/SSLv3"" or ""SSLv2"" which indicates
the SSL/TLS protocol version to which cipher belongs (i.e. where it
was defined in the specification the first time).
DEALING WITH PROTOCOL CONTEXTS
Here we document the various API functions which deal with the SSL/TLS
protocol context defined in the SSL_CTX structure.
int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x);
long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);
int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_CTX_check_private_key(const SSL_CTX *ctx);
long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, char *parg);
void SSL_CTX_flush_sessions(SSL_CTX *s, long t);
void SSL_CTX_free(SSL_CTX *a);
char *SSL_CTX_get_app_data(SSL_CTX *ctx);
X509_STORE *SSL_CTX_get_cert_store(SSL_CTX *ctx);
STACK *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509,
EVP_PKEY **pkey);
void SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);
char *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx);
int SSL_CTX_get_ex_new_index(long argl, char *argp, int
(*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))(SSL *ssl, int cb, int
ret);
int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);
void SSL_CTX_get_read_ahead(SSL_CTX *ctx);
int SSL_CTX_get_session_cache_mode(SSL_CTX *ctx);
long SSL_CTX_get_timeout(const SSL_CTX *ctx);
int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int ok,
X509_STORE_CTX *ctx);
int SSL_CTX_get_verify_mode(SSL_CTX *ctx);
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, char *CAfile, char
*CApath);
long SSL_CTX_need_tmp_RSA(SSL_CTX *ctx);
SSL_CTX *SSL_CTX_new(const SSL_METHOD *meth);
int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_CTX_sess_accept(SSL_CTX *ctx);
int SSL_CTX_sess_accept_good(SSL_CTX *ctx);
int SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);
int SSL_CTX_sess_cache_full(SSL_CTX *ctx);
int SSL_CTX_sess_cb_hits(SSL_CTX *ctx);
int SSL_CTX_sess_connect(SSL_CTX *ctx);
int SSL_CTX_sess_connect_good(SSL_CTX *ctx);
int SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);
int SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);
SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(SSL *ssl,
unsigned char *data, int len, int *copy);
int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION
*sess);
void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx)(SSL_CTX *ctx,
SSL_SESSION *sess);
int SSL_CTX_sess_hits(SSL_CTX *ctx);
int SSL_CTX_sess_misses(SSL_CTX *ctx);
int SSL_CTX_sess_number(SSL_CTX *ctx);
void SSL_CTX_sess_set_cache_size(SSL_CTX *ctx,t);
void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl,
unsigned char *data, int len, int *copy));
void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl,
SSL_SESSION *sess));
void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx,
SSL_SESSION *sess));
int SSL_CTX_sess_timeouts(SSL_CTX *ctx);
LHASH *SSL_CTX_sessions(SSL_CTX *ctx);
void SSL_CTX_set_app_data(SSL_CTX *ctx, void *arg);
void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *cs);
void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(), char *arg)
int SSL_CTX_set_cipher_list(SSL_CTX *ctx, char *str);
void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK *list);
void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509
**x509, EVP_PKEY **pkey));
void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, int (*cb);(void))
void SSL_CTX_set_default_read_ahead(SSL_CTX *ctx, int m);
int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, char *arg);
void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*cb)(SSL *ssl, int
cb, int ret));
void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int
version, int content_type, const void *buf, size_t len, SSL *ssl, void
*arg));
void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
void SSL_CTX_set_options(SSL_CTX *ctx, unsigned long op);
void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode);
void SSL_CTX_set_read_ahead(SSL_CTX *ctx, int m);
void SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, int mode);
int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *meth);
void SSL_CTX_set_timeout(SSL_CTX *ctx, long t);
long SSL_CTX_set_tmp_dh(SSL_CTX* ctx, DH *dh);
long SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, DH *(*cb)(void));
long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
SSL_CTX_set_tmp_rsa_callback
"long SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx, RSA *(*cb)(SSL
*ssl, int export, int keylength));"
Sets the callback which will be called when a temporary private key
is required. The "export" flag will be set if the reason for
needing a temp key is that an export ciphersuite is in use, in
which case, "keylength" will contain the required keylength in
bits. Generate a key of appropriate size (using ???) and return it.
SSL_set_tmp_rsa_callback
long SSL_set_tmp_rsa_callback(SSL *ssl, RSA *(*cb)(SSL *ssl, int
export, int keylength));
The same as SSL_CTX_set_tmp_rsa_callback, except it operates on an
SSL session instead of a context.
void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, int (*cb);(void))
int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
int SSL_CTX_use_PrivateKey_ASN1(int type, SSL_CTX *ctx, unsigned char
*d, long len);
int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, char *file, int type);
int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long
len);
int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, char *file, int type);
int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char
*d);
int SSL_CTX_use_certificate_file(SSL_CTX *ctx, char *file, int type);
X509 *SSL_CTX_get0_certificate(const SSL_CTX *ctx);
EVP_PKEY *SSL_CTX_get0_privatekey(const SSL_CTX *ctx);
void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, unsigned int
(*callback)(SSL *ssl, const char *hint, char *identity, unsigned int
max_identity_len, unsigned char *psk, unsigned int max_psk_len));
int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, unsigned int
(*callback)(SSL *ssl, const char *identity, unsigned char *psk, int
max_psk_len));
DEALING WITH SESSIONS
Here we document the various API functions which deal with the SSL/TLS
sessions defined in the SSL_SESSION structures.
int SSL_SESSION_cmp(const SSL_SESSION *a, const SSL_SESSION *b);
void SSL_SESSION_free(SSL_SESSION *ss);
char *SSL_SESSION_get_app_data(SSL_SESSION *s);
char *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx);
int SSL_SESSION_get_ex_new_index(long argl, char *argp, int
(*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
long SSL_SESSION_get_time(const SSL_SESSION *s);
long SSL_SESSION_get_timeout(const SSL_SESSION *s);
unsigned long SSL_SESSION_hash(const SSL_SESSION *a);
SSL_SESSION *SSL_SESSION_new(void);
int SSL_SESSION_print(BIO *bp, const SSL_SESSION *x);
int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *x);
void SSL_SESSION_set_app_data(SSL_SESSION *s, char *a);
int SSL_SESSION_set_ex_data(SSL_SESSION *s, int idx, char *arg);
long SSL_SESSION_set_time(SSL_SESSION *s, long t);
long SSL_SESSION_set_timeout(SSL_SESSION *s, long t);
DEALING WITH CONNECTIONS
Here we document the various API functions which deal with the SSL/TLS
connection defined in the SSL structure.
int SSL_accept(SSL *ssl);
int SSL_add_dir_cert_subjects_to_stack(STACK *stack, const char *dir);
int SSL_add_file_cert_subjects_to_stack(STACK *stack, const char
*file);
int SSL_add_client_CA(SSL *ssl, X509 *x);
char *SSL_alert_desc_string(int value);
char *SSL_alert_desc_string_long(int value);
char *SSL_alert_type_string(int value);
char *SSL_alert_type_string_long(int value);
int SSL_check_private_key(const SSL *ssl);
void SSL_clear(SSL *ssl);
long SSL_clear_num_renegotiations(SSL *ssl);
int SSL_connect(SSL *ssl);
void SSL_copy_session_id(SSL *t, const SSL *f);
long SSL_ctrl(SSL *ssl, int cmd, long larg, char *parg);
int SSL_do_handshake(SSL *ssl);
SSL *SSL_dup(SSL *ssl);
STACK *SSL_dup_CA_list(STACK *sk);
void SSL_free(SSL *ssl);
SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);
char *SSL_get_app_data(SSL *ssl);
X509 *SSL_get_certificate(const SSL *ssl);
const char *SSL_get_cipher(const SSL *ssl);
int SSL_get_cipher_bits(const SSL *ssl, int *alg_bits);
char *SSL_get_cipher_list(const SSL *ssl, int n);
char *SSL_get_cipher_name(const SSL *ssl);
char *SSL_get_cipher_version(const SSL *ssl);
STACK *SSL_get_ciphers(const SSL *ssl);
STACK *SSL_get_client_CA_list(const SSL *ssl);
SSL_CIPHER *SSL_get_current_cipher(SSL *ssl);
long SSL_get_default_timeout(const SSL *ssl);
int SSL_get_error(const SSL *ssl, int i);
char *SSL_get_ex_data(const SSL *ssl, int idx);
int SSL_get_ex_data_X509_STORE_CTX_idx(void);
int SSL_get_ex_new_index(long argl, char *argp, int (*new_func);(void),
int (*dup_func)(void), void (*free_func)(void))
int SSL_get_fd(const SSL *ssl);
void (*SSL_get_info_callback(const SSL *ssl);)()
STACK *SSL_get_peer_cert_chain(const SSL *ssl);
X509 *SSL_get_peer_certificate(const SSL *ssl);
EVP_PKEY *SSL_get_privatekey(const SSL *ssl);
int SSL_get_quiet_shutdown(const SSL *ssl);
BIO *SSL_get_rbio(const SSL *ssl);
int SSL_get_read_ahead(const SSL *ssl);
SSL_SESSION *SSL_get_session(const SSL *ssl);
char *SSL_get_shared_ciphers(const SSL *ssl, char *buf, int len);
int SSL_get_shutdown(const SSL *ssl);
const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);
int SSL_get_state(const SSL *ssl);
long SSL_get_time(const SSL *ssl);
long SSL_get_timeout(const SSL *ssl);
int (*SSL_get_verify_callback(const SSL *ssl))(int,X509_STORE_CTX *)
int SSL_get_verify_mode(const SSL *ssl);
long SSL_get_verify_result(const SSL *ssl);
char *SSL_get_version(const SSL *ssl);
BIO *SSL_get_wbio(const SSL *ssl);
int SSL_in_accept_init(SSL *ssl);
int SSL_in_before(SSL *ssl);
int SSL_in_connect_init(SSL *ssl);
int SSL_in_init(SSL *ssl);
int SSL_is_init_finished(SSL *ssl);
STACK *SSL_load_client_CA_file(char *file);
void SSL_load_error_strings(void);
SSL *SSL_new(SSL_CTX *ctx);
long SSL_num_renegotiations(SSL *ssl);
int SSL_peek(SSL *ssl, void *buf, int num);
int SSL_pending(const SSL *ssl);
int SSL_read(SSL *ssl, void *buf, int num);
int SSL_renegotiate(SSL *ssl);
char *SSL_rstate_string(SSL *ssl);
char *SSL_rstate_string_long(SSL *ssl);
long SSL_session_reused(SSL *ssl);
void SSL_set_accept_state(SSL *ssl);
void SSL_set_app_data(SSL *ssl, char *arg);
void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);
int SSL_set_cipher_list(SSL *ssl, char *str);
void SSL_set_client_CA_list(SSL *ssl, STACK *list);
void SSL_set_connect_state(SSL *ssl);
int SSL_set_ex_data(SSL *ssl, int idx, char *arg);
int SSL_set_fd(SSL *ssl, int fd);
void SSL_set_info_callback(SSL *ssl, void (*cb);(void))
void SSL_set_msg_callback(SSL *ctx, void (*cb)(int write_p, int
version, int content_type, const void *buf, size_t len, SSL *ssl, void
*arg));
void SSL_set_msg_callback_arg(SSL *ctx, void *arg);
void SSL_set_options(SSL *ssl, unsigned long op);
void SSL_set_quiet_shutdown(SSL *ssl, int mode);
void SSL_set_read_ahead(SSL *ssl, int yes);
int SSL_set_rfd(SSL *ssl, int fd);
int SSL_set_session(SSL *ssl, SSL_SESSION *session);
void SSL_set_shutdown(SSL *ssl, int mode);
int SSL_set_ssl_method(SSL *ssl, const SSL_METHOD *meth);
void SSL_set_time(SSL *ssl, long t);
void SSL_set_timeout(SSL *ssl, long t);
void SSL_set_verify(SSL *ssl, int mode, int (*callback);(void))
void SSL_set_verify_result(SSL *ssl, long arg);
int SSL_set_wfd(SSL *ssl, int fd);
int SSL_shutdown(SSL *ssl);
int SSL_state(const SSL *ssl);
char *SSL_state_string(const SSL *ssl);
char *SSL_state_string_long(const SSL *ssl);
long SSL_total_renegotiations(SSL *ssl);
int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
int SSL_use_PrivateKey_ASN1(int type, SSL *ssl, unsigned char *d, long
len);
int SSL_use_PrivateKey_file(SSL *ssl, char *file, int type);
int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
int SSL_use_RSAPrivateKey_file(SSL *ssl, char *file, int type);
int SSL_use_certificate(SSL *ssl, X509 *x);
int SSL_use_certificate_ASN1(SSL *ssl, int len, unsigned char *d);
int SSL_use_certificate_file(SSL *ssl, char *file, int type);
int SSL_version(const SSL *ssl);
int SSL_want(const SSL *ssl);
int SSL_want_nothing(const SSL *ssl);
int SSL_want_read(const SSL *ssl);
int SSL_want_write(const SSL *ssl);
int SSL_want_x509_lookup(const SSL *ssl);
int SSL_write(SSL *ssl, const void *buf, int num);
void SSL_set_psk_client_callback(SSL *ssl, unsigned int (*callback)(SSL
*ssl, const char *hint, char *identity, unsigned int max_identity_len,
unsigned char *psk, unsigned int max_psk_len));
int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
void SSL_set_psk_server_callback(SSL *ssl, unsigned int (*callback)(SSL
*ssl, const char *identity, unsigned char *psk, int max_psk_len));
const char *SSL_get_psk_identity_hint(SSL *ssl);
const char *SSL_get_psk_identity(SSL *ssl);
SEE ALSO
openssl(1), crypto(3), SSL_accept(3), SSL_clear(3), SSL_connect(3),
SSL_CIPHER_get_name(3), SSL_COMP_add_compression_method(3),
SSL_CTX_add_extra_chain_cert(3), SSL_CTX_add_session(3),
SSL_CTX_ctrl(3), SSL_CTX_flush_sessions(3),
SSL_CTX_get_ex_new_index(3), SSL_CTX_get_verify_mode(3),
SSL_CTX_load_verify_locations(3) SSL_CTX_new(3),
SSL_CTX_sess_number(3), SSL_CTX_sess_set_cache_size(3),
SSL_CTX_sess_set_get_cb(3), SSL_CTX_sessions(3),
SSL_CTX_set_cert_store(3), SSL_CTX_set_cert_verify_callback(3),
SSL_CTX_set_cipher_list(3), SSL_CTX_set_client_CA_list(3),
SSL_CTX_set_client_cert_cb(3), SSL_CTX_set_default_passwd_cb(3),
SSL_CTX_set_generate_session_id(3), SSL_CTX_set_info_callback(3),
SSL_CTX_set_max_cert_list(3), SSL_CTX_set_mode(3),
SSL_CTX_set_msg_callback(3), SSL_CTX_set_options(3),
SSL_CTX_set_quiet_shutdown(3), SSL_CTX_set_read_ahead(3),
SSL_CTX_set_session_cache_mode(3), SSL_CTX_set_session_id_context(3),
SSL_CTX_set_ssl_version(3), SSL_CTX_set_timeout(3),
SSL_CTX_set_tmp_rsa_callback(3), SSL_CTX_set_tmp_dh_callback(3),
SSL_CTX_set_verify(3), SSL_CTX_use_certificate(3),
SSL_alert_type_string(3), SSL_do_handshake(3), SSL_get_SSL_CTX(3),
SSL_get_ciphers(3), SSL_get_client_CA_list(3),
SSL_get_default_timeout(3), SSL_get_error(3),
SSL_get_ex_data_X509_STORE_CTX_idx(3), SSL_get_ex_new_index(3),
SSL_get_fd(3), SSL_get_peer_cert_chain(3), SSL_get_rbio(3),
SSL_get_session(3), SSL_get_verify_result(3), SSL_get_version(3),
SSL_library_init(3), SSL_load_client_CA_file(3), SSL_new(3),
SSL_pending(3), SSL_read(3), SSL_rstate_string(3),
SSL_session_reused(3), SSL_set_bio(3), SSL_set_connect_state(3),
SSL_set_fd(3), SSL_set_session(3), SSL_set_shutdown(3),
SSL_shutdown(3), SSL_state_string(3), SSL_want(3), SSL_write(3),
SSL_SESSION_free(3), SSL_SESSION_get_ex_new_index(3),
SSL_SESSION_get_time(3), d2i_SSL_SESSION(3),
SSL_CTX_set_psk_client_callback(3), SSL_CTX_use_psk_identity_hint(3),
SSL_get_psk_identity(3)
HISTORY
The ssl(3) document appeared in OpenSSL 0.9.2
1.0.2h 2016-05-03 ssl(3)
SSL_READ_EARLY_DATA(3) OpenSSL SSL_READ_EARLY_DATA(3)
NAME
SSL_set_max_early_data, SSL_CTX_set_max_early_data,
SSL_get_max_early_data, SSL_CTX_get_max_early_data,
SSL_set_recv_max_early_data, SSL_CTX_set_recv_max_early_data,
SSL_get_recv_max_early_data, SSL_CTX_get_recv_max_early_data,
SSL_SESSION_get_max_early_data, SSL_SESSION_set_max_early_data,
SSL_write_early_data, SSL_read_early_data, SSL_get_early_data_status,
SSL_allow_early_data_cb_fn, SSL_CTX_set_allow_early_data_cb,
SSL_set_allow_early_data_cb - functions for sending and receiving early
data
SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_early_data);
uint32_t SSL_CTX_get_max_early_data(const SSL_CTX *ctx);
int SSL_set_max_early_data(SSL *s, uint32_t max_early_data);
uint32_t SSL_get_max_early_data(const SSL *s);
int SSL_CTX_set_recv_max_early_data(SSL_CTX *ctx, uint32_t recv_max_early_data);
uint32_t SSL_CTX_get_recv_max_early_data(const SSL_CTX *ctx);
int SSL_set_recv_max_early_data(SSL *s, uint32_t recv_max_early_data);
uint32_t SSL_get_recv_max_early_data(const SSL *s);
uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s);
int SSL_SESSION_set_max_early_data(SSL_SESSION *s, uint32_t max_early_data);
int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written);
int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes);
int SSL_get_early_data_status(const SSL *s);
typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg);
void SSL_CTX_set_allow_early_data_cb(SSL_CTX *ctx,
SSL_allow_early_data_cb_fn cb,
void *arg);
void SSL_set_allow_early_data_cb(SSL *s,
SSL_allow_early_data_cb_fn cb,
void *arg);
DESCRIPTION
These functions are used to send and receive early data where TLSv1.3
has been negotiated. Early data can be sent by the client immediately
after its initial ClientHello without having to wait for the server to
complete the handshake. Early data can be sent if a session has
previously been established with the server or when establishing a new
session using an out-of-band PSK, and only when the server is known to
support it. Additionally these functions can be used to send data from
the server to the client when the client has not yet completed the
authentication stage of the handshake.
Early data has weaker security properties than other data sent over an
SSL/TLS connection. In particular the data does not have forward
secrecy. There are also additional considerations around replay attacks
(see "REPLAY PROTECTION" below). For these reasons extreme care should
be exercised when using early data. For specific details, consult the
TLS 1.3 specification.
When a server receives early data it may opt to immediately respond by
sending application data back to the client. Data sent by the server at
this stage is done before the full handshake has been completed.
Specifically the client's authentication messages have not yet been
received, i.e. the client is unauthenticated at this point and care
should be taken when using this capability.
A server or client can determine whether the full handshake has been
completed or not by calling SSL_is_init_finished(3).
On the client side, the function SSL_SESSION_get_max_early_data() can
be used to determine if a session established with a server can be used
to send early data. If the session cannot be used then this function
will return 0. Otherwise it will return the maximum number of early
data bytes that can be sent.
The function SSL_SESSION_set_max_early_data() sets the maximum number
of early data bytes that can be sent for a session. This would
typically be used when creating a PSK session file (see
SSL_CTX_set_psk_use_session_callback(3)). If using a ticket based PSK
then this is set automatically to the value provided by the server.
A client uses the function SSL_write_early_data() to send early data.
This function is similar to the SSL_write_ex(3) function, but with the
following differences. See SSL_write_ex(3) for information on how to
write bytes to the underlying connection, and how to handle any errors
that may arise. This page describes the differences between
SSL_write_early_data() and SSL_write_ex(3).
When called by a client, SSL_write_early_data() must be the first IO
function called on a new connection, i.e. it must occur before any
calls to SSL_write_ex(3), SSL_read_ex(3), SSL_connect(3),
SSL_do_handshake(3) or other similar functions. It may be called
multiple times to stream data to the server, but the total number of
bytes written must not exceed the value returned from
SSL_SESSION_get_max_early_data(). Once the initial
SSL_write_early_data() call has completed successfully the client may
interleave calls to SSL_read_ex(3) and SSL_read(3) with calls to
SSL_write_early_data() as required.
If SSL_write_early_data() fails you should call SSL_get_error(3) to
determine the correct course of action, as for SSL_write_ex(3).
When the client no longer wishes to send any more early data then it
should complete the handshake by calling a function such as
SSL_connect(3) or SSL_do_handshake(3). Alternatively you can call a
standard write function such as SSL_write_ex(3), which will
transparently complete the connection and write the requested data.
A server may choose to ignore early data that has been sent to it. Once
the connection has been completed you can determine whether the server
accepted or rejected the early data by calling
SSL_get_early_data_status(). This will return SSL_EARLY_DATA_ACCEPTED
if the data was accepted, SSL_EARLY_DATA_REJECTED if it was rejected or
SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function may be
called by either the client or the server.
A server uses the SSL_read_early_data() function to receive early data
on a connection for which early data has been enabled using
SSL_CTX_set_max_early_data() or SSL_set_max_early_data(). As for
SSL_write_early_data(), this must be the first IO function called on a
connection, i.e. it must occur before any calls to SSL_write_ex(3),
SSL_read_ex(3), SSL_accept(3), SSL_do_handshake(3), or other similar
functions.
SSL_read_early_data() is similar to SSL_read_ex(3) with the following
differences. Refer to SSL_read_ex(3) for full details.
SSL_read_early_data() may return 3 possible values:
SSL_READ_EARLY_DATA_ERROR
This indicates an IO or some other error occurred. This should be
treated in the same way as a 0 return value from SSL_read_ex(3).
SSL_READ_EARLY_DATA_SUCCESS
This indicates that early data was successfully read. This should
be treated in the same way as a 1 return value from SSL_read_ex(3).
You should continue to call SSL_read_early_data() to read more
data.
SSL_READ_EARLY_DATA_FINISH
This indicates that no more early data can be read. It may be
returned on the first call to SSL_read_early_data() if the client
has not sent any early data, or if the early data was rejected.
Once the initial SSL_read_early_data() call has completed successfully
(i.e. it has returned SSL_READ_EARLY_DATA_SUCCESS or
SSL_READ_EARLY_DATA_FINISH) then the server may choose to write data
immediately to the unauthenticated client using SSL_write_early_data().
If SSL_read_early_data() returned SSL_READ_EARLY_DATA_FINISH then in
some situations (e.g. if the client only supports TLSv1.2) the
handshake may have already been completed and calls to
SSL_write_early_data() are not allowed. Call SSL_is_init_finished(3) to
determine whether the handshake has completed or not. If the handshake
is still in progress then the server may interleave calls to
SSL_write_early_data() with calls to SSL_read_early_data() as required.
Servers must not call SSL_read_ex(3), SSL_read(3), SSL_write_ex(3) or
SSL_write(3) until SSL_read_early_data() has returned with
SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the
client still needs to be completed. Complete the connection by calling
a function such as SSL_accept(3) or SSL_do_handshake(3). Alternatively
you can call a standard read function such as SSL_read_ex(3), which
will transparently complete the connection and read the requested data.
Note that it is an error to attempt to complete the connection before
SSL_read_early_data() has returned SSL_READ_EARLY_DATA_FINISH.
Only servers may call SSL_read_early_data().
Calls to SSL_read_early_data() may, in certain circumstances, complete
the connection immediately without further need to call a function such
as SSL_accept(3). This can happen if the client is using a protocol
version less than TLSv1.3. Applications can test for this by calling
SSL_is_init_finished(3). Alternatively, applications may choose to call
SSL_accept(3) anyway. Such a call will successfully return immediately
with no further action taken.
When a session is created between a server and a client the server will
specify the maximum amount of any early data that it will accept on any
future connection attempt. By default the server does not accept early
data; a server may indicate support for early data by calling
SSL_CTX_set_max_early_data() or SSL_set_max_early_data() to set it for
the whole SSL_CTX or an individual SSL object respectively. The
max_early_data parameter specifies the maximum amount of early data in
bytes that is permitted to be sent on a single connection. Similarly
the SSL_CTX_get_max_early_data() and SSL_get_max_early_data() functions
can be used to obtain the current maximum early data settings for the
SSL_CTX and SSL objects respectively. Generally a server application
will either use both of SSL_read_early_data() and
SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither
of them, since there is no practical benefit from using only one of
them. If the maximum early data setting for a server is nonzero then
replay protection is automatically enabled (see "REPLAY PROTECTION"
below).
If the server rejects the early data sent by a client then it will skip
over the data that is sent. The maximum amount of received early data
that is skipped is controlled by the recv_max_early_data setting. If a
client sends more than this then the connection will abort. This value
can be set by calling SSL_CTX_set_recv_max_early_data() or
SSL_set_recv_max_early_data(). The current value for this setting can
be obtained by calling SSL_CTX_get_recv_max_early_data() or
SSL_get_recv_max_early_data(). The default value for this setting is
16,384 bytes.
The recv_max_early_data value also has an impact on early data that is
accepted. The amount of data that is accepted will always be the lower
of the max_early_data for the session and the recv_max_early_data
setting for the server. If a client sends more data than this then the
connection will abort.
The configured value for max_early_data on a server may change over
time as required. However, clients may have tickets containing the
previously configured max_early_data value. The recv_max_early_data
should always be equal to or higher than any recently configured
max_early_data value in order to avoid aborted connections. The
recv_max_early_data should never be set to less than the current
configured max_early_data value.
Some server applications may wish to have more control over whether
early data is accepted or not, for example to mitigate replay risks
(see "REPLAY PROTECTION" below) or to decline early_data when the
server is heavily loaded. The functions
SSL_CTX_set_allow_early_data_cb() and SSL_set_allow_early_data_cb() set
a callback which is called at a point in the handshake immediately
before a decision is made to accept or reject early data. The callback
is provided with a pointer to the user data argument that was provided
when the callback was first set. Returning 1 from the callback will
allow early data and returning 0 will reject it. Note that the OpenSSL
library may reject early data for other reasons in which case this
callback will not get called. Notably, the built-in replay protection
feature will still be used even if a callback is present unless it has
been explicitly disabled using the SSL_OP_NO_ANTI_REPLAY option. See
"REPLAY PROTECTION" below.
NOTES
The whole purpose of early data is to enable a client to start sending
data to the server before a full round trip of network traffic has
occurred. Application developers should ensure they consider
optimisation of the underlying TCP socket to obtain a performant
solution. For example Nagle's algorithm is commonly used by operating
systems in an attempt to avoid lots of small TCP packets. In many
scenarios this is beneficial for performance, but it does not work well
with the early data solution as implemented in OpenSSL. In Nagle's
algorithm the OS will buffer outgoing TCP data if a TCP packet has
already been sent which we have not yet received an ACK for from the
peer. The buffered data will only be transmitted if enough data to fill
an entire TCP packet is accumulated, or if the ACK is received from the
peer. The initial ClientHello will be sent in the first TCP packet
along with any data from the first call to SSL_write_early_data(). If
the amount of data written will exceed the size of a single TCP packet,
or if there are more calls to SSL_write_early_data() then that
additional data will be sent in subsequent TCP packets which will be
buffered by the OS and not sent until an ACK is received for the first
packet containing the ClientHello. This means the early data is not
actually sent until a complete round trip with the server has occurred
which defeats the objective of early data.
In many operating systems the TCP_NODELAY socket option is available to
disable Nagle's algorithm. If an application opts to disable Nagle's
algorithm consideration should be given to turning it back on again
after the handshake is complete if appropriate.
In rare circumstances, it may be possible for a client to have a
session that reports a max early data value greater than 0, but where
the server does not support this. For example, this can occur if a
server has had its configuration changed to accept a lower max early
data value such as by calling SSL_CTX_set_recv_max_early_data().
Another example is if a server used to support TLSv1.3 but was later
downgraded to TLSv1.2. Sending early data to such a server will cause
the connection to abort. Clients that encounter an aborted connection
while sending early data may want to retry the connection without
sending early data as this does not happen automatically. A client will
have to establish a new transport layer connection to the server and
attempt the SSL/TLS connection again but without sending early data.
Note that it is inadvisable to retry with a lower maximum protocol
version.
REPLAY PROTECTION
When early data is in use the TLS protocol provides no security
guarantees that the same early data was not replayed across multiple
connections. As a mitigation for this issue OpenSSL automatically
enables replay protection if the server is configured with a nonzero
max early data value. With replay protection enabled sessions are
forced to be single use only. If a client attempts to reuse a session
ticket more than once, then the second and subsequent attempts will
fall back to a full handshake (and any early data that was submitted
will be ignored). Note that single use tickets are enforced even if a
client does not send any early data.
The replay protection mechanism relies on the internal OpenSSL server
session cache (see SSL_CTX_set_session_cache_mode(3)). When replay
protection is being used the server will operate as if the
SSL_OP_NO_TICKET option had been selected (see SSL_CTX_set_options(3)).
Sessions will be added to the cache whenever a session ticket is
issued. When a client attempts to resume the session, OpenSSL will
check for its presence in the internal cache. If it exists then the
resumption is allowed and the session is removed from the cache. If it
does not exist then the resumption is not allowed and a full handshake
will occur.
Note that some applications may maintain an external cache of sessions
(see SSL_CTX_sess_set_new_cb(3) and similar functions). It is the
application's responsibility to ensure that any sessions in the
external cache are also populated in the internal cache and that once
removed from the internal cache they are similarly removed from the
external cache. Failing to do this could result in an application
becoming vulnerable to replay attacks. Note that OpenSSL will lock the
internal cache while a session is removed but that lock is not held
when the remove session callback (see SSL_CTX_sess_set_remove_cb(3)) is
called. This could result in a small amount of time where the session
has been removed from the internal cache but is still available in the
external cache. Applications should be designed with this in mind in
order to minimise the possibility of replay attacks.
The OpenSSL replay protection does not apply to external Pre Shared
Keys (PSKs) (e.g. see SSL_CTX_set_psk_find_session_callback(3)).
Therefore, extreme caution should be applied when combining external
PSKs with early data.
Some applications may mitigate the replay risks in other ways. For
those applications it is possible to turn off the built-in replay
protection feature using the SSL_OP_NO_ANTI_REPLAY option. See
SSL_CTX_set_options(3) for details. Applications can also set a
callback to make decisions about accepting early data or not. See
SSL_CTX_set_allow_early_data_cb() above for details.
RETURN VALUES
SSL_write_early_data() returns 1 for success or 0 for failure. In the
event of a failure call SSL_get_error(3) to determine the correct
course of action.
SSL_read_early_data() returns SSL_READ_EARLY_DATA_ERROR for failure,
SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and
SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In
the event of a failure call SSL_get_error(3) to determine the correct
course of action.
SSL_get_max_early_data(), SSL_CTX_get_max_early_data() and
SSL_SESSION_get_max_early_data() return the maximum number of early
data bytes that may be sent.
SSL_set_max_early_data(), SSL_CTX_set_max_early_data() and
SSL_SESSION_set_max_early_data() return 1 for success or 0 for failure.
SSL_get_early_data_status() returns SSL_EARLY_DATA_ACCEPTED if early
data was accepted by the server, SSL_EARLY_DATA_REJECTED if early data
was rejected by the server, or SSL_EARLY_DATA_NOT_SENT if no early data
was sent.
SEE ALSO
SSL_get_error(3), SSL_write_ex(3), SSL_read_ex(3), SSL_connect(3),
SSL_accept(3), SSL_do_handshake(3),
SSL_CTX_set_psk_use_session_callback(3), ssl(7)
HISTORY
All of the functions described above were added in OpenSSL 1.1.1.
COPYRIGHT
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
1.1.1v 2023-08-01 SSL_READ_EARLY_DATA(3)