lib/libtls/man/tls_connect.3

   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
  68 After creating a TLS client context with
  69 .Xr tls_client 3
  70 and configuring it with
  71 .Xr tls_configure 3 ,
  72 a client connection is initiated by calling
  73 .Fn tls_connect .
  74 This function will create a new socket, connect to the specified
  75 .Fa host
  76 and
  77 .Fa port ,
  78 and then establish a secure connection.
  79 The
  80 .Fa port
  81 may be numeric or a service name.
  82 If it is
  83 .Dv NULL ,
  84 then a
  85 .Fa host
  86 of the format "hostname:port" is permitted.
  87 .Pp
  88 The
  89 .Fn tls_connect_servername
  90 function has the same behaviour, however the name to use for verification is
  91 explicitly provided, rather than being inferred from the
  92 .Ar host
  93 value.
  94 .Pp
  95 An already existing socket can be upgraded to a secure connection by calling
  96 .Fn tls_connect_socket .
  97 .Pp
  98 Alternatively, a secure connection can be established over a pair of existing
  99 file descriptors by calling
 100 .Fn tls_connect_fds .
 101 .Pp
 102 Calling
 103 .Fn tls_connect_cbs
 104 allows read and write callback functions to handle data transfers.
 105 The specified cb_arg parameter is passed back to the functions,
 106 and can contain a pointer to any caller-specified data.
 107 .Sh RETURN VALUES
 108 These 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
 119 and
 120 .Fn tls_connect_socket
 121 appeared in
 122 .Ox 5.6
 123 and got their final names in
 124 .Ox 5.7 .
 125 .Pp
 126 .Fn tls_connect_fds
 127 and
 128 .Fn tls_connect_servername
 129 appeared in
 130 .Ox 5.7
 131 and
 132 .Fn tls_connect_cbs
 133 in
 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
 141 was written by
 142 .An Tobias Pape Aq Mt tobias@netshed.de .