OpenBSD manual page server

Manual Page Search Parameters

SSL(3) Library Functions Manual SSL(3)

SSLOpenSSL 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 is a core part of the SSL/TLS protocol. The available ciphers are configured on an 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 lifetime 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.

Currently the OpenSSL ssl library provides the following C header files containing the prototypes for the data structures 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 library. Whenever you need hardcore 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.

The functions that the OpenSSL ssl library exports are documented below:

Here we document the various API functions which deal with the SSL/TLS protocol methods defined in SSL_METHOD structures.

const SSL_METHOD * (void)
Constructor for the SSLv2 SSL_METHOD structure for a dedicated client.
const SSL_METHOD * (void)
Constructor for the SSLv2 SSL_METHOD structure for a dedicated server.
const SSL_METHOD * (void)
Constructor for the SSLv2 SSL_METHOD structure for combined client and server.
const SSL_METHOD * (void)
Constructor for the SSLv3 SSL_METHOD structure for a dedicated client.
const SSL_METHOD * (void)
Constructor for the SSLv3 SSL_METHOD structure for a dedicated server.
const SSL_METHOD * (void)
Constructor for the SSLv3 SSL_METHOD structure for combined client and server.
const SSL_METHOD * (void)
Constructor for the TLSv1 SSL_METHOD structure for a dedicated client.
const SSL_METHOD * (void)
Constructor for the TLSv1 SSL_METHOD structure for a dedicated server.
const SSL_METHOD * (void)
Constructor for the TLSv1 SSL_METHOD structure for combined client and server.

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

char * (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 *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 *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 *cipher)
Returns a string like Qq TLSv1/SSLv3 or Qq SSLv2 which indicates the SSL/TLS protocol version to which cipher belongs (i.e., where it was defined in the specification the first time).

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

int (SSL_CTX *ctx, X509 *x)
 
long (SSL_CTX *ctx, X509 *x509)
 
int (SSL_CTX *ctx, SSL_SESSION *c)
 
int (const SSL_CTX *ctx)
 
long (SSL_CTX *ctx, int cmd, long larg, char *parg)
 
void (SSL_CTX *s, long t)
 
void (SSL_CTX *a)
 
char * (SSL_CTX *ctx)
 
X509_STORE * (SSL_CTX *ctx)
 
STACK * (const SSL_CTX *ctx)
 
int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))() SSL *ssl X509 **x509 EVP_PKEY **pkey
 
char * (const SSL_CTX *s, int idx)
 
int (long argl, void *argp, CRYPTO_EX_new *new_func, CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
 
void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(SSL *ssl, int cb, int ret);
 
int (const SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
long (const SSL_CTX *ctx)
 
int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx, char *CAfile, char *CApath)
 
long (SSL_CTX *ctx)
 
SSL_CTX * (const SSL_METHOD *meth)
 
int (SSL_CTX *ctx, SSL_SESSION *c)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
int (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 *ctx)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *ctx)
 
void (SSL_CTX *ctx, long t)
 
void (SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));
 
void (SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));
 
void (SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));
 
int (SSL_CTX *ctx)
 
LHASH * (SSL_CTX *ctx)
 
void (SSL_CTX *ctx, void *arg)
 
void (SSL_CTX *ctx, X509_STORE *cs)
 
void (SSL_CTX *ctx, int (*cb)(), char *arg)
 
int (SSL_CTX *ctx, char *str)
 
void (SSL_CTX *ctx, STACK *list)
 
void (SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
 
void (SSL_CTX *ctx, pem_password_cb *cb)
 
void (SSL_CTX *ctx, int m)
 
int (SSL_CTX *ctx)
 
int (SSL_CTX *s, int idx, char *arg)
 
void (SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));
 
void (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 *ctx, void *arg)
 
void (SSL_CTX *ctx, unsigned long op)
 
void (SSL_CTX *ctx, int mode)
 
