lib/libtls/man/tls_read.3

   1 .\" $OpenBSD: tls_read.3,v 1.4 2017/02/20 13:09:15 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2014, 2015 Ted Unangst <tedu@openbsd.org>
   4 .\" Copyright (c) 2015 Doug Hogan <doug@openbsd.org>
   5 .\" Copyright (c) 2015 Joel Sing <jsing@openbsd.org>
   6 .\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
   7 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
   8 .\"
   9 .\" Permission to use, copy, modify, and distribute this software for any
  10 .\" purpose with or without fee is hereby granted, provided that the above
  11 .\" copyright notice and this permission notice appear in all copies.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  19 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  20 .\"
  21 .Dd $Mdocdate: February 20 2017 $
  22 .Dt TLS_READ 3
  23 .Os
  24 .Sh NAME
  25 .Nm tls_read ,
  26 .Nm tls_write ,
  27 .Nm tls_handshake ,
  28 .Nm tls_error ,
  29 .Nm tls_close ,
  30 .Nm tls_reset
  31 .Nd use a TLS connection
  32 .Sh SYNOPSIS
  33 .In tls.h
  34 .Ft ssize_t
  35 .Fo tls_read
  36 .Fa "struct tls *ctx"
  37 .Fa "void *buf"
  38 .Fa "size_t buflen"
  39 .Fc
  40 .Ft ssize_t
  41 .Fo tls_write
  42 .Fa "struct tls *ctx"
  43 .Fa "const void *buf"
  44 .Fa "size_t buflen"
  45 .Fc
  46 .Ft int
  47 .Fn tls_handshake "struct tls *ctx"
  48 .Ft const char *
  49 .Fn tls_error "struct tls *ctx"
  50 .Ft int
  51 .Fn tls_close "struct tls *ctx"
  52 .Ft void
  53 .Fn tls_reset "struct tls *ctx"
  54 .Sh DESCRIPTION
  55 .Fn tls_read
  56 reads
  57 .Fa buflen
  58 bytes of data from the socket into
  59 .Fa buf .
  60 It returns the amount of data read.
  61 .Pp
  62 .Fn tls_write
  63 writes
  64 .Fa buflen
  65 bytes of data from
  66 .Fa buf
  67 to the socket.
  68 It returns the amount of data written.
  69 .Pp
  70 .Fn tls_handshake
  71 explicitly performs the TLS handshake.
  72 It is only necessary to call this function if you need to guarantee that the
  73 handshake has completed, as both
  74 .Fn tls_read
  75 and
  76 .Fn tls_write
  77 automatically perform the TLS handshake when necessary.
  78 .Pp
  79 The
  80 .Fn tls_error
  81 function may be used to retrieve a string containing more information
  82 about the most recent error relating to a context.
  83 .Pp
  84 .Fn tls_close
  85 closes a connection after use.
  86 Only the TLS layer will be shut down and the caller is responsible for closing
  87 the file descriptors, unless the connection was established using
  88 .Xr tls_connect 3
  89 or
  90 .Xr tls_connect_servername 3 .
  91 After closing the connection,
  92 .Fa ctx
  93 can be passed to
  94 .Xr tls_free 3 .
  95 .\" XXX Fn tls_reset does what?
  96 .Sh RETURN VALUES
  97 .Fn tls_read
  98 and
  99 .Fn tls_write
 100 return a size on success or -1 on error.
 101 .Pp
 102 .Fn tls_handshake
 103 and
 104 .Fn tls_close
 105 return 0 on success or -1 on error.
 106 .Pp
 107 .Fn tls_error
 108 returns
 109 .Dv NULL
 110 if no error occurred with
 111 .Fa ctx
 112 during or since the last call to
 113 .Fn tls_handshake ,
 114 .Fn tls_read ,
 115 .Fn tls_write ,
 116 .Fn tls_close ,
 117 or
 118 .Fn tls_reset
 119 involving
 120 .Fa ctx ,
 121 or if memory allocation failed while trying to assemble the string
 122 describing the most recent error related to
 123 .Fa ctx .
 124 .Pp
 125 The
 126 .Fn tls_read ,
 127 .Fn tls_write ,
 128 .Fn tls_handshake ,
 129 and
 130 .Fn tls_close
 131 functions have two special return values:
 132 .Pp
 133 .Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact
 134 .It Dv TLS_WANT_POLLIN
 135 The underlying read file descriptor needs to be readable in order to continue.
 136 .It Dv TLS_WANT_POLLOUT
 137 The underlying write file descriptor needs to be writeable in order to continue.
 138 .El
 139 .Pp
 140 In the case of blocking file descriptors, the same function call should be
 141 repeated immediately.
 142 In the case of non-blocking file descriptors, the same function call should be
 143 repeated when the required condition has been met.
 144 .Pp
 145 Callers of these functions cannot rely on the value of the global
 146 .Ar errno .
 147 To prevent mishandling of error conditions,
 148 .Fn tls_read ,
 149 .Fn tls_write ,
 150 .Fn tls_handshake ,
 151 and
 152 .Fn tls_close
 153 all explicitly clear
 154 .Ar errno .
 155 .Sh EXAMPLES
 156 The following example demonstrates how to handle TLS writes on a blocking
 157 file descriptor:
 158 .Bd -literal -offset indent
 159 \&...
 160 while (len > 0) {
 161         ssize_t ret;
 162
 163         ret = tls_write(ctx, buf, len);
 164         if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT)
 165                 continue;
 166         if (ret < 0)
 167                 err(1, "tls_write: %s", tls_error(ctx));
 168         buf += ret;
 169         len -= ret;
 170 }
 171 \&...
 172 .Ed
 173 .Pp
 174 The following example demonstrates how to handle TLS writes on a
 175 non-blocking file descriptor using
 176 .Xr poll 2 :
 177 .Bd -literal -offset indent
 178 \&...
 179 pfd[0].fd = fd;
 180 pfd[0].events = POLLIN|POLLOUT;
 181 while (len > 0) {
 182         nready = poll(pfd, 1, 0);
 183         if (nready == -1)
 184                 err(1, "poll");
 185         if ((pfd[0].revents & (POLLERR|POLLNVAL)))
 186                 errx(1, "bad fd %d", pfd[0].fd);
 187         if ((pfd[0].revents & (pfd[0].events|POLLHUP))) {
 188                 ssize_t ret;
 189
 190                 ret = tls_write(ctx, buf, len);
 191                 if (ret == TLS_WANT_POLLIN)
 192                         pfd[0].events = POLLIN;
 193                 else if (ret == TLS_WANT_POLLOUT)
 194                         pfd[0].events = POLLOUT;
 195                 else if (ret < 0)
 196                         err(1, "tls_write: %s", tls_error(ctx));
 197                 else {
 198                         buf += ret;
 199                         len -= ret;
 200                 }
 201         }
 202 }
 203 \&...
 204 .Ed
 205 .Sh SEE ALSO
 206 .Xr tls_accept_socket 3 ,
 207 .Xr tls_configure 3 ,
 208 .Xr tls_conn_version 3 ,
 209 .Xr tls_connect 3 ,
 210 .Xr tls_init 3 ,
 211 .Xr tls_ocsp_process_response 3
 212 .Sh HISTORY
 213 .Fn tls_read ,
 214 .Fn tls_write ,
 215 .Fn tls_error ,
 216 .Fn tls_close ,
 217 and
 218 .Fn tls_reset
 219 appeared in
 220 .Ox 5.6
 221 and got their final names in
 222 .Ox 5.7 .
 223 .Pp
 224 .Fn tls_handshake
 225 appeared in
 226 .Ox 5.9 .
 227 .Sh AUTHORS
 228 .An Joel Sing Aq Mt jsing@openbsd.org
 229 with contributions from
 230 .An Bob Beck Aq Mt beck@openbsd.org
 231 .Sh CAVEATS
 232 The function
 233 .Fn tls_error
 234 returns an internal pointer.
 235 It must not be freed by the application, or a double free error
 236 will occur.
 237 The pointer will become invalid when the next error occurs with
 238 .Fa ctx .
 239 Consequently, if the application may need the message at a later
 240 time, it has to copy the string before calling the next
 241 .Sy libtls
 242 function involving
 243 .Fa ctx ,
 244 or a segmentation fault or read access to unintended data is the
 245 likely result.