ssl(3) - OpenBSD manual pages

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 *SSLv2_client_method(void);: Constructor for the SSLv2 SSL_METHOD structure for a dedicated client.
const SSL_METHOD *SSLv2_server_method(void);: Constructor for the SSLv2 SSL_METHOD structure for a dedicated server.
const SSL_METHOD *SSLv2_method(void);: Constructor for the SSLv2 SSL_METHOD structure for combined client and server.
const SSL_METHOD *SSLv3_client_method(void);: Constructor for the SSLv3 SSL_METHOD structure for a dedicated client.
const SSL_METHOD *SSLv3_server_method(void);: Constructor for the SSLv3 SSL_METHOD structure for a dedicated server.
const SSL_METHOD *SSLv3_method(void);: Constructor for the SSLv3 SSL_METHOD structure for combined client and server.
const SSL_METHOD *TLSv1_client_method(void);: Constructor for the TLSv1 SSL_METHOD structure for a dedicated client.
const SSL_METHOD *TLSv1_server_method(void);: Constructor for the TLSv1 SSL_METHOD structure for a dedicated server.
const SSL_METHOD *TLSv1_method(void);: 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 *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).