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