SSL_read(3)                 OpenSSL                 SSL_read(3)





NAME
       SSL_read - read bytes from a TLS/SSL connection.

SYNOPSIS
        #include <openssl/ssl.h>

        int SSL_read(SSL *ssl, void *buf, int num);

DESCRIPTION
       SSL_read() tries to read num bytes from the specified
       ssl into the buffer buf.

NOTES
       If necessary, SSL_read() will negotiate a TLS/SSL ses-
       sion, if not already explicitly performed by SSL_con-
       nect(3) or SSL_accept(3). If the peer requests a
       re-negotiation, it will be performed transparently dur-
       ing the SSL_read() operation. The behaviour of
       SSL_read() depends on the underlying BIO.

       For the transparent negotiation to succeed, the ssl must
       have been initialized to client or server mode. This is
       being done by calling SSL_set_connect_state(3) or
       SSL_set_accept_state() before the first call to an
       SSL_read() or SSL_write(3) function.

       SSL_read() works 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 com-
       pletely received, it can 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 retrieved 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 pro-
       cessed completely, SSL_read() will return reporting suc-
       cess. 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
       (e.g. 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, SSL_read() will only
       return, once the read operation has been finished or an
       error occurred, except when a renegotiation take place,
       in which case a SSL_ERROR_WANT_READ may occur.  This be-
       haviour can be controlled with the SSL_MODE_AUTO_RETRY
       flag of the SSL_CTX_set_mode(3) call.

       If the underlying BIO is non-blocking, SSL_read() 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(3) with the return
       value of SSL_read() will yield SSL_ERROR_WANT_READ or
       SSL_ERROR_WANT_WRITE. As at any time a re-negotiation 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 underly-
       ing 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, like a
       BIO pair, data must be written into or retrieved out of
       the BIO before being able to continue.

WARNING
       When an SSL_read() operation has to be 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:

       >0  The read operation was successful; the return value
           is the number of bytes actually read from the
           TLS/SSL connection.

       o   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(3), SSL_set_shutdown(3)).
           It is also possible, that the peer simply shut down
           the underlying transport and the shutdown is incom-
           plete. 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, whether the
           underlying connection was closed. It cannot be
           checked, whether the closure was initiated by the
           peer or by something else.

       <0  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 out the reason.

SEE ALSO
       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_shut-
       down(3), ssl(3), bio(3)



0.9.7c                     2001-09-13               SSL_read(3)
