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