Sortix 1.1dev nightly manual
This manual documents Sortix 1.1dev nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
TLS_INIT(3) | 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
Thetls
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
Thetls
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 functiontls_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.July 9, 2018 | Debian |