| SSL_read.pod (79998) | SSL_read.pod (89837) |
|---|---|
| 1=pod 2 3=head1 NAME 4 5SSL_read - read bytes from a TLS/SSL connection. 6 7=head1 SYNOPSIS 8 --- 11 unchanged lines hidden (view full) --- 20If necessary, SSL_read() will negotiate a TLS/SSL session, if 21not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or 22L<SSL_accept(3)|SSL_accept(3)>. If the 23peer requests a re-negotiation, it will be performed transparently during 24the SSL_read() operation. The behaviour of SSL_read() depends on the 25underlying BIO. 26 27For the transparent negotiation to succeed, the B<ssl> must have been | 1=pod 2 3=head1 NAME 4 5SSL_read - read bytes from a TLS/SSL connection. 6 7=head1 SYNOPSIS 8 --- 11 unchanged lines hidden (view full) --- 20If necessary, SSL_read() will negotiate a TLS/SSL session, if 21not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or 22L<SSL_accept(3)|SSL_accept(3)>. If the 23peer requests a re-negotiation, it will be performed transparently during 24the SSL_read() operation. The behaviour of SSL_read() depends on the 25underlying BIO. 26 27For the transparent negotiation to succeed, the B<ssl> must have been |
| 28initialized to client or server mode. This is not the case if a generic 29method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that | 28initialized to client or server mode. This is being done by calling |
| 30L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() | 29L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() |
| 31must be used before the first call to an SSL_read() or 32L<SSL_write(3)|SSL_write(3)> function). | 30before the first call to an SSL_read() or L<SSL_write(3)|SSL_write(3)> 31function. |
| 33 34SSL_read() works based on the SSL/TLS records. The data are received in 35records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a 36record has been completely received, it can be processed (decryption and 37check of integrity). Therefore data that was not retrieved at the last 38call of SSL_read() can still be buffered inside the SSL layer and will be 39retrieved on the next call to SSL_read(). If B<num> is higher than the 40number of bytes buffered, SSL_read() will return with the bytes buffered. --- 38 unchanged lines hidden (view full) --- 79 80=item E<gt>0 81 82The read operation was successful; the return value is the number of 83bytes actually read from the TLS/SSL connection. 84 85=item 0 86 | 32 33SSL_read() works based on the SSL/TLS records. The data are received in 34records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a 35record has been completely received, it can be processed (decryption and 36check of integrity). Therefore data that was not retrieved at the last 37call of SSL_read() can still be buffered inside the SSL layer and will be 38retrieved on the next call to SSL_read(). If B<num> is higher than the 39number of bytes buffered, SSL_read() will return with the bytes buffered. --- 38 unchanged lines hidden (view full) --- 78 79=item E<gt>0 80 81The read operation was successful; the return value is the number of 82bytes actually read from the TLS/SSL connection. 83 84=item 0 85 |
| 87The read operation was not successful, probably because no data was 88available. Call SSL_get_error() with the return value B<ret> to find out, 89whether an error occurred. | 86The read operation was not successful. The reason may either be a clean 87shutdown due to a "close notify" alert sent by the peer (in which case 88the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set 89(see L<SSL_shutdown(3)|SSL_shutdown(3)>, 90L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>). It is also possible, that 91the peer simply shut down the underlying transport and the shutdown is 92incomplete. Call SSL_get_error() with the return value B<ret> to find out, 93whether an error occurred or the connection was shut down cleanly 94(SSL_ERROR_ZERO_RETURN). |
| 90 | 95 |
| 96SSLv2 (deprecated) does not support a shutdown alert protocol, so it can 97only be detected, whether the underlying connection was closed. It cannot 98be checked, whether the closure was initiated by the peer or by something 99else. 100 |
|
| 91=item E<lt>0 92 93The read operation was not successful, because either an error occurred 94or action must be taken by the calling process. Call SSL_get_error() with the 95return value B<ret> to find out the reason. 96 97=back 98 99=head1 SEE ALSO 100 101L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, 102L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, 103L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> 104L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, | 101=item E<lt>0 102 103The read operation was not successful, because either an error occurred 104or action must be taken by the calling process. Call SSL_get_error() with the 105return value B<ret> to find out the reason. 106 107=back 108 109=head1 SEE ALSO 110 111L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, 112L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, 113L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> 114L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, |
| 115L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, |
|
| 105L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 106 107=cut | 116L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 117 118=cut |