|
|
SSL_get_error(3)
Contents
|
SSL_get_error - Obtain result code for TLS/SSL I/O operation
#include <openssl/ssl.h>
int SSL_get_error(
SSL *ssl,
int ret );
The SSL_get_error() function returns a result code (suitable
for the C switch statement) for a preceding call to
the SSL_connect(), SSL_accept(), SSL_do_handshake(),
SSL_read(), SSL_peek(), or SSL_write() functions on ssl.
The value returned by that TLS/SSL I/O function must be
passed to the SSL_get_error() function in parameter ret.
In addition to ssl and ret, the SSL_get_error() function
inspects the current thread's OpenSSL error queue. Thus,
the SSL_get_error() function must be used in the same
thread that performed the TLS/SSL I/O operation, and no
other OpenSSL function calls should appear in between.
The current thread's error queue must be empty before the
TLS/SSL I/O operation is attempted, or the SSL_get_error()
function will not work reliably.
The following return values can currently occur: The
TLS/SSL I/O operation completed. This result code is
returned if and only if ret > 0. The TLS/SSL connection
has been closed. If the protocol version is SSL 3.0 or
TLS 1.0, this result code is returned only if a closure
alert has occurred in the protocol, i.e. if the connection
has been closed cleanly. In this case
SSL_ERROR_ZERO_RETURN does not necessarily indicate that
the underlying transport has been closed. The operation
did not complete; the same TLS/SSL I/O function should be
called again later. If, by then, the underlying BIO has
data available for reading (if the result code is
SSL_ERROR_WANT_READ) or allows writing data
(SSL_ERROR_WANT_WRITE), then some TLS/SSL protocol
progress will take place, i.e. at least part of an TLS/SSL
record will be read or written. The retry may again lead
to a SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition.
There is no fixed upper limit for the number of
iterations that may be necessary until progress becomes
visible at application protocol level.
For socket BIOs (e.g. when the SSL_set_fd() function
was used), the select() or poll() functions on
the underlying socket can be used to determine when
the TLS/SSL I/O function should be retried.
Caveat: Any TLS/SSL I/O function can lead to either
SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. In
particular, the SSL_read() or SSL_peek() functions
might write data, and the SSL_write() function
might read data. This is because TLS/SSL handshakes
can occur at any time during the protocol
(initiated by either the client or the server); the
SSL_read(), SSL_peek(), and SSL_write() functions
will handle any pending handshakes. The operation
did not complete; the same TLS/SSL I/O function
should be called again later. The underlying BIO
was not connected yet to the peer and the call
would block in connect()/accept(). The SSL function
should be called again when the connection is
established. These messages can only appear with a
BIO_s_connect() or BIO_s_accept() BIO, respectively.
In order to find out when the connection
has been successfully established, on many platforms
the select() or poll() functions for writing
on the socket file descriptor can be used. The
operation did not complete because an application
callback set by theSSL_CTX_set_client_cert_cb()
function has asked to be called again. The TLS/SSL
I/O function should be called again later. Details
depend on the application. Some I/O error
occurred. The OpenSSL error queue may contain more
information on the error. If the error queue is
empty (i.e. the ERR_get_error() functions returns
0), ret can be used to learn more about the error.
If ret == 0, an EOF was observed that violates the
protocol. If ret == -1, the underlying BIO
reported an I/O error (for socket I/O on UNIX systems,
consult errno for details). A failure in the
SSL library occurred, usually a protocol error.
The OpenSSL error queue contains more information
on the error.
The SSL_get_error() function was added in SSLeay 0.8.
Functions: ssl(3), err(3)
SSL_get_error(3)
[ Back ] |