void (SSL_CTX *ctx, int mode)
 
int (SSL_CTX *ctx, const SSL_METHOD *meth)
 
void (SSL_CTX *ctx, long t)
 
long (SSL_CTX* ctx, DH *dh)
 
long (SSL_CTX *ctx, DH *(*cb)(void))
 
long (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.

()
long SSL_set_tmp_rsa_callback(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength));

The same as (), except it operates on an SSL session instead of a context.

void (SSL_CTX *ctx, int mode, int (*cb)(void))
 
int (SSL_CTX *ctx, EVP_PKEY *pkey)
 
int (int type, SSL_CTX *ctx, unsigned char *d, long len);
 
int (SSL_CTX *ctx, char *file, int type)
 
int (SSL_CTX *ctx, RSA *rsa)
 
int (SSL_CTX *ctx, unsigned char *d, long len)
 
int (SSL_CTX *ctx, char *file, int type)
 
int (SSL_CTX *ctx, X509 *x)
 
int (SSL_CTX *ctx, int len, unsigned char *d)
 
int (SSL_CTX *ctx, char *file, int type)
 
void (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 *ctx, const char *hint)
 
void (SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
 

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

int (const SSL_SESSION *a, const SSL_SESSION *b)
 
void (SSL_SESSION *ss)
 
char * (SSL_SESSION *s)
 
char * (const SSL_SESSION *s, int idx)
 
int (long argl, char *argp, int (*new_func)(void), int (*dup_func)(void), void (*free_func)(void));
 
long (const SSL_SESSION *s)
 
long (const SSL_SESSION *s)
 
unsigned long (const SSL_SESSION *a)
 
SSL_SESSION * (void)
 
int (BIO *bp, const SSL_SESSION *x)
 
int (FILE *fp, const SSL_SESSION *x)
 
void (SSL_SESSION *s, char *a)
 
int (SSL_SESSION *s, int idx, char *arg)
 
long (SSL_SESSION *s, long t)
 
long (SSL_SESSION *s, long t)
 

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

int (SSL *ssl)
 
int (STACK *stack, const char *dir)
 
int (STACK *stack, const char *file)
 
int (SSL *ssl, X509 *x)
 
char * (int value)
 
char * (int value)
 
char * (int value)
 
char * (int value)
 
int (const SSL *ssl)
 
void (SSL *ssl)
 
long (SSL *ssl)
 
int (SSL *ssl)
 
void (SSL *t, const SSL *f)
 
long (SSL *ssl, int cmd, long larg, char *parg)
 
int (SSL *ssl)
 
SSL * (SSL *ssl)
 
STACK * (STACK *sk)
 
void (SSL *ssl)
 
SSL_CTX * (const SSL *ssl)
 
char * (SSL *ssl)
 
X509 * (const SSL *ssl)
 
const char * (const SSL *ssl)
 
int (const SSL *ssl, int *alg_bits)
 
char * (const SSL *ssl, int n)
 
char * (const SSL *ssl)
 
char * (const SSL *ssl)
 
STACK * (const SSL *ssl)
 
STACK * (const SSL *ssl)
 
SSL_CIPHER * (SSL *ssl)
 
long (const SSL *ssl)
 
int (const SSL *ssl, int i)
 
char * (const SSL *ssl, int idx)
 
int (void)
 
int (long argl, char *argp, int (*new_func)(void), int (*dup_func)(void), void (*free_func)(void));
 
int (const SSL *ssl)
 
void (*SSL_get_info_callback(const SSL *ssl))()
 
STACK * (const SSL *ssl)
 
X509 * (const SSL *ssl)
 
EVP_PKEY * (SSL *ssl)
 
int (const SSL *ssl)
 
BIO * (const SSL *ssl)
 
int (const SSL *ssl)
 
SSL_SESSION * (const SSL *ssl)
 
char * (const SSL *ssl, char *buf, int len)
 
int (const SSL *ssl)
 
const SSL_METHOD * (SSL *ssl)
 
int (const SSL *ssl)
 
long (const SSL *ssl)
 
long (const SSL *ssl)
 
int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *)
 
