Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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://www.freebsd.org/cgi/man.cgi?query=tls_config_new&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help