1.\" $OpenBSD: tls_init.3,v 1.5 2017/02/20 16:01:15 jmc 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: February 20 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 created, 101the configuration object should be freed by calling 102.Fn tls_config_free . 103.Sh RETURN VALUES 104.Fn tls_init 105returns 0 on success or -1 on error. 106.Pp 107.Fn tls_config_new 108returns 109.Dv NULL 110on error or an out of memory condition. 111.Pp 112.Fn tls_config_error 113returns 114.Dv NULL 115if no error occurred with 116.Fa config 117at all, or if memory allocation failed while trying to assemble the 118string describing the most recent error related to 119.Fa config . 120.Sh SEE ALSO 121.Xr tls_accept_socket 3 , 122.Xr tls_client 3 , 123.Xr tls_config_ocsp_require_stapling 3 , 124.Xr tls_config_set_protocols 3 , 125.Xr tls_config_verify 3 , 126.Xr tls_conn_version 3 , 127.Xr tls_connect 3 , 128.Xr tls_load_file 3 , 129.Xr tls_ocsp_process_response 3 , 130.Xr tls_read 3 131.Sh HISTORY 132The 133.Nm tls 134API first appeared in 135.Ox 5.6 136as a response to the unnecessary challenges other APIs present in 137order to use them safely. 138.Pp 139All functions were renamed from 140.Fn ressl_* 141to 142.Fn tls_* 143for 144.Ox 5.7 . 145.Pp 146.Fn tls_config_error 147appeared in 148.Ox 6.0 . 149.Sh AUTHORS 150.An Joel Sing Aq Mt jsing@openbsd.org 151.An Ted Unangst Aq Mt tedu@openbsd.org 152.Pp 153Many others contributed to various parts of the library; see the 154individual manual pages for more information. 155.Sh CAVEATS 156The function 157.Fn tls_config_error 158returns an internal pointer. 159It must not be freed by the application, or a double free error 160will occur. 161The pointer will become invalid when the next error occurs with 162.Fa config . 163Consequently, if the application may need the message at a later 164time, it has to copy the string before calling the next 165.Sy libtls 166function involving 167.Fa config , 168or a segmentation fault or read access to unintended data is the 169likely result. 170