1 .\" $OpenBSD: tls_connect.3,v 1.5 2025年07月07日 10:54:00 schwarze Exp $ 2 .\" 3 .\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> 4 .\" Copyright (c) 2014, 2015 Joel Sing <jsing@openbsd.org> 5 .\" Copyright (c) 2016 Brent Cook <bcook@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_CONNECT 3 21 .Os 22 .Sh NAME 23 .Nm tls_connect , 24 .Nm tls_connect_fds , 25 .Nm tls_connect_servername , 26 .Nm tls_connect_socket , 27 .Nm tls_connect_cbs 28 .Nd instruct a TLS client to establish a connection 29 .Sh SYNOPSIS 30 .Lb libtls libssl libcrypto 31 .In tls.h 32 .Ft int 33 .Fo tls_connect 34 .Fa "struct tls *ctx" 35 .Fa "const char *host" 36 .Fa "const char *port" 37 .Fc 38 .Ft int 39 .Fo tls_connect_fds 40 .Fa "struct tls *ctx" 41 .Fa "int fd_read" 42 .Fa "int fd_write" 43 .Fa "const char *servername" 44 .Fc 45 .Ft int 46 .Fo tls_connect_servername 47 .Fa "struct tls *ctx" 48 .Fa "const char *host" 49 .Fa "const char *port" 50 .Fa "const char *servername" 51 .Fc 52 .Ft int 53 .Fo tls_connect_socket 54 .Fa "struct tls *ctx" 55 .Fa "int s" 56 .Fa "const char *servername" 57 .Fc 58 .Ft int 59 .Fo tls_connect_cbs 60 .Fa "struct tls *ctx" 61 .Fa "ssize_t (*tls_read_cb)(struct tls *ctx,\ 62 void *buf, size_t buflen, void *cb_arg)" 63 .Fa "ssize_t (*tls_write_cb)(struct tls *ctx,\ 64 const void *buf, size_t buflen, void *cb_arg)" 65 .Fa "void *cb_arg" 66 .Fa "const char *servername" 67 .Fc 68 .Sh DESCRIPTION 69After creating a TLS client context with 70 .Xr tls_client 3 71and configuring it with 72 .Xr tls_configure 3 , 73a client connection is initiated by calling 74 .Fn tls_connect . 75This function will create a new socket, connect to the specified 76 .Fa host 77and 78 .Fa port , 79and then establish a secure connection. 80The 81 .Fa port 82may be numeric or a service name. 83If it is 84 .Dv NULL , 85then a 86 .Fa host 87of the format "hostname:port" is permitted. 88The name to use for verification is inferred from the 89 .Ar host 90value. 91 .Pp 92The 93 .Fn tls_connect_servername 94function has the same behaviour, however the name to use for verification is 95explicitly provided, for the case where the TLS server name differs from the 96DNS name. 97 .Pp 98An already existing socket can be upgraded to a secure connection by calling 99 .Fn tls_connect_socket . 100 .Pp 101Alternatively, a secure connection can be established over a pair of existing 102file descriptors by calling 103 .Fn tls_connect_fds . 104 .Pp 105Calling 106 .Fn tls_connect_cbs 107allows read and write callback functions to handle data transfers. 108The specified cb_arg parameter is passed back to the functions, 109and can contain a pointer to any caller-specified data. 110 .Sh RETURN VALUES 111These functions return 0 on success or -1 on error. 112 .Sh SEE ALSO 113 .Xr tls_accept_socket 3 , 114 .Xr tls_client 3 , 115 .Xr tls_close 3 , 116 .Xr tls_config_ocsp_require_stapling 3 , 117 .Xr tls_configure 3 , 118 .Xr tls_handshake 3 , 119 .Xr tls_init 3 120 .Sh HISTORY 121 .Fn tls_connect 122and 123 .Fn tls_connect_socket 124appeared in 125 .Ox 5.6 126and got their final names in 127 .Ox 5.7 . 128 .Pp 129 .Fn tls_connect_fds 130and 131 .Fn tls_connect_servername 132appeared in 133 .Ox 5.7 134and 135 .Fn tls_connect_cbs 136in 137 .Ox 6.1 . 138 .Sh AUTHORS 139 .An Joel Sing Aq Mt jsing@openbsd.org 140 .An Reyk Floeter Aq Mt reyk@openbsd.org 141 .Pp 142 .An -nosplit 143 .Fn tls_connect_cbs 144was written by 145 .An Tobias Pape Aq Mt tobias@netshed.de . 146