Index for Section 3

Alphabetical listing for S

Bottom of page

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
  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 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.

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:

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

  0	  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.

  <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 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)

Index for Section 3

Alphabetical listing for S

Top of page