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.

Debian                                            July 9, 2018                                       TLS_INIT(3)