1.\" $OpenBSD: tls_read.3,v 1.8 2023/09/18 17:25: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: September 18 2023 $ 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.Nd use a TLS connection 31.Sh SYNOPSIS 32.In tls.h 33.Ft ssize_t 34.Fo tls_read 35.Fa "struct tls *ctx" 36.Fa "void *buf" 37.Fa "size_t buflen" 38.Fc 39.Ft ssize_t 40.Fo tls_write 41.Fa "struct tls *ctx" 42.Fa "const void *buf" 43.Fa "size_t buflen" 44.Fc 45.Ft int 46.Fn tls_handshake "struct tls *ctx" 47.Ft const char * 48.Fn tls_error "struct tls *ctx" 49.Ft int 50.Fn tls_close "struct tls *ctx" 51.Sh DESCRIPTION 52.Fn tls_read 53reads 54.Fa buflen 55bytes of data from the socket into 56.Fa buf . 57It returns the amount of data read. 58.Pp 59.Fn tls_write 60writes 61.Fa buflen 62bytes of data from 63.Fa buf 64to the socket. 65It returns the amount of data written. 66.Pp 67.Fn tls_handshake 68explicitly performs the TLS handshake. 69It is only necessary to call this function if you need to guarantee that the 70handshake has completed, as both 71.Fn tls_read 72and 73.Fn tls_write 74automatically perform the TLS handshake when necessary. 75.Pp 76The 77.Fn tls_error 78function may be used to retrieve a string containing more information 79about the most recent error relating to a context. 80.Pp 81.Fn tls_close 82closes a connection after use. 83Only the TLS layer will be shut down and the caller is responsible for closing 84the file descriptors, unless the connection was established using 85.Xr tls_connect 3 86or 87.Xr tls_connect_servername 3 . 88After closing the connection, 89.Fa ctx 90can be passed to 91.Xr tls_free 3 . 92.Sh RETURN VALUES 93.Fn tls_read 94and 95.Fn tls_write 96return a size on success or -1 on error. 97.Pp 98.Fn tls_handshake 99and 100.Fn tls_close 101return 0 on success or -1 on error. 102.Pp 103The 104.Fn tls_read , 105.Fn tls_write , 106.Fn tls_handshake , 107and 108.Fn tls_close 109functions also have two special return values: 110.Pp 111.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact 112.It Dv TLS_WANT_POLLIN 113The underlying read file descriptor needs to be readable in order to continue. 114.It Dv TLS_WANT_POLLOUT 115The underlying write file descriptor needs to be writeable in order to continue. 116.El 117.Pp 118In the case of blocking file descriptors, the same function call should be 119repeated immediately. 120In the case of non-blocking file descriptors, the same function call should be 121repeated when the required condition has been met. 122.Pp 123Callers of these functions cannot rely on the value of the global 124.Ar errno . 125To prevent mishandling of error conditions, 126.Fn tls_read , 127.Fn tls_write , 128.Fn tls_handshake , 129and 130.Fn tls_close 131all explicitly clear 132.Ar errno . 133.Pp 134.Fn tls_error 135returns 136.Dv NULL 137if no error occurred with 138.Fa ctx 139during or since the last call to 140.Fn tls_handshake , 141.Fn tls_read , 142.Fn tls_write , 143.Fn tls_close , 144or 145.Xr tls_reset 3 146involving 147.Fa ctx , 148or if memory allocation failed while trying to assemble the string 149describing the most recent error related to 150.Fa ctx . 151.Sh EXAMPLES 152The following example demonstrates how to handle TLS writes on a blocking 153file descriptor: 154.Bd -literal -offset indent 155\&... 156while (len > 0) { 157 ssize_t ret; 158 159 ret = tls_write(ctx, buf, len); 160 if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT) 161 continue; 162 if (ret == -1) 163 errx(1, "tls_write: %s", tls_error(ctx)); 164 buf += ret; 165 len -= ret; 166} 167\&... 168.Ed 169.Pp 170The following example demonstrates how to handle TLS writes on a 171non-blocking file descriptor using 172.Xr poll 2 : 173.Bd -literal -offset indent 174\&... 175pfd[0].fd = fd; 176pfd[0].events = POLLIN|POLLOUT; 177while (len > 0) { 178 nready = poll(pfd, 1, 0); 179 if (nready == -1) 180 err(1, "poll"); 181 if ((pfd[0].revents & (POLLERR|POLLNVAL))) 182 errx(1, "bad fd %d", pfd[0].fd); 183 if ((pfd[0].revents & (pfd[0].events|POLLHUP))) { 184 ssize_t ret; 185 186 ret = tls_write(ctx, buf, len); 187 if (ret == TLS_WANT_POLLIN) 188 pfd[0].events = POLLIN; 189 else if (ret == TLS_WANT_POLLOUT) 190 pfd[0].events = POLLOUT; 191 else if (ret == -1) 192 errx(1, "tls_write: %s", tls_error(ctx)); 193 else { 194 buf += ret; 195 len -= ret; 196 } 197 } 198} 199\&... 200.Ed 201.Sh SEE ALSO 202.Xr tls_accept_socket 3 , 203.Xr tls_configure 3 , 204.Xr tls_conn_version 3 , 205.Xr tls_connect 3 , 206.Xr tls_init 3 , 207.Xr tls_ocsp_process_response 3 208.Sh HISTORY 209.Fn tls_read , 210.Fn tls_write , 211.Fn tls_error , 212and 213.Fn tls_close 214appeared in 215.Ox 5.6 216and got their final names in 217.Ox 5.7 . 218.Pp 219.Fn tls_handshake 220appeared in 221.Ox 5.9 . 222.Sh AUTHORS 223.An Joel Sing Aq Mt jsing@openbsd.org 224with contributions from 225.An Bob Beck Aq Mt beck@openbsd.org 226.Sh CAVEATS 227The function 228.Fn tls_error 229returns an internal pointer. 230It must not be freed by the application, or a double free error 231will occur. 232The pointer will become invalid when the next error occurs with 233.Fa ctx . 234Consequently, if the application may need the message at a later 235time, it has to copy the string before calling the next 236.Sy libtls 237function involving 238.Fa ctx , 239or a segmentation fault or read access to unintended data is the 240likely result. 241