1.\" $OpenBSD: tls_init.3,v 1.7 2017/05/06 21:18:48 jsing 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: May 6 2017 $ 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 should be called once before any other functions. 49It may be called more than once, but not concurrently. 50.Pp 51Before a connection is created, a configuration must be created. 52The 53.Fn tls_config_new 54function allocates, initializes, and returns a new default configuration 55object that can be used for future connections. 56Several functions exist to change the options of the configuration; see 57.Xr tls_config_set_protocols 3 , 58.Xr tls_load_file 3 , 59.Xr tls_config_ocsp_require_stapling 3 , 60and 61.Xr tls_config_verify 3 . 62.Pp 63The 64.Fn tls_config_error 65function may be used to retrieve a string containing more information 66about the most recent error relating to a configuration. 67.Pp 68A TLS connection object is created by 69.Xr tls_client 3 70or 71.Xr tls_server 3 72and configured with 73.Xr tls_configure 3 . 74.Pp 75A client connection is initiated after configuration by calling 76.Xr tls_connect 3 . 77A server can accept a new client connection by calling 78.Xr tls_accept_socket 3 79on an already established socket connection. 80.Pp 81Two functions are provided for input and output, 82.Xr tls_read 3 83and 84.Xr tls_write 3 . 85Both automatically perform the 86.Xr tls_handshake 3 87when needed. 88.Pp 89The properties of established TLS connections 90can be inspected with the functions described in 91.Xr tls_conn_version 3 92and 93.Xr tls_ocsp_process_response 3 . 94.Pp 95After use, a TLS connection should be closed with 96.Xr tls_close 3 97and then freed by calling 98.Xr tls_free 3 . 99.Pp 100When no more contexts are to be configured, 101the configuration object should be freed by calling 102.Fn tls_config_free . 103It is safe to call 104.Fn tls_config_free 105as soon as the final call to 106.Fn tls_configure 107has been made. 108If 109.Fa config 110is 111.Dv NULL , 112no action occurs. 113.Sh RETURN VALUES 114.Fn tls_init 115returns 0 on success or -1 on error. 116.Pp 117.Fn tls_config_new 118returns 119.Dv NULL 120on error or an out of memory condition. 121.Pp 122.Fn tls_config_error 123returns 124.Dv NULL 125if no error occurred with 126.Fa config 127at all, or if memory allocation failed while trying to assemble the 128string describing the most recent error related to 129.Fa config . 130.Sh SEE ALSO 131.Xr tls_accept_socket 3 , 132.Xr tls_client 3 , 133.Xr tls_config_ocsp_require_stapling 3 , 134.Xr tls_config_set_protocols 3 , 135.Xr tls_config_verify 3 , 136.Xr tls_conn_version 3 , 137.Xr tls_connect 3 , 138.Xr tls_load_file 3 , 139.Xr tls_ocsp_process_response 3 , 140.Xr tls_read 3 141.Sh HISTORY 142The 143.Nm tls 144API first appeared in 145.Ox 5.6 146as a response to the unnecessary challenges other APIs present in 147order to use them safely. 148.Pp 149All functions were renamed from 150.Fn ressl_* 151to 152.Fn tls_* 153for 154.Ox 5.7 . 155.Pp 156.Fn tls_config_error 157appeared in 158.Ox 6.0 . 159.Sh AUTHORS 160.An Joel Sing Aq Mt jsing@openbsd.org 161.An Ted Unangst Aq Mt tedu@openbsd.org 162.Pp 163Many others contributed to various parts of the library; see the 164individual manual pages for more information. 165.Sh CAVEATS 166The function 167.Fn tls_config_error 168returns an internal pointer. 169It must not be freed by the application, or a double free error 170will occur. 171The pointer will become invalid when the next error occurs with 172.Fa config . 173Consequently, if the application may need the message at a later 174time, it has to copy the string before calling the next 175.Sy libtls 176function involving 177.Fa config , 178or a segmentation fault or read access to unintended data is the 179likely result. 180