1.\" $OpenBSD: SSL_read.3,v 1.8 2021/10/24 15:10:13 schwarze Exp $ 2.\" full merge up to: OpenSSL 5a2443ae Nov 14 11:37:36 2016 +0000 3.\" partial merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org> and 6.\" Matt Caswell <matt@openssl.org>. 7.\" Copyright (c) 2000, 2001, 2008, 2016 The OpenSSL Project. 8.\" All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in 19.\" the documentation and/or other materials provided with the 20.\" distribution. 21.\" 22.\" 3. All advertising materials mentioning features or use of this 23.\" software must display the following acknowledgment: 24.\" "This product includes software developed by the OpenSSL Project 25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 26.\" 27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 28.\" endorse or promote products derived from this software without 29.\" prior written permission. For written permission, please contact 30.\" openssl-core@openssl.org. 31.\" 32.\" 5. Products derived from this software may not be called "OpenSSL" 33.\" nor may "OpenSSL" appear in their names without prior written 34.\" permission of the OpenSSL Project. 35.\" 36.\" 6. Redistributions of any form whatsoever must retain the following 37.\" acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 52.\" OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.Dd $Mdocdate: October 24 2021 $ 55.Dt SSL_READ 3 56.Os 57.Sh NAME 58.Nm SSL_read_ex , 59.Nm SSL_read , 60.Nm SSL_peek_ex , 61.Nm SSL_peek 62.Nd read bytes from a TLS connection 63.Sh SYNOPSIS 64.In openssl/ssl.h 65.Ft int 66.Fn SSL_read_ex "SSL *ssl" "void *buf" "size_t num" "size_t *readbytes" 67.Ft int 68.Fn SSL_read "SSL *ssl" "void *buf" "int num" 69.Ft int 70.Fn SSL_peek_ex "SSL *ssl" "void *buf" "size_t num" "size_t *readbytes" 71.Ft int 72.Fn SSL_peek "SSL *ssl" "void *buf" "int num" 73.Sh DESCRIPTION 74.Fn SSL_read_ex 75and 76.Fn SSL_read 77try to read 78.Fa num 79bytes from the specified 80.Fa ssl 81into the buffer 82.Fa buf . 83On success 84.Fn SSL_read_ex 85stores the number of bytes actually read in 86.Pf * Fa readbytes . 87.Pp 88.Fn SSL_peek_ex 89and 90.Fn SSL_peek 91are identical to 92.Fn SSL_read_ex 93and 94.Fn SSL_read , 95respectively, 96except that no bytes are removed from the underlying BIO during 97the read, such that a subsequent call to 98.Fn SSL_read_ex 99or 100.Fn SSL_read 101will yield at least the same bytes once again. 102.Pp 103In the following, 104.Fn SSL_read_ex , 105.Fn SSL_read , 106.Fn SSL_peek_ex , 107and 108.Fn SSL_peek 109are called 110.Dq read functions . 111.Pp 112If necessary, a read function will negotiate a TLS session, if 113not already explicitly performed by 114.Xr SSL_connect 3 115or 116.Xr SSL_accept 3 . 117If the peer requests a re-negotiation, it will be performed 118transparently during the read function operation. 119The behaviour of the read functions depends on the underlying 120.Vt BIO . 121.Pp 122For the transparent negotiation to succeed, the 123.Fa ssl 124must have been initialized to client or server mode. 125This is done by calling 126.Xr SSL_set_connect_state 3 127or 128.Xr SSL_set_accept_state 3 129before the first call to a read function. 130.Pp 131The read functions work based on the TLS records. 132The data are received in records (with a maximum record size of 16kB). 133Only when a record has been completely received, it can be processed 134(decrypted and checked for integrity). 135Therefore, data that was not retrieved at the last read call can 136still be buffered inside the TLS layer and will be retrieved on the 137next read call. 138If 139.Fa num 140is higher than the number of bytes buffered, the read functions 141will return with the bytes buffered. 142If no more bytes are in the buffer, the read functions will trigger 143the processing of the next record. 144Only when the record has been received and processed completely 145will the read functions return reporting success. 146At most the contents of the record will be returned. 147As the size of a TLS record may exceed the maximum packet size 148of the underlying transport (e.g., TCP), it may be necessary to 149read several packets from the transport layer before the record is 150complete and the read call can succeed. 151.Pp 152If the underlying 153.Vt BIO 154is blocking, 155a read function will only return once the read operation has been 156finished or an error occurred, except when a renegotiation takes 157place, in which case an 158.Dv SSL_ERROR_WANT_READ 159may occur. 160This behavior can be controlled with the 161.Dv SSL_MODE_AUTO_RETRY 162flag of the 163.Xr SSL_CTX_set_mode 3 164call. 165.Pp 166If the underlying 167.Vt BIO 168is non-blocking, a read function will also return when the underlying 169.Vt BIO 170could not satisfy the needs of the function to continue the operation. 171In this case a call to 172.Xr SSL_get_error 3 173with the return value of the read function will yield 174.Dv SSL_ERROR_WANT_READ 175or 176.Dv SSL_ERROR_WANT_WRITE . 177As at any time a re-negotiation is possible, a read function may 178also cause write operations. 179The calling process must then repeat the call after taking appropriate 180action to satisfy the needs of the read function. 181The action depends on the underlying 182.Vt BIO . 183When using a non-blocking socket, nothing is to be done, but 184.Xr select 2 185can be used to check for the required condition. 186When using a buffering 187.Vt BIO , 188like a 189.Vt BIO 190pair, data must be written into or retrieved out of the 191.Vt BIO 192before being able to continue. 193.Pp 194.Xr SSL_pending 3 195can be used to find out whether there are buffered bytes available for 196immediate retrieval. 197In this case a read function can be called without blocking or 198actually receiving new data from the underlying socket. 199.Pp 200When a read function operation has to be repeated because of 201.Dv SSL_ERROR_WANT_READ 202or 203.Dv SSL_ERROR_WANT_WRITE , 204it must be repeated with the same arguments. 205.Sh RETURN VALUES 206.Fn SSL_read_ex 207and 208.Fn SSL_peek_ex 209return 1 for success or 0 for failure. 210Success means that one or more application data bytes 211have been read from the SSL connection. 212Failure means that no bytes could be read from the SSL connection. 213Failures can be retryable (e.g. we are waiting for more bytes to be 214delivered by the network) or non-retryable (e.g. a fatal network error). 215In the event of a failure, call 216.Xr SSL_get_error 3 217to find out the reason which indicates whether the call is retryable or not. 218.Pp 219For 220.Fn SSL_read 221and 222.Fn SSL_peek , 223the following return values can occur: 224.Bl -tag -width Ds 225.It >0 226The read operation was successful. 227The return value is the number of bytes actually read from the 228TLS connection. 229.It 0 230The read operation was not successful. 231The reason may either be a clean shutdown due to a 232.Dq close notify 233alert sent by the peer (in which case the 234.Dv SSL_RECEIVED_SHUTDOWN 235flag in the ssl shutdown state is set (see 236.Xr SSL_shutdown 3 237and 238.Xr SSL_set_shutdown 3 ) . 239It is also possible that the peer simply shut down the underlying transport and 240the shutdown is incomplete. 241Call 242.Xr SSL_get_error 3 243with the return value to find out whether an error occurred or the connection 244was shut down cleanly 245.Pq Dv SSL_ERROR_ZERO_RETURN . 246.It <0 247The read operation was not successful, because either an error occurred or 248action must be taken by the calling process. 249Call 250.Xr SSL_get_error 3 251with the return value to find out the reason. 252.El 253.Sh SEE ALSO 254.Xr BIO_new 3 , 255.Xr ssl 3 , 256.Xr SSL_accept 3 , 257.Xr SSL_connect 3 , 258.Xr SSL_CTX_new 3 , 259.Xr SSL_CTX_set_mode 3 , 260.Xr SSL_get_error 3 , 261.Xr SSL_pending 3 , 262.Xr SSL_set_connect_state 3 , 263.Xr SSL_set_shutdown 3 , 264.Xr SSL_shutdown 3 , 265.Xr SSL_write 3 266.Sh HISTORY 267.Fn SSL_read 268appeared in SSLeay 0.4 or earlier. 269.Fn SSL_peek 270first appeared in SSLeay 0.6.6. 271Both functions have been available since 272.Ox 2.4 . 273.Pp 274.Fn SSL_read_ex 275and 276.Fn SSL_peek_ex 277first appeared in OpenSSL 1.1.1 and have been available since 278.Ox 7.1 . 279