Scroll to navigation

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:

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.
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.
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.
This is a structure containing the current TLS/SSL session details for a connection: SSL_CIPHERs, client and server certificates, keys, etc.
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:

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

Constructor for the SSLv2 SSL_METHOD structure for a dedicated client.
Constructor for the SSLv2 SSL_METHOD structure for a dedicated server.
Constructor for the SSLv2 SSL_METHOD structure for combined client and server.
Constructor for the SSLv3 SSL_METHOD structure for a dedicated client.
Constructor for the SSLv3 SSL_METHOD structure for a dedicated server.
Constructor for the SSLv3 SSL_METHOD structure for combined client and server.
Constructor for the TLSv1 SSL_METHOD structure for a dedicated client.
Constructor for the TLSv1 SSL_METHOD structure for a dedicated server.
Constructor for the TLSv1 SSL_METHOD structure for combined client and server.

DEALING WITH CIPHERS

Here we document the various API functions which deal with the SSL/TLS ciphers defined in SSL_CIPHER structures.

Write a string to buf (with a maximum size of len) containing a human readable description of cipher. Returns buf.
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).
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.
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.

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

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.

DEALING WITH SESSIONS

Here we document the various API functions which deal with the SSL/TLS sessions defined in the SSL_SESSION structures.

DEALING WITH CONNECTIONS

Here we document the various API functions which deal with the SSL/TLS connection defined in the SSL structure.

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_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

2013-02-11 1.0.1e