initialize TLS client and server
struct tls_config *
const char *
tls family of functions establishes a
secure communications channel using the TLS socket protocol. Both clients
and servers are supported.
function initializes global data structures. It is no longer necessary to
call this function directly, since it is invoked internally when needed. It
may be called more than once, and may be called concurrently.
Before a connection is created, a
configuration must be created. The
function allocates, initializes, and returns a new default configuration
object that can be used for future connections. Several functions exist to
change the options of the configuration; see
function may be used to retrieve a string containing more information about
the most recent error relating to a configuration.
A TLS connection object is created by tls_client(3) or tls_server(3) and configured with tls_configure(3).
A client connection is initiated after configuration by calling tls_connect(3). A server can accept a new client connection by calling tls_accept_socket(3) on an already established socket connection.
Two functions are provided for input and output, tls_read(3) and tls_write(3). Both automatically perform the tls_handshake(3) when needed.
The properties of established TLS connections can be inspected with the functions described in tls_conn_version(3) and tls_ocsp_process_response(3).
After use, a TLS connection should be closed with tls_close(3) and then freed by calling tls_free(3).
When no more contexts are to be configured,
the configuration object should be freed by calling
It is safe to call
tls_config_free() as soon as the
final call to
has been made. If config is
NULL, no action occurs.
tls_init() returns 0 on success or -1 on
NULL on error or an out of memory condition.
NULL if no error occurred with
config at all, or if memory allocation failed while
trying to assemble the string describing the most recent error related to
tls_accept_socket(3), tls_client(3), tls_config_ocsp_require_stapling(3), tls_config_set_protocols(3), tls_config_verify(3), tls_conn_version(3), tls_connect(3), tls_load_file(3), tls_ocsp_process_response(3), tls_read(3)
tls API first appeared in
OpenBSD 5.6 as a response to the unnecessary
challenges other APIs present in order to use them safely.
All functions were renamed from
tls_*() for OpenBSD
tls_config_error() appeared in
Ted Unangst <firstname.lastname@example.org>
Many others contributed to various parts of the library; see the individual manual pages for more information.
tls_config_error() returns an
internal pointer. It must not be freed by the application, or a double free
error will occur. The pointer will become invalid when the next error occurs
with config. Consequently, if the application may need
the message at a later time, it has to copy the string before calling the
function involving config, or a segmentation fault or
read access to unintended data is the likely result.