SSL_get_error(3)SSL_get_error(3)NAMESSL_get_error - Obtain result code for TLS/SSL I/O operation
SYNOPSIS
#include <openssl/ssl.h>
int SSL_get_error(
SSL *ssl,
int ret );
DESCRIPTION
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() func‐
tion 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.
RETURN VALUES
The following return values can currently occur: The TLS/SSL I/O opera‐
tion 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 indi‐
cate 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 visi‐
ble 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 con‐
nected yet to the peer and the call would block in con‐
nect()/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 vio‐
lates 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 pro‐
tocol error. The OpenSSL error queue contains more information
on the error.
HISTORY
The SSL_get_error() function was added in SSLeay 0.8.
SEE ALSO
Functions: ssl(3), err(3)SSL_get_error(3)
