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<nonblocking>, 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 nonblocking 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 96When used with a QUIC SSL object, calling an I/O function such as SSL_read() 97allows internal network event processing to be performed. It is important that 98this processing is performed regularly. If an application is not using thread 99assisted mode, an application should ensure that an I/O function such as 100SSL_read() is called regularly, or alternatively ensure that SSL_handle_events() 101is called regularly. See L<openssl-quic(7)> and L<SSL_handle_events(3)> for more 102information. 103 104=head1 RETURN VALUES 105 106SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for failure. 107Success means that 1 or more application data bytes have been read from the SSL 108connection. 109Failure means that no bytes could be read from the SSL connection. 110Failures can be retryable (e.g. we are waiting for more bytes to 111be delivered by the network) or non-retryable (e.g. a fatal network error). 112In the event of a failure call L<SSL_get_error(3)> to find out the reason which 113indicates whether the call is retryable or not. 114 115For SSL_read() and SSL_peek() the following return values can occur: 116 117=over 4 118 119=item E<gt> 0 120 121The read operation was successful. 122The return value is the number of bytes actually read from the TLS/SSL 123connection. 124 125=item Z<><= 0 126 127The read operation was not successful, because either the connection was closed, 128an error occurred or action must be taken by the calling process. 129Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. 130 131Old documentation indicated a difference between 0 and -1, and that -1 was 132retryable. 133You should instead call SSL_get_error() to find out if it's retryable. 134 135=back 136 137=head1 SEE ALSO 138 139L<SSL_get_error(3)>, L<SSL_write_ex(3)>, 140L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, 141L<SSL_connect(3)>, L<SSL_accept(3)> 142L<SSL_set_connect_state(3)>, 143L<SSL_pending(3)>, 144L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>, 145L<ssl(7)>, L<bio(7)> 146 147=head1 HISTORY 148 149The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL 1.1.1. 150 151=head1 COPYRIGHT 152 153Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 154 155Licensed under the Apache License 2.0 (the "License"). You may not use 156this file except in compliance with the License. You can obtain a copy 157in the file LICENSE in the source distribution or at 158L<https://www.openssl.org/source/license.html>. 159 160=cut 161
