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