FreeBSD Manual Pages
TLS_INIT(3) FreeBSD Library Functions Manual TLS_INIT(3) 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 in- ternally 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 de- fault configuration object that can be used for future connections. Sev- eral 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 contain- ing more information about the most recent error relating to a configura- tion. 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 de- scribing 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 unneces- sary 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 individ- ual 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. Con- sequently, 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. FreeBSD 13.0 July 9, 2018 FreeBSD 13.0
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | CAVEATS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=tls_init&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>