*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> SSL_read (3)              



NAME    [Toc]    [Back]

       SSL_read - Read bytes from a TLS/SSL connection.

SYNOPSIS    [Toc]    [Back]

       #include <openssl/ssl.h>

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

DESCRIPTION    [Toc]    [Back]

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

NOTES    [Toc]    [Back]

       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    [Toc]    [Back]

       When  an  SSL_read()  operation  is  repeated  because  of
       repeated with the same arguments.

RETURN VALUES    [Toc]    [Back]

       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

              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.

SEE ALSO    [Toc]    [Back]

       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)

[ Back ]
 Similar pages
Name OS Title
SSL_write OpenBSD write bytes to a TLS/SSL connection.
SSL_write NetBSD write bytes to a TLS/SSL connection.
SSL_write Tru64 Write bytes to a TLS/SSL connection.
tis_read_unlock Tru64 Unlocks a read-write lock that was acquired for read access
tis_read_lock Tru64 Acquires a read-write lock for read access
pthread_rwlock_rdlock Tru64 Acquires a read-write lock for read access
AFreadmisc IRIX read from / write to / move logical read/write pointer for data in a miscellaneous chunk in an audio file
tis_read_trylock Tru64 Attempts to acquire a read-write lock for read access and does not wait if the lock cannot be immedi...
swab Tru64 Swap bytes
memcpy OpenBSD copy bytes
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service