1.\" $OpenBSD: tls_connect.3,v 1.3 2017/01/28 00:59:36 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: January 28 2017 $ 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. 87.Pp 88The 89.Fn tls_connect_servername 90function has the same behaviour, however the name to use for verification is 91explicitly provided, rather than being inferred from the 92.Ar host 93value. 94.Pp 95An already existing socket can be upgraded to a secure connection by calling 96.Fn tls_connect_socket . 97.Pp 98Alternatively, a secure connection can be established over a pair of existing 99file descriptors by calling 100.Fn tls_connect_fds . 101.Pp 102Calling 103.Fn tls_connect_cbs 104allows read and write callback functions to handle data transfers. 105The specified cb_arg parameter is passed back to the functions, 106and can contain a pointer to any caller-specified data. 107.Sh RETURN VALUES 108These functions return 0 on success or -1 on error. 109.Sh SEE ALSO 110.Xr tls_accept_socket 3 , 111.Xr tls_client 3 , 112.Xr tls_close 3 , 113.Xr tls_config_ocsp_require_stapling 3 , 114.Xr tls_configure 3 , 115.Xr tls_handshake 3 , 116.Xr tls_init 3 117.Sh HISTORY 118.Fn tls_connect 119and 120.Fn tls_connect_socket 121appeared in 122.Ox 5.6 123and got their final names in 124.Ox 5.7 . 125.Pp 126.Fn tls_connect_fds 127and 128.Fn tls_connect_servername 129appeared in 130.Ox 5.7 131and 132.Fn tls_connect_cbs 133in 134.Ox 6.1 . 135.Sh AUTHORS 136.An Joel Sing Aq Mt jsing@openbsd.org 137.An Reyk Floeter Aq Mt reyk@openbsd.org 138.Pp 139.An -nosplit 140.Fn tls_connect_cbs 141was written by 142.An Tobias Pape Aq Mt tobias@netshed.de . 143