1.\" $OpenBSD: tls_read.3,v 1.7 2019/07/09 17:58:33 jsing 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: July 9 2019 $ 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 56reads 57.Fa buflen 58bytes of data from the socket into 59.Fa buf . 60It returns the amount of data read. 61.Pp 62.Fn tls_write 63writes 64.Fa buflen 65bytes of data from 66.Fa buf 67to the socket. 68It returns the amount of data written. 69.Pp 70.Fn tls_handshake 71explicitly performs the TLS handshake. 72It is only necessary to call this function if you need to guarantee that the 73handshake has completed, as both 74.Fn tls_read 75and 76.Fn tls_write 77automatically perform the TLS handshake when necessary. 78.Pp 79The 80.Fn tls_error 81function may be used to retrieve a string containing more information 82about the most recent error relating to a context. 83.Pp 84.Fn tls_close 85closes a connection after use. 86Only the TLS layer will be shut down and the caller is responsible for closing 87the file descriptors, unless the connection was established using 88.Xr tls_connect 3 89or 90.Xr tls_connect_servername 3 . 91After closing the connection, 92.Fa ctx 93can be passed to 94.Xr tls_free 3 . 95.\" XXX Fn tls_reset does what? 96.Sh RETURN VALUES 97.Fn tls_read 98and 99.Fn tls_write 100return a size on success or -1 on error. 101.Pp 102.Fn tls_handshake 103and 104.Fn tls_close 105return 0 on success or -1 on error. 106.Pp 107The 108.Fn tls_read , 109.Fn tls_write , 110.Fn tls_handshake , 111and 112.Fn tls_close 113functions also have two special return values: 114.Pp 115.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact 116.It Dv TLS_WANT_POLLIN 117The underlying read file descriptor needs to be readable in order to continue. 118.It Dv TLS_WANT_POLLOUT 119The underlying write file descriptor needs to be writeable in order to continue. 120.El 121.Pp 122In the case of blocking file descriptors, the same function call should be 123repeated immediately. 124In the case of non-blocking file descriptors, the same function call should be 125repeated when the required condition has been met. 126.Pp 127Callers of these functions cannot rely on the value of the global 128.Ar errno . 129To prevent mishandling of error conditions, 130.Fn tls_read , 131.Fn tls_write , 132.Fn tls_handshake , 133and 134.Fn tls_close 135all explicitly clear 136.Ar errno . 137.Pp 138.Fn tls_error 139returns 140.Dv NULL 141if no error occurred with 142.Fa ctx 143during or since the last call to 144.Fn tls_handshake , 145.Fn tls_read , 146.Fn tls_write , 147.Fn tls_close , 148or 149.Fn tls_reset 150involving 151.Fa ctx , 152or if memory allocation failed while trying to assemble the string 153describing the most recent error related to 154.Fa ctx . 155.Sh EXAMPLES 156The following example demonstrates how to handle TLS writes on a blocking 157file descriptor: 158.Bd -literal -offset indent 159\&... 160while (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 == -1) 167 errx(1, "tls_write: %s", tls_error(ctx)); 168 buf += ret; 169 len -= ret; 170} 171\&... 172.Ed 173.Pp 174The following example demonstrates how to handle TLS writes on a 175non-blocking file descriptor using 176.Xr poll 2 : 177.Bd -literal -offset indent 178\&... 179pfd[0].fd = fd; 180pfd[0].events = POLLIN|POLLOUT; 181while (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 == -1) 196 errx(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 , 217and 218.Fn tls_reset 219appeared in 220.Ox 5.6 221and got their final names in 222.Ox 5.7 . 223.Pp 224.Fn tls_handshake 225appeared in 226.Ox 5.9 . 227.Sh AUTHORS 228.An Joel Sing Aq Mt jsing@openbsd.org 229with contributions from 230.An Bob Beck Aq Mt beck@openbsd.org 231.Sh CAVEATS 232The function 233.Fn tls_error 234returns an internal pointer. 235It must not be freed by the application, or a double free error 236will occur. 237The pointer will become invalid when the next error occurs with 238.Fa ctx . 239Consequently, if the application may need the message at a later 240time, it has to copy the string before calling the next 241.Sy libtls 242function involving 243.Fa ctx , 244or a segmentation fault or read access to unintended data is the 245likely result. 246