1.\" $OpenBSD: tls_init.3,v 1.13 2018/07/09 19:47:20 tb Exp $ 2.\" 3.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> 4.\" Copyright (c) 2016 Joel Sing <jsing@openbsd.org> 5.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd $Mdocdate: July 9 2018 $ 20.Dt TLS_INIT 3 21.Os 22.Sh NAME 23.Nm tls_init , 24.Nm tls_config_new , 25.Nm tls_config_free , 26.Nm tls_config_error 27.Nd initialize TLS client and server API 28.Sh SYNOPSIS 29.In tls.h 30.Ft int 31.Fn tls_init void 32.Ft struct tls_config * 33.Fn tls_config_new void 34.Ft void 35.Fn tls_config_free "struct tls_config *config" 36.Ft const char * 37.Fn tls_config_error "struct tls_config *config" 38.Sh DESCRIPTION 39The 40.Nm tls 41family of functions establishes a secure communications channel 42using the TLS socket protocol. 43Both clients and servers are supported. 44.Pp 45The 46.Fn tls_init 47function initializes global data structures. 48It is no longer necessary to call this function directly, 49since it is invoked internally when needed. 50It may be called more than once, and may be called concurrently. 51.Pp 52Before a connection is created, a configuration must be created. 53The 54.Fn tls_config_new 55function allocates, initializes, and returns a new default configuration 56object that can be used for future connections. 57Several functions exist to change the options of the configuration; see 58.Xr tls_config_set_protocols 3 , 59.Xr tls_load_file 3 , 60.Xr tls_config_ocsp_require_stapling 3 , 61and 62.Xr tls_config_verify 3 . 63.Pp 64The 65.Fn tls_config_error 66function may be used to retrieve a string containing more information 67about the most recent error relating to a configuration. 68.Pp 69A TLS connection object is created by 70.Xr tls_client 3 71or 72.Xr tls_server 3 73and configured with 74.Xr tls_configure 3 . 75.Pp 76A client connection is initiated after configuration by calling 77.Xr tls_connect 3 . 78A server can accept a new client connection by calling 79.Xr tls_accept_socket 3 80on an already established socket connection. 81.Pp 82Two functions are provided for input and output, 83.Xr tls_read 3 84and 85.Xr tls_write 3 . 86Both automatically perform the 87.Xr tls_handshake 3 88when needed. 89.Pp 90The properties of established TLS connections 91can be inspected with the functions described in 92.Xr tls_conn_version 3 93and 94.Xr tls_ocsp_process_response 3 . 95.Pp 96After use, a TLS connection should be closed with 97.Xr tls_close 3 98and then freed by calling 99.Xr tls_free 3 . 100.Pp 101When no more contexts are to be configured, 102the configuration object should be freed by calling 103.Fn tls_config_free . 104It is safe to call 105.Fn tls_config_free 106as soon as the final call to 107.Fn tls_configure 108has been made. 109If 110.Fa config 111is 112.Dv NULL , 113no action occurs. 114.Sh RETURN VALUES 115.Fn tls_init 116returns 0 on success or -1 on error. 117.Pp 118.Fn tls_config_new 119returns 120.Dv NULL 121on error or an out of memory condition. 122.Pp 123.Fn tls_config_error 124returns 125.Dv NULL 126if no error occurred with 127.Fa config 128at all, or if memory allocation failed while trying to assemble the 129string describing the most recent error related to 130.Fa config . 131.Sh SEE ALSO 132.Xr tls_accept_socket 3 , 133.Xr tls_client 3 , 134.Xr tls_config_ocsp_require_stapling 3 , 135.Xr tls_config_set_protocols 3 , 136.Xr tls_config_verify 3 , 137.Xr tls_conn_version 3 , 138.Xr tls_connect 3 , 139.Xr tls_load_file 3 , 140.Xr tls_ocsp_process_response 3 , 141.Xr tls_read 3 142.Sh HISTORY 143The 144.Nm tls 145API first appeared in 146.Ox 5.6 147as a response to the unnecessary challenges other APIs present in 148order to use them safely. 149.Pp 150All functions were renamed from 151.Fn ressl_* 152to 153.Fn tls_* 154for 155.Ox 5.7 . 156.Pp 157.Fn tls_config_error 158appeared in 159.Ox 6.0 . 160.Sh AUTHORS 161.An Joel Sing Aq Mt jsing@openbsd.org 162.An Ted Unangst Aq Mt tedu@openbsd.org 163.Pp 164Many others contributed to various parts of the library; see the 165individual manual pages for more information. 166.Sh CAVEATS 167The function 168.Fn tls_config_error 169returns an internal pointer. 170It must not be freed by the application, or a double free error 171will occur. 172The pointer will become invalid when the next error occurs with 173.Fa config . 174Consequently, if the application may need the message at a later 175time, it has to copy the string before calling the next 176.Sy libtls 177function involving 178.Fa config , 179or a segmentation fault or read access to unintended data is the 180likely result. 181