168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisSSL_read - read bytes from a TLS/SSL connection. 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/ssl.h> 1068651Skris 1176866Skris int SSL_read(SSL *ssl, void *buf, int num); 1268651Skris 1368651Skris=head1 DESCRIPTION 1468651Skris 1568651SkrisSSL_read() tries to read B<num> bytes from the specified B<ssl> into the 1668651Skrisbuffer B<buf>. 1768651Skris 1868651Skris=head1 NOTES 1968651Skris 2068651SkrisIf necessary, SSL_read() will negotiate a TLS/SSL session, if 2176866Skrisnot already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or 2276866SkrisL<SSL_accept(3)|SSL_accept(3)>. If the 2368651Skrispeer requests a re-negotiation, it will be performed transparently during 2468651Skristhe SSL_read() operation. The behaviour of SSL_read() depends on the 2568651Skrisunderlying BIO. 2668651Skris 2776866SkrisFor the transparent negotiation to succeed, the B<ssl> must have been 2889837Skrisinitialized to client or server mode. This is being done by calling 2976866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() 3089837Skrisbefore the first call to an SSL_read() or L<SSL_write(3)|SSL_write(3)> 3189837Skrisfunction. 3276866Skris 3379998SkrisSSL_read() works based on the SSL/TLS records. The data are received in 3479998Skrisrecords (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a 3579998Skrisrecord has been completely received, it can be processed (decryption and 3679998Skrischeck of integrity). Therefore data that was not retrieved at the last 3779998Skriscall of SSL_read() can still be buffered inside the SSL layer and will be 3879998Skrisretrieved on the next call to SSL_read(). If B<num> is higher than the 3979998Skrisnumber of bytes buffered, SSL_read() will return with the bytes buffered. 4079998SkrisIf no more bytes are in the buffer, SSL_read() will trigger the processing 4179998Skrisof the next record. Only when the record has been received and processed 4279998Skriscompletely, SSL_read() will return reporting success. At most the contents 4379998Skrisof the record will be returned. As the size of an SSL/TLS record may exceed 4479998Skristhe maximum packet size of the underlying transport (e.g. TCP), it may 4579998Skrisbe necessary to read several packets from the transport layer before the 4679998Skrisrecord is complete and SSL_read() can succeed. 4779998Skris 4868651SkrisIf the underlying BIO is B<blocking>, SSL_read() will only return, once the 4976866Skrisread operation has been finished or an error occurred, except when a 5076866Skrisrenegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. 5176866SkrisThis behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the 5276866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. 5368651Skris 5468651SkrisIf the underlying BIO is B<non-blocking>, SSL_read() will also return 5568651Skriswhen the underlying BIO could not satisfy the needs of SSL_read() 5676866Skristo continue the operation. In this case a call to 5776866SkrisL<SSL_get_error(3)|SSL_get_error(3)> with the 5868651Skrisreturn value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or 5968651SkrisB<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 6068651Skriscall to SSL_read() can also cause write operations! The calling process 6168651Skristhen must repeat the call after taking appropriate action to satisfy the 6268651Skrisneeds of SSL_read(). The action depends on the underlying BIO. When using a 6368651Skrisnon-blocking socket, nothing is to be done, but select() can be used to check 6468651Skrisfor the required condition. When using a buffering BIO, like a BIO pair, data 6568651Skrismust be written into or retrieved out of the BIO before being able to continue. 6668651Skris 67194206SsimonL<SSL_pending(3)|SSL_pending(3)> can be used to find out whether there 68194206Ssimonare buffered bytes available for immediate retrieval. In this case 69194206SsimonSSL_read() can be called without blocking or actually receiving new 70194206Ssimondata from the underlying socket. 71194206Ssimon 7268651Skris=head1 WARNING 7368651Skris 7468651SkrisWhen an SSL_read() operation has to be repeated because of 7568651SkrisB<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 7668651Skriswith the same arguments. 7768651Skris 7868651Skris=head1 RETURN VALUES 7968651Skris 8068651SkrisThe following return values can occur: 8168651Skris 8268651Skris=over 4 8368651Skris 8468651Skris=item E<gt>0 8568651Skris 8668651SkrisThe read operation was successful; the return value is the number of 8768651Skrisbytes actually read from the TLS/SSL connection. 8868651Skris 89264331Sjkim=item Z<>0 9068651Skris 9189837SkrisThe read operation was not successful. The reason may either be a clean 9289837Skrisshutdown due to a "close notify" alert sent by the peer (in which case 9389837Skristhe SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set 9489837Skris(see L<SSL_shutdown(3)|SSL_shutdown(3)>, 9589837SkrisL<SSL_set_shutdown(3)|SSL_set_shutdown(3)>). It is also possible, that 9689837Skristhe peer simply shut down the underlying transport and the shutdown is 9789837Skrisincomplete. Call SSL_get_error() with the return value B<ret> to find out, 9889837Skriswhether an error occurred or the connection was shut down cleanly 9989837Skris(SSL_ERROR_ZERO_RETURN). 10068651Skris 10189837SkrisSSLv2 (deprecated) does not support a shutdown alert protocol, so it can 10289837Skrisonly be detected, whether the underlying connection was closed. It cannot 10389837Skrisbe checked, whether the closure was initiated by the peer or by something 10489837Skriselse. 10589837Skris 10672613Skris=item E<lt>0 10768651Skris 10868651SkrisThe read operation was not successful, because either an error occurred 10968651Skrisor action must be taken by the calling process. Call SSL_get_error() with the 11068651Skrisreturn value B<ret> to find out the reason. 11168651Skris 11268651Skris=back 11368651Skris 11468651Skris=head1 SEE ALSO 11568651Skris 11668651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, 11776866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, 11876866SkrisL<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> 11976866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, 120194206SsimonL<SSL_pending(3)|SSL_pending(3)>, 12189837SkrisL<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, 12268651SkrisL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 12368651Skris 12468651Skris=cut 125