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