1=pod 2 3=head1 NAME 4 5SSL_read_ex, SSL_read, SSL_peek_ex, SSL_peek 6- read bytes from a TLS/SSL connection 7 8=head1 SYNOPSIS 9 10 #include <openssl/ssl.h> 11 12 int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes); 13 int SSL_read(SSL *ssl, void *buf, int num); 14 15 int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes); 16 int SSL_peek(SSL *ssl, void *buf, int num); 17 18=head1 DESCRIPTION 19 20SSL_read_ex() and SSL_read() try to read B<num> bytes from the specified B<ssl> 21into the buffer B<buf>. On success SSL_read_ex() will store the number of bytes 22actually read in B<*readbytes>. 23 24SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and SSL_read() 25respectively except no bytes are actually removed from the underlying BIO during 26the read, so that a subsequent call to SSL_read_ex() or SSL_read() will yield 27at least the same bytes. 28 29=head1 NOTES 30 31In the paragraphs below a "read function" is defined as one of SSL_read_ex(), 32SSL_read(), SSL_peek_ex() or SSL_peek(). 33 34If necessary, a read function will negotiate a TLS/SSL session, if not already 35explicitly performed by L<SSL_connect(3)> or L<SSL_accept(3)>. If the 36peer requests a re-negotiation, it will be performed transparently during 37the read function operation. The behaviour of the read functions depends on the 38underlying BIO. 39 40For the transparent negotiation to succeed, the B<ssl> must have been 41initialized to client or server mode. This is being done by calling 42L<SSL_set_connect_state(3)> or SSL_set_accept_state() before the first 43invocation of a read function. 44 45The read functions work based on the SSL/TLS records. The data are received in 46records (with a maximum record size of 16kB). Only when a record has been 47completely received, can it be processed (decryption and check of integrity). 48Therefore data that was not retrieved at the last read call can still be 49buffered inside the SSL layer and will be retrieved on the next read 50call. If B<num> is higher than the number of bytes buffered then the read 51functions will return with the bytes buffered. If no more bytes are in the 52buffer, the read functions will trigger the processing of the next record. 53Only when the record has been received and processed completely will the read 54functions return reporting success. At most the contents of one record will 55be returned. As the size of an SSL/TLS record may exceed the maximum packet size 56of the underlying transport (e.g. TCP), it may be necessary to read several 57packets from the transport layer before the record is complete and the read call 58can succeed. 59 60If B<SSL_MODE_AUTO_RETRY> has been switched off and a non-application data 61record has been processed, the read function can return and set the error to 62B<SSL_ERROR_WANT_READ>. 63In this case there might still be unprocessed data available in the B<BIO>. 64If read ahead was set using L<SSL_CTX_set_read_ahead(3)>, there might also still 65be unprocessed data available in the B<SSL>. 66This behaviour can be controlled using the L<SSL_CTX_set_mode(3)> call. 67 68If the underlying BIO is B<blocking>, a read function will only return once the 69read operation has been finished or an error occurred, except when a 70non-application data record has been processed and B<SSL_MODE_AUTO_RETRY> is 71not set. 72Note that if B<SSL_MODE_AUTO_RETRY> is set and only non-application data is 73available the call will hang. 74 75If the underlying BIO is B<non-blocking>, a read function will also return when 76the underlying BIO could not satisfy the needs of the function to continue the 77operation. 78In this case a call to L<SSL_get_error(3)> with the 79return value of the read function will yield B<SSL_ERROR_WANT_READ> or 80B<SSL_ERROR_WANT_WRITE>. 81As at any time it's possible that non-application data needs to be sent, 82a read function can also cause write operations. 83The calling process then must repeat the call after taking appropriate action 84to satisfy the needs of the read function. 85The action depends on the underlying BIO. 86When using a non-blocking socket, nothing is to be done, but select() can be 87used to check for the required condition. 88When using a buffering BIO, like a BIO pair, data must be written into or 89retrieved out of the BIO before being able to continue. 90 91L<SSL_pending(3)> can be used to find out whether there 92are buffered bytes available for immediate retrieval. 93In this case the read function can be called without blocking or actually 94receiving new data from the underlying socket. 95 96=head1 RETURN VALUES 97 98SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for failure. 99Success means that 1 or more application data bytes have been read from the SSL 100connection. 101Failure means that no bytes could be read from the SSL connection. 102Failures can be retryable (e.g. we are waiting for more bytes to 103be delivered by the network) or non-retryable (e.g. a fatal network error). 104In the event of a failure call L<SSL_get_error(3)> to find out the reason which 105indicates whether the call is retryable or not. 106 107For SSL_read() and SSL_peek() the following return values can occur: 108 109=over 4 110 111=item E<gt> 0 112 113The read operation was successful. 114The return value is the number of bytes actually read from the TLS/SSL 115connection. 116 117=item Z<><= 0 118 119The read operation was not successful, because either the connection was closed, 120an error occurred or action must be taken by the calling process. 121Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. 122 123Old documentation indicated a difference between 0 and -1, and that -1 was 124retryable. 125You should instead call SSL_get_error() to find out if it's retryable. 126 127=back 128 129=head1 SEE ALSO 130 131L<SSL_get_error(3)>, L<SSL_write_ex(3)>, 132L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, 133L<SSL_connect(3)>, L<SSL_accept(3)> 134L<SSL_set_connect_state(3)>, 135L<SSL_pending(3)>, 136L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>, 137L<ssl(7)>, L<bio(7)> 138 139=head1 HISTORY 140 141The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL 1.1.1. 142 143=head1 COPYRIGHT 144 145Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. 146 147Licensed under the OpenSSL license (the "License"). You may not use 148this file except in compliance with the License. You can obtain a copy 149in the file LICENSE in the source distribution or at 150L<https://www.openssl.org/source/license.html>. 151 152=cut 153