SSL_read(3)SSL_read(3)NAMESSL_read - Read bytes from a TLS/SSL connection.
SYNOPSIS
#include <openssl/ssl.h>
int SSL_read(
SSL *ssl,
void *buf,
int num );
DESCRIPTION
The SSL_read() function tries to read num bytes from the specified ssl
into the buffer buf.
NOTES
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 behav‐
ior of the SSL_read() function depends on the underlying BIO.
For the transparent negotiation to succeed, the ssl must have been ini‐
tialized 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 renego‐
tiation is possible, a call to SSL_read() can also cause write opera‐
tions. 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, noth‐
ing 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.
RESTRICTIONS
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.
RETURN VALUES
The following return values can occur: The read operation was success‐
ful; 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_shut‐
down().)
It is also possible that the peer simply shut down the underly‐
ing 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.
SEE ALSO
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)
