SSL_read - Read bytes from a TLS/SSL connection.
#include <openssl/ssl.h>
int SSL_read(
SSL *ssl,
void *buf,
int num );
The SSL_read() function tries to read num bytes from the
specified ssl into the buffer buf.
If necessary, the SSL_read() function will negotiate a
TLS/SSL session, if not already explicitly performed by
the SSL_connect() or SSL_accept() functions. If the peer
requests a renegotiation, it will be performed transparently
during the SSL_read() operation. The behavior of the
SSL_read() function depends on the underlying BIO.
For the transparent negotiation to succeed, the ssl must
have been initialized to client or server mode. This is
done by calling the SSL_set_connect_state() or
SSL_set_accept_state() function before the first call to
an SSL_read() or SSL_write() function.
The SSL_read() function is based on the SSL/TLS records.
The data are received in records (with a maximum record
size of 16kb for SSLv3/TLSv1). Only when a record has
been completely received, can it be processed (decryption
and check of integrity). Therefore, data that was not
retrieved at the last call of SSL_read() can still be
buffered inside the SSL layer and will be retired on the
next call to SSL_read(). If num is higher than the number
of bytes buffered, SSL_read() will return with the bytes
buffered. If no more bytes are in the buffer, SSL_read()
will trigger the processing of the next record. Only when
the record has been received and processed completely will
SSL_read() return reporting success. At most, the contents
of the record will be returned. As the size of an SSL/TLS
record may exceed the maximum packet size of the underlying
transport, such as TCP, it may be necessary to read
several packets from the transport layer before the record
is complete and SSL_read() can succeed.
If the underlying BIO is blocking, the SSL_read() function
will only return once the read operation has been finished
or an error occurred, except when a renegotiation takes
place, in which case a SSL_ERROR_WANT_READ may occur.
This behavior can be controlled with the
SSL_MODE_AUTO_RETRY flag of the SSL_CTX_set_mode() call.
If the underlying BIO is non-blocking, the SSL_read()
function will also return when the underlying BIO could
not satisfy the needs of SSL_read() to continue the operation.
In this case a call to SSL_get_error() with the
return value of SSL_read() will yield SSL_ERROR_WANT_READ
or SSL_ERROR_WANT_WRITE. As at any time a renegotiation
is possible, a call to SSL_read() can also cause write
operations. The calling process then must repeat the call
after taking appropriate action to satisfy the needs of
SSL_read(). The action depends on the underlying BIO. When
using a non-blocking socket, nothing is to be done, but
select() can be used to check for the required condition.
When using a buffering BIO, such as a BIO pair, data must
be written into or retrieved out of the BIO before being
able to continue.
When an SSL_read() operation is repeated because of
SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE, it must be
repeated with the same arguments.
The following return values can occur: The read operation
was successful; the return value is the number of bytes
actually read from the TLS/SSL connection. The read operation
was not successful. The reason may either be a clean
shutdown due to a "close notify" alert sent by the peer
(in which case the SSL_RECEIVED_SHUTDOWN flag in
the ssl shutdown state is set (See SSL_shutdown() and
SSL_set_shutdown().)
It is also possible that the peer simply shut down
the underlying transport and the shutdown is incomplete.
Call SSL_get_error() with the return value
ret to find out whether an error occurred or the
connection was shut down cleanly
(SSL_ERROR_ZERO_RETURN). SSLv2 (deprecated) does
not support a shutdown alert protocol, so it can
only be detected if the underlying connection was
closed. It cannot be checked if the closure was
initiated by the peer or by something else. The
read operation was not successful, because either
an error occurred or action must be taken by the
calling process. Call SSL_get_error() with the
return value ret to find the reason.
Functions: SSL_get_error(3), SSL_write(3),
SSL_CTX_set_mode(3), SSL_CTX_new(3), SSL_connect(3),
SSL_accept(3) SSL_set_connect_state(3), SSL_shutdown(3),
SSL_set_shurdown(3), ssl(3), bio(3)
SSL_read(3)
[ Back ] |
