NAME

     tls_init, tls_config_new, tls_config_free, tls_config_error — initialize TLS client and
     server API

SYNOPSIS

     #include <tls.h>

     int
     tls_init(void);

     struct tls_config *
     tls_config_new(void);

     void
     tls_config_free(struct tls_config *config);

     const char *
     tls_config_error(struct tls_config *config);

DESCRIPTION

     The tls family of functions establishes a secure communications channel using the TLS socket
     protocol.  Both clients and servers are supported.

     The tls_init() 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 tls_config_new()
     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 tls_config_set_protocols(3), tls_load_file(3),
     tls_config_ocsp_require_stapling(3), and tls_config_verify(3).

     The tls_config_error() 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 tls_config_free().  It is safe to call tls_config_free() as soon as the final call
     to tls_configure() has been made.  If config is NULL, no action occurs.

RETURN VALUES

     tls_init() returns 0 on success or -1 on error.

     tls_config_new() returns NULL on error or an out of memory condition.

     tls_config_error() returns 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 config.

SEE ALSO

     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)

HISTORY

     The 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 ressl_*() to tls_*() for OpenBSD 5.7.

     tls_config_error() appeared in OpenBSD 6.0.

AUTHORS

     Joel Sing <jsing@openbsd.org>
     Ted Unangst <tedu@openbsd.org>

     Many others contributed to various parts of the library; see the individual manual pages for
     more information.

CAVEATS

     The function 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 next libtls function involving
     config, or a segmentation fault or read access to unintended data is the likely result.