1TLS_INIT(3) BSD Library Functions Manual TLS_INIT(3)
2
4 tls_init, tls_config_new, tls_config_free, tls_config_error — initialize
5 TLS client and server API
6
8 #include <tls.h>
9 int
11 tls_init(void);
12 struct tls_config *
14 tls_config_new(void);
15 void
17 tls_config_free(struct tls_config *config);
18 const char *
20 tls_config_error(struct tls_config *config);
21
23 The tls family of functions establishes a secure communications channel
24 using the TLS socket protocol. Both clients and servers are supported.
25 The tls_init() function initializes global data structures. It is no
27 longer necessary to call this function directly, since it is invoked
28 internally when needed. It may be called more than once, and may be
29 called concurrently.
30 Before a connection is created, a configuration must be created. The
32 tls_config_new() function allocates, initializes, and returns a new
33 default configuration object that can be used for future connections.
34 Several functions exist to change the options of the configuration; see
35 tls_config_set_protocols(3), tls_load_file(3),
36 tls_config_ocsp_require_stapling(3), and tls_config_verify(3).
37 The tls_config_error() function may be used to retrieve a string contain‐
39 ing more information about the most recent error relating to a configura‐
40 tion.
41 A TLS connection object is created by tls_client(3) or tls_server(3) and
43 configured with tls_configure(3).
44 A client connection is initiated after configuration by calling
46 tls_connect(3). A server can accept a new client connection by calling
47 tls_accept_socket(3) on an already established socket connection.
48 Two functions are provided for input and output, tls_read(3) and
50 tls_write(3). Both automatically perform the tls_handshake(3) when
51 needed.
52 The properties of established TLS connections can be inspected with the
54 functions described in tls_conn_version(3) and
55 tls_ocsp_process_response(3).
56 After use, a TLS connection should be closed with tls_close(3) and then
58 freed by calling tls_free(3).
59 When no more contexts are to be configured, the configuration object
61 should be freed by calling tls_config_free(). It is safe to call
62 tls_config_free() as soon as the final call to tls_configure() has been
63 made. If config is NULL, no action occurs.
64
66 tls_init() returns 0 on success or -1 on error.
67 tls_config_new() returns NULL on error or an out of memory condition.
69 tls_config_error() returns NULL if no error occurred with config at all,
71 or if memory allocation failed while trying to assemble the string
72 describing the most recent error related to config.
73
75 tls_accept_socket(3), tls_client(3), tls_config_ocsp_require_stapling(3),
76 tls_config_set_protocols(3), tls_config_verify(3), tls_conn_version(3),
77 tls_connect(3), tls_load_file(3), tls_ocsp_process_response(3),
78 tls_read(3)
79
81 The tls API first appeared in OpenBSD 5.6 as a response to the unneces‐
82 sary challenges other APIs present in order to use them safely.
83 All functions were renamed from ressl_*() to tls_*() for OpenBSD 5.7.
85 tls_config_error() appeared in OpenBSD 6.0.
87
89 Joel Sing <jsing@openbsd.org>
90 Ted Unangst <tedu@openbsd.org>
91 Many others contributed to various parts of the library; see the individ‐
93 ual manual pages for more information.
94
96 The function tls_config_error() returns an internal pointer. It must not
97 be freed by the application, or a double free error will occur. The
98 pointer will become invalid when the next error occurs with config. Con‐
99 sequently, if the application may need the message at a later time, it
100 has to copy the string before calling the next libtls function involving
101 config, or a segmentation fault or read access to unintended data is the
102 likely result.
103BSD July 9, 2018 BSD