Manual Page Search Parameters

TLS_INIT(3) Library Functions Manual TLS_INIT(3)


tls_init, tls_config_new, tls_config_free, tls_config_errorinitialize TLS client and server API


#include <tls.h>
struct tls_config *
tls_config_free(struct tls_config *config);
const char *
tls_config_error(struct tls_config *config);


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 should be called once before any other functions. It may be called more than once, but not 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.


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.


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)


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.


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.


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.
May 6, 2017 OpenBSD-current