SSL_read.pod revision 89837
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 6768651Skris=head1 WARNING 6868651Skris 6968651SkrisWhen an SSL_read() operation has to be repeated because of 7068651SkrisB<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 7168651Skriswith the same arguments. 7268651Skris 7368651Skris=head1 RETURN VALUES 7468651Skris 7568651SkrisThe following return values can occur: 7668651Skris 7768651Skris=over 4 7868651Skris 7968651Skris=item E<gt>0 8068651Skris 8168651SkrisThe read operation was successful; the return value is the number of 8268651Skrisbytes actually read from the TLS/SSL connection. 8368651Skris 8468651Skris=item 0 8568651Skris 8689837SkrisThe read operation was not successful. The reason may either be a clean 8789837Skrisshutdown due to a "close notify" alert sent by the peer (in which case 8889837Skristhe SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set 8989837Skris(see L<SSL_shutdown(3)|SSL_shutdown(3)>, 9089837SkrisL<SSL_set_shutdown(3)|SSL_set_shutdown(3)>). It is also possible, that 9189837Skristhe peer simply shut down the underlying transport and the shutdown is 9289837Skrisincomplete. Call SSL_get_error() with the return value B<ret> to find out, 9389837Skriswhether an error occurred or the connection was shut down cleanly 9489837Skris(SSL_ERROR_ZERO_RETURN). 9568651Skris 9689837SkrisSSLv2 (deprecated) does not support a shutdown alert protocol, so it can 9789837Skrisonly be detected, whether the underlying connection was closed. It cannot 9889837Skrisbe checked, whether the closure was initiated by the peer or by something 9989837Skriselse. 10089837Skris 10172613Skris=item E<lt>0 10268651Skris 10368651SkrisThe read operation was not successful, because either an error occurred 10468651Skrisor action must be taken by the calling process. Call SSL_get_error() with the 10568651Skrisreturn value B<ret> to find out the reason. 10668651Skris 10768651Skris=back 10868651Skris 10968651Skris=head1 SEE ALSO 11068651Skris 11168651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, 11276866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, 11376866SkrisL<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> 11476866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, 11589837SkrisL<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, 11668651SkrisL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 11768651Skris 11868651Skris=cut 119