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