SSL_read.pod revision 89837
1231200Smm=pod 2232153Smm 3231200Smm=head1 NAME 4231200Smm 5231200SmmSSL_read - read bytes from a TLS/SSL connection. 6231200Smm 7231200Smm=head1 SYNOPSIS 8231200Smm 9231200Smm #include <openssl/ssl.h> 10231200Smm 11231200Smm int SSL_read(SSL *ssl, void *buf, int num); 12231200Smm 13231200Smm=head1 DESCRIPTION 14231200Smm 15231200SmmSSL_read() tries to read B<num> bytes from the specified B<ssl> into the 16231200Smmbuffer B<buf>. 17231200Smm 18231200Smm=head1 NOTES 19231200Smm 20231200SmmIf necessary, SSL_read() will negotiate a TLS/SSL session, if 21231200Smmnot already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or 22231200SmmL<SSL_accept(3)|SSL_accept(3)>. If the 23231200Smmpeer requests a re-negotiation, it will be performed transparently during 24231200Smmthe SSL_read() operation. The behaviour of SSL_read() depends on the 25231200Smmunderlying BIO. 26231200Smm 27231200SmmFor the transparent negotiation to succeed, the B<ssl> must have been 28231200Smminitialized to client or server mode. This is being done by calling 29231200SmmL<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() 30231200Smmbefore the first call to an SSL_read() or L<SSL_write(3)|SSL_write(3)> 31231200Smmfunction. 32231200Smm 33231200SmmSSL_read() works based on the SSL/TLS records. The data are received in 34231200Smmrecords (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a 35231200Smmrecord has been completely received, it can be processed (decryption and 36231200Smmcheck of integrity). Therefore data that was not retrieved at the last 37231200Smmcall of SSL_read() can still be buffered inside the SSL layer and will be 38231200Smmretrieved on the next call to SSL_read(). If B<num> is higher than the 39231200Smmnumber of bytes buffered, SSL_read() will return with the bytes buffered. 40231200SmmIf no more bytes are in the buffer, SSL_read() will trigger the processing 41231200Smmof the next record. Only when the record has been received and processed 42231200Smmcompletely, SSL_read() will return reporting success. At most the contents 43231200Smmof the record will be returned. As the size of an SSL/TLS record may exceed 44231200Smmthe maximum packet size of the underlying transport (e.g. TCP), it may 45231200Smmbe necessary to read several packets from the transport layer before the 46231200Smmrecord is complete and SSL_read() can succeed. 47231200Smm 48231200SmmIf the underlying BIO is B<blocking>, SSL_read() will only return, once the 49231200Smmread operation has been finished or an error occurred, except when a 50231200Smmrenegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. 51231200SmmThis behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the 52231200SmmL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. 53231200Smm 54231200SmmIf the underlying BIO is B<non-blocking>, SSL_read() will also return 55231200Smmwhen the underlying BIO could not satisfy the needs of SSL_read() 56231200Smmto continue the operation. In this case a call to 57231200SmmL<SSL_get_error(3)|SSL_get_error(3)> with the 58231200Smmreturn value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or 59231200SmmB<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 60231200Smmcall to SSL_read() can also cause write operations! The calling process 61231200Smmthen must repeat the call after taking appropriate action to satisfy the 62231200Smmneeds of SSL_read(). The action depends on the underlying BIO. When using a 63231200Smmnon-blocking socket, nothing is to be done, but select() can be used to check 64231200Smmfor the required condition. When using a buffering BIO, like a BIO pair, data 65231200Smmmust be written into or retrieved out of the BIO before being able to continue. 66231200Smm 67231200Smm=head1 WARNING 68231200Smm 69231200SmmWhen an SSL_read() operation has to be repeated because of 70231200SmmB<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 71231200Smmwith the same arguments. 72231200Smm 73231200Smm=head1 RETURN VALUES 74231200Smm 75231200SmmThe following return values can occur: 76231200Smm 77231200Smm=over 4 78231200Smm 79231200Smm=item E<gt>0 80231200Smm 81231200SmmThe read operation was successful; the return value is the number of 82231200Smmbytes actually read from the TLS/SSL connection. 83231200Smm 84231200Smm=item 0 85231200Smm 86231200SmmThe read operation was not successful. The reason may either be a clean 87231200Smmshutdown due to a "close notify" alert sent by the peer (in which case 88231200Smmthe SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set 89231200Smm(see L<SSL_shutdown(3)|SSL_shutdown(3)>, 90231200SmmL<SSL_set_shutdown(3)|SSL_set_shutdown(3)>). It is also possible, that 91231200Smmthe peer simply shut down the underlying transport and the shutdown is 92231200Smmincomplete. Call SSL_get_error() with the return value B<ret> to find out, 93231200Smmwhether an error occurred or the connection was shut down cleanly 94231200Smm(SSL_ERROR_ZERO_RETURN). 95231200Smm 96231200SmmSSLv2 (deprecated) does not support a shutdown alert protocol, so it can 97231200Smmonly be detected, whether the underlying connection was closed. It cannot 98231200Smmbe checked, whether the closure was initiated by the peer or by something 99231200Smmelse. 100231200Smm 101231200Smm=item E<lt>0 102231200Smm 103231200SmmThe read operation was not successful, because either an error occurred 104231200Smmor action must be taken by the calling process. Call SSL_get_error() with the 105231200Smmreturn value B<ret> to find out the reason. 106231200Smm 107231200Smm=back 108231200Smm 109231200Smm=head1 SEE ALSO 110231200Smm 111231200SmmL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, 112231200SmmL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, 113231200SmmL<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> 114231200SmmL<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, 115231200SmmL<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, 116231200SmmL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 117231200Smm 118231200Smm=cut 119231200Smm