ssl
NAME SYNOPSIS DESCRIPTION DATA STRUCTURES HEADER FILES API FUNCTIONS SEE ALSO HISTORY
SSL - OpenSSL SSL/TLS library
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.
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_CIPHER s, 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.
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.
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.
SSL_METHOD
Constructor for the SSLv2 SSL_METHOD structure for a dedicated client.
SSL_METHOD
Constructor for the SSLv2 SSL_METHOD structure for a dedicated server.
SSL_METHOD
Constructor for the SSLv2 SSL_METHOD structure for combined client and server.
SSL_METHOD
Constructor for the SSLv3 SSL_METHOD structure for a dedicated client.
SSL_METHOD
Constructor for the SSLv3 SSL_METHOD structure for a dedicated server.
SSL_METHOD
Constructor for the SSLv3 SSL_METHOD structure for combined client and server.
SSL_METHOD
Constructor for the TLSv1 SSL_METHOD structure for a dedicated client.
SSL_METHOD
Constructor for the TLSv1 SSL_METHOD structure for a dedicated server.
SSL_METHOD
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.
char *SSL_CIPHER_description( SSL_CIPHER
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
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
Returns a string like TLSv1/SSLv3`` or SSLv2 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
long SSL_CTX_add_extra_chain_cert( SSL_CTX
int SSL_CTX_add_session( SSL_CTX
int SSL_CTX_check_private_key( SSL_CTX
long SSL_CTX_ctrl( SSL_CTX *ctx, int cmd, long larg, char *parg);
void SSL_CTX_flush_sessions( SSL_CTX
void SSL_CTX_free( SSL_CTX
char *SSL_CTX_get_app_data( SSL_CTX
X509_STORE *SSL_CTX_get_cert_store( SSL_CTX *ctx);
STACK *SSL_CTX_get_client_CA_list( SSL_CTX
int (*SSL_CTX_get_client_cert_cb( SSL_CTX
EVP_PKEY **pkey);
char *SSL_CTX_get_ex_data( SSL_CTX
int SSL_CTX_get_ex_new_index(long argl, char
(*free_func)(void))
void (*SSL_CTX_get_info_callback( SSL_CTX
ret);
int SSL_CTX_get_quiet_shutdown( SSL_CTX
int SSL_CTX_get_session_cache_mode( SSL_CTX *ctx);
long SSL_CTX_get_timeout( SSL_CTX
int (*SSL_CTX_get_verify_callback( SSL_CTX
int SSL_CTX_get_verify_mode( SSL_CTX
int SSL_CTX_load_verify_locations( SSL_CTX
long SSL_CTX_need_tmp_RSA( SSL_CTX
SSL_CTX *SSL_CTX_new( SSL_METHOD
int SSL_CTX_remove_session( SSL_CTX
int SSL_CTX_sess_accept( SSL_CTX
int SSL_CTX_sess_accept_good( SSL_CTX
int SSL_CTX_sess_accept_renegotiate( SSL_CTX *ctx);
int SSL_CTX_sess_cache_full( SSL_CTX
int SSL_CTX_sess_cb_hits( SSL_CTX
int SSL_CTX_sess_connect( SSL_CTX
int SSL_CTX_sess_connect_good( SSL_CTX
int SSL_CTX_sess_connect_renegotiate( SSL_CTX *ctx);
int SSL_CTX_sess_get_cache_size( SSL_CTX
SSL_SESSION (SSL_CTX_sess_get_get_cb( SSL_CTX *ctx))( SSL *ssl, unsigned char
int (*SSL_CTX_sess_get_new_cb( SSL_CTX
void (*SSL_CTX_sess_get_remove_cb( SSL_CTX
int SSL_CTX_sess_hits( SSL_CTX
int SSL_CTX_sess_misses( SSL_CTX
int SSL_CTX_sess_number( SSL_CTX
void SSL_CTX_sess_set_cache_size( SSL_CTX
void SSL_CTX_sess_set_get_cb( SSL_CTX
void SSL_CTX_sess_set_new_cb( SSL_CTX
void SSL_CTX_sess_set_remove_cb( SSL_CTX
SSL_SESSION *sess));
int SSL_CTX_sess_timeouts( SSL_CTX
LHASH *SSL_CTX_sessions( SSL_CTX
void SSL_CTX_set_app_data( SSL_CTX
void SSL_CTX_set_cert_store( SSL_CTX
void SSL_CTX_set_cert_verify_cb( SSL_CTX
int SSL_CTX_set_cipher_list( SSL_CTX
void SSL_CTX_set_client_CA_list( SSL_CTX
void SSL_CTX_set_client_cert_cb( SSL_CTX
ctx, int (*cb)( SSL *ssl, X509
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
ret));
void SSL_CTX_set_options( SSL_CTX
void SSL_CTX_set_quiet_shutdown( SSL_CTX
void SSL_CTX_set_session_cache_mode( SSL_CTX *ctx, int mode);
int SSL_CTX_set_ssl_version( SSL_CTX
void SSL_CTX_set_timeout( SSL_CTX
long SSL_CTX_set_tmp_dh(SSL_CTX* ctx, DH
long SSL_CTX_set_tmp_dh_callback( SSL_CTX
long SSL_CTX_set_tmp_rsa( SSL_CTX
SSL_CTX_set_tmp_rsa_callback
long SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx, RSA
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
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
int SSL_CTX_use_!PrivateKey( SSL_CTX
int SSL_CTX_use_!PrivateKey_ASN1(int type, SSL_CTX *ctx, unsigned char *d, long len);
int SSL_CTX_use_!PrivateKey_file( SSL_CTX
int SSL_CTX_use_RSAPrivateKey( SSL_CTX
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
int SSL_CTX_use_certificate_ASN1( SSL_CTX
int SSL_CTX_use_certificate_file( SSL_CTX
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( SSL_SESSION
void SSL_SESSION_free( SSL_SESSION
char *SSL_SESSION_get_app_data( SSL_SESSION *s);
char *SSL_SESSION_get_ex_data( SSL_SESSION
int SSL_SESSION_get_ex_new_index(long argl, char
(*free_func)(void))
long SSL_SESSION_get_time( SSL_SESSION
long SSL_SESSION_get_timeout( SSL_SESSION
unsigned long SSL_SESSION_hash( SSL_SESSION *a);
SSL_SESSION
int SSL_SESSION_print( BIO *bp, SSL_SESSION *x);
int SSL_SESSION_print_fp( FILE
void SSL_SESSION_set_app_data( SSL_SESSION
int SSL_SESSION_set_ex_data( SSL_SESSION
long SSL_SESSION_set_time( SSL_SESSION
long SSL_SESSION_set_timeout( SSL_SESSION
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
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
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( SSL
void SSL_clear( SSL
long SSL_clear_num_renegotiations( SSL
int SSL_connect( SSL
void SSL_copy_session_id( SSL
long SSL_ctrl( SSL *ssl, int cmd, long larg, char *parg);
int SSL_do_handshake( SSL
SSL *SSL_dup( SSL
STACK *SSL_dup_CA_list( STACK
void SSL_free( SSL
SSL_CTX *SSL_get_SSL_CTX( SSL
char *SSL_get_app_data( SSL
X509 *SSL_get_certificate( SSL
const char *SSL_get_cipher( SSL
int SSL_get_cipher_bits( SSL *ssl, int *alg_bits);
char *SSL_get_cipher_list( SSL *ssl, int n);
char *SSL_get_cipher_name( SSL
char *SSL_get_cipher_version( SSL
STACK *SSL_get_ciphers( SSL
STACK *SSL_get_client_CA_list( SSL
SSL_CIPHER *SSL_get_current_cipher( SSL
long SSL_get_default_timeout( SSL
int SSL_get_error( SSL *ssl, int i);
char *SSL_get_ex_data( 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( SSL
void (*SSL_get_info_callback( SSL
STACK *SSL_get_peer_cert_chain( SSL
X509 *SSL_get_peer_certificate( SSL
EVP_PKEY *SSL_get_privatekey( SSL
int SSL_get_quiet_shutdown( SSL
BIO *SSL_get_rbio( SSL
int SSL_get_read_ahead( SSL
SSL_SESSION *SSL_get_session( SSL
char *SSL_get_shared_ciphers( SSL
int SSL_get_shutdown( SSL
SSL_METHOD *SSL_get_ssl_method( SSL
int SSL_get_state( SSL
long SSL_get_time( SSL
long SSL_get_timeout( SSL
int (*SSL_get_verify_callback( SSL
int SSL_get_verify_mode( SSL
long SSL_get_verify_result( SSL
char *SSL_get_version( SSL
BIO *SSL_get_wbio( SSL
int SSL_in_accept_init( SSL
int SSL_in_before( SSL
int SSL_in_connect_init( SSL
int SSL_in_init( SSL
int SSL_is_init_finished( SSL
STACK *SSL_load_client_CA_file(char
void SSL_load_error_strings(void);
SSL *SSL_new( SSL_CTX
long SSL_num_renegotiations( SSL
int SSL_peek( SSL *ssl, void *buf, int num);
int SSL_pending( SSL
int SSL_read( SSL *ssl, void *buf, int num);
int SSL_renegotiate( SSL
char *SSL_rstate_string( SSL
char *SSL_rstate_string_long( SSL
long SSL_session_reused( SSL
void SSL_set_accept_state( SSL
void SSL_set_app_data( SSL *ssl, char
void SSL_set_bio( SSL *ssl, BIO
int SSL_set_cipher_list( SSL *ssl, char *str);
void SSL_set_client_CA_list( SSL
void SSL_set_connect_state( 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_options( SSL *ssl, unsigned long op);
void SSL_set_quiet_shutdown( SSL
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
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
int SSL_state( SSL
char *SSL_state_string( SSL
char *SSL_state_string_long( SSL
long SSL_total_renegotiations( SSL
int SSL_use_!PrivateKey( SSL
int SSL_use_!PrivateKey_ASN1(int type, SSL
int SSL_use_!PrivateKey_file( SSL
int SSL_use_RSAPrivateKey( SSL
int SSL_use_RSAPrivateKey_ASN1( SSL
int SSL_use_RSAPrivateKey_file( SSL
int SSL_use_certificate( SSL *ssl, X509 *x);
int SSL_use_certificate_ASN1( SSL
int SSL_use_certificate_file( SSL
int SSL_version( SSL
int SSL_want( SSL
int SSL_want_nothing( SSL
int SSL_want_read( SSL
int SSL_want_write( SSL
int SSL_want_x509_lookup(s);
int SSL_write( SSL *ssl, const void
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_default_passwd_cb(3), SSL_CTX_set_info_callback(3), SSL_CTX_set_mode(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_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)
The ssl(3) document appeared in OpenSSL 0.9.2
3 pages link to ssl(3):