ssl(3) - OpenBSD manual pages

ssl(3) - OpenBSD manual pages
SSL(3)
Library
Functions Manual
SSL(3)
NAME
ssl
OpenSSL TLS library
DESCRIPTION
The
ssl
library implements the Transport
Layer Security (TLS) protocol, the successor to the Secure Sockets Layer
(SSL) protocol.
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
ssl
library functions deal
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. It's needed to create an
SSL_CTX
. See
TLS_method(3)
for constructors.
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_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. At run-time the application usually deals with this structure which
has links to mostly all other structures.
HEADER
FILES
Currently the
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
crypto
library.
Whenever you need hardcore details on the internals of the SSL API, look
inside this header file.
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
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
Ciphers
The following pages describe functions acting on
SSL_CIPHER
objects:
SSL_get_ciphers(3)
SSL_get_current_cipher(3)
SSL_CIPHER_get_name(3)
Protocol
contexts
The following pages describe functions acting on
SSL_CTX
objects.
Constructors and destructors:
SSL_CTX_new(3)
SSL_CTX_set_ssl_version(3)
SSL_CTX_free(3)
Certificate configuration:
SSL_CTX_add_extra_chain_cert(3)
SSL_CTX_get0_certificate(3)
SSL_CTX_load_verify_locations(3)
SSL_CTX_set_cert_store(3)
SSL_CTX_set_cert_verify_callback(3)
SSL_CTX_set_client_cert_cb(3)
SSL_CTX_set_default_passwd_cb(3)
SSL_CTX_set_tlsext_status_cb(3)
Session configuration:
SSL_CTX_add_session(3)
SSL_CTX_flush_sessions(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_session_cache_mode(3)
SSL_CTX_set_timeout(3)
SSL_CTX_set_tlsext_ticket_key_cb(3)
Various configuration:
SSL_CTX_get_ex_new_index(3)
SSL_CTX_set_tlsext_servername_callback(3)
Common
configuration of contexts and connections
The functions on the following pages each come in two variants:
one to directly configure a single
SSL
connection and
another to be called on an
SSL_CTX
object, to set up
defaults for all future
SSL
connections created from
that context.
Protocol and algorithm configuration:
SSL_CTX_set_alpn_select_cb(3)
SSL_CTX_set_cipher_list(3)
SSL_CTX_set_min_proto_version(3)
SSL_CTX_set_options(3)
SSL_CTX_set_security_level(3)
SSL_CTX_set_tlsext_use_srtp(3)
SSL_CTX_set_tmp_dh_callback(3)
SSL_CTX_set1_groups(3)
Certificate configuration:
SSL_CTX_add1_chain_cert(3)
SSL_CTX_get_verify_mode(3)
SSL_CTX_set_client_CA_list(3)
SSL_CTX_set_max_cert_list(3)
SSL_CTX_set_verify(3)
SSL_CTX_use_certificate(3)
SSL_get_client_CA_list(3)
SSL_set1_param(3)
Session configuration:
SSL_CTX_set_generate_session_id(3)
SSL_CTX_set_session_id_context(3)
Various configuration:
SSL_CTX_ctrl(3)
SSL_CTX_set_info_callback(3)
SSL_CTX_set_mode(3)
SSL_CTX_set_msg_callback(3)
SSL_CTX_set_quiet_shutdown(3)
SSL_CTX_set_read_ahead(3)
SSL_set_max_send_fragment(3)
Sessions
The following pages describe functions acting on
SSL_SESSION
objects.
Constructors and destructors:
SSL_SESSION_new(3)
SSL_SESSION_free(3)
Accessors:
SSL_SESSION_get_compress_id(3)
SSL_SESSION_get_ex_new_index(3)
SSL_SESSION_get_id(3)
SSL_SESSION_get_protocol_version(3)
SSL_SESSION_get_time(3)
SSL_SESSION_get0_peer(3)
SSL_SESSION_has_ticket(3)
SSL_SESSION_set1_id_context(3)
Encoding and decoding:
d2i_SSL_SESSION(3)
PEM_read_SSL_SESSION(3)
SSL_SESSION_print(3)
Connections
The following pages describe functions acting on
SSL
connection objects:
Constructors and destructors:
SSL_new(3)
SSL_dup(3)
SSL_free(3)
BIO_f_ssl(3)
To change the configuration:
SSL_clear(3)
SSL_set_SSL_CTX(3)
SSL_copy_session_id(3)
SSL_set_bio(3)
SSL_set_connect_state(3)
SSL_set_fd(3)
SSL_set_session(3)
SSL_set1_host(3)
SSL_set_verify_result(3)
To inspect the configuration:
SSL_get_certificate(3)
SSL_get_default_timeout(3)
SSL_get_ex_new_index(3)
SSL_get_fd(3)
SSL_get_rbio(3)
SSL_get_SSL_CTX(3)
To transmit data:
DTLSv1_listen(3)
SSL_accept(3)
SSL_connect(3)
SSL_do_handshake(3)
SSL_read(3)
SSL_read_early_data(3)
SSL_renegotiate(3)
SSL_shutdown(3)
SSL_write(3)
To inspect the state after a connection is established:
SSL_export_keying_material(3)
SSL_get_client_random(3)
SSL_get_ex_data_X509_STORE_CTX_idx(3)
SSL_get_peer_cert_chain(3)
SSL_get_peer_certificate(3)
SSL_get_server_tmp_key(3)
SSL_get_servername(3)
SSL_get_session(3)
SSL_get_shared_ciphers(3)
SSL_get_verify_result(3)
SSL_get_version(3)
SSL_session_reused(3)
To inspect the state during ongoing communication:
SSL_get_error(3)
SSL_get_shutdown(3)
SSL_get_state(3)
SSL_num_renegotiations(3)
SSL_pending(3)
SSL_rstate_string(3)
SSL_state_string(3)
SSL_want(3)
Utility
functions
SSL_alert_type_string(3)
SSL_dup_CA_list(3)
SSL_load_client_CA_file(3)
Obsolete
functions
OPENSSL_init_ssl(3)
SSL_COMP_get_compression_methods(3)
SSL_CTX_set_tmp_rsa_callback(3)
SSL_library_init(3)
SSL_set_tmp_ecdh(3)
SEE
ALSO
openssl(1)
crypto(3)
tls_init(3)
HISTORY
The
ssl
document appeared in OpenSSL
0.9.2.
OpenBSD-current
August 31, 2024
SSL(3)