int (const SSL *ssl)
 
long (const SSL *ssl)
 
char * (const SSL *ssl)
 
BIO * (const SSL *ssl)
 
int (SSL *ssl)
 
int (SSL *ssl)
 
int (SSL *ssl)
 
int (SSL *ssl)
 
int (SSL *ssl)
 
STACK * (char *file)
 
void (void)
 
SSL * (SSL_CTX *ctx)
 
long (SSL *ssl)
 
int (SSL *ssl, void *buf, int num)
 
int (const SSL *ssl)
 
int (SSL *ssl, void *buf, int num)
 
int (SSL *ssl)
 
char * (SSL *ssl)
 
char * (SSL *ssl)
 
long (SSL *ssl)
 
void (SSL *ssl)
 
void (SSL *ssl, char *arg)
 
void (SSL *ssl, BIO *rbio, BIO *wbio)
 
int (SSL *ssl, char *str)
 
void (SSL *ssl, STACK *list)
 
void (SSL *ssl)
 
int (SSL *ssl, int idx, char *arg)
 
int (SSL *ssl, int fd)
 
void (SSL *ssl, void (*cb)(void))
 
void (SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
 
void (SSL *ctx, void *arg)
 
void (SSL *ssl, unsigned long op)
 
void (SSL *ssl, int mode)
 
void (SSL *ssl, int yes)
 
int (SSL *ssl, int fd)
 
int (SSL *ssl, SSL_SESSION *session)
 
void (SSL *ssl, int mode)
 
int (SSL *ssl, const SSL_METHOD *meth)
 
void (SSL *ssl, long t)
 
void (SSL *ssl, long t)
 
void (SSL *ssl, int mode, int (*callback)(void))
 
void (SSL *ssl, long arg)
 
int (SSL *ssl, int fd)
 
int (SSL *ssl)
 
int (const SSL *ssl)
 
char * (const SSL *ssl)
 
char * (const SSL *ssl)
 
long (SSL *ssl)
 
int (SSL *ssl, EVP_PKEY *pkey)
 
int (int type, SSL *ssl, unsigned char *d, long len)
 
int (SSL *ssl, char *file, int type)
 
int (SSL *ssl, RSA *rsa)
 
int (SSL *ssl, unsigned char *d, long len)
 
int (SSL *ssl, char *file, int type)
 
int (SSL *ssl, X509 *x)
 
int (SSL *ssl, int len, unsigned char *d)
 
int (SSL *ssl, char *file, int type)
 
int (const SSL *ssl)
 
int (const SSL *ssl)
 
int (const SSL *ssl)
 
int (const SSL *ssl)
 
int (const SSL *ssl)
 
int (const SSL *ssl)
 
int (SSL *ssl, const void *buf, int num)
 
void (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 *ssl, const char *hint)
 
void (SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
 
const char * (SSL *ssl)
 
const char * (SSL *ssl)
 

openssl(1), crypto(3), d2i_SSL_SESSION(3), SSL_accept(3), SSL_alert_type_string(3), SSL_CIPHER_get_name(3), SSL_clear(3), SSL_COMP_add_compression_method(3), SSL_connect(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_psk_client_callback(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_dh_callback(3), SSL_CTX_set_tmp_rsa_callback(3), SSL_CTX_set_verify(3), SSL_CTX_use_certificate(3), SSL_CTX_use_psk_identity_hint(3), SSL_do_handshake(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_psk_identity(3), SSL_get_rbio(3), SSL_get_session(3), SSL_get_SSL_CTX(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_free(3), SSL_SESSION_get_ex_new_index(3), SSL_SESSION_get_time(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)

The SSL document appeared in OpenSSL 0.9.2.

December 2, 2014 OpenBSD-5.7