SSL_shutdown - Shut down a TLS/SSL connection
#include <openssl/ssl.h>
int SSL_shutdown(
SSL *ssl );
The SSL_shutdown() function shuts down an active TLS/SSL
connection. It sends the "lose notify" shutdown alert to
the peer.
The SSL_shutdown() function tries to send the "close
notify" shutdown alert to the peer. Whether the operation
succeeds or not, the SSL_SENT_SHUTDOWN flag is set and a
currently open session is considered closed and good and
will be kept in the session cache for further reuse.
The shutdown procedure consists of two steps: the sending
of the "close notify" shutdown alert and the reception of
the peer's "close notify" shutdown alert. According to
the TLS standard, it is acceptable for an application to
only send its shutdown alert and then close the underlying
connection without waiting for the peer's response. (This
way resources can be saved as the process can already terminate
or serve another connection.) When the underlying
connection is used for more communications, the complete
shutdown procedure (bidirectional "close notify" alerts)
must be performed, so that the peers stay synchronized.
The SSL_shutdown() function supports both unidirectional
and bidirectional shutdown by its two-step behavior.
When the application is the first party to send the
"close notify" alert, SSL_shutdown will only send the
alert and then set the SSL_SENT_SHUTDOWN flag (so that
the session is considered good and will be kept in cache).
The SSL_shutdown() function will then return with 0. If a
unidirectional shutdown is enough (the underlying connection
shall be closed anyway), this first call to SSL_shutdown()
is sufficient. In order to complete the bidirectional
shutdown handshake, SSL_shutdown() must be called
again. The second call will make SSL_shutdown() wait for
the peer's "close notify" shutdown alert. On success, the
second call to SSL_shutdown() will return with 1.
If the peer already sent the "close notify" alert and it
was already processed implicitly inside another function
(SSL_read()), the SSL_RECEIVED_SHUTDOWN flag is set. The
SSL_shutdown() function will send the "close notify"
alert, set the SSL_SENT_SHUTDOWN flag and immediately
return with 1. Whether SSL_RECEIVED_SHUTDOWN is already
set can be checked using the SSL_get_shutdown() function.
We recommend checking the return value of SSL_shutdown()
and call SSL_shutdown() again if the bidirectional shutdown
is not complete (return value of the first call is
0). Since the shutdown is not specially handled in the
SSLv2 protocol, SSL_shutdown() will succeed on the first
call.
The behavior of the SSL_shutdown() function also depends
on the underlying BIO.
If the underlying BIO is blocking, the SSL_shutdown()
function will only return once the handshake step has been
finished or an error occurred.
If the underlying BIO is non-blocking, the SSL_shutdown()
function will also return when the underlying BIO could
not satisfy the needs of the SSL_shutdown() function to
continue the handshake. In this case, a call to
SSL_get_error() with the return value of SSL_shutdown()
will yield SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE.
The calling process must then repeat the call after taking
appropriate action to satisfy the needs of SSL_shutdown().
The action depends on the underlying BIO. When using a
non-blocking socket, nothing is to be done, but the
select() function 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.
The SSL_shutdown() function can be modified to only set
the connection to ``shutdown'' state but not actually send
the ``close notify'' alert messages. See
SSL_CTX_set_quiet_shutdown(). When ``quiet shutdown'' is
enabled, the SSL_shutdown() function will always succeed
and return 1.
The following return values can occur: The shutdown was
successfully completed. The ``close notify'' alert was
sent and the peer's ``close notify'' alert was received.
The shutdown is not finished. Call SSL_shutdown() for a
second time if a bidirectional shutdown will be performed.
The output of SSL_get_error() may be misleading, as an
erroneous SSL_ERROR_SYSCALL may be flagged even though no
error occurred. The shutdown was not successful because a
fatal error occurred either at the protocol level or a
connection failure occurred. It can also occur if action
is needed to continue the operation for non-blocking BIOs.
Call SSL_get_error() with the return value ret to find the
reason.
Functions: SSL_get_error(3), SSL_connect(3),
SSL_accept(3), SSL_set_shutdown(3),
SSL_CTX_set_quiet_shutdown(3) SSL_clear(3), SSL_free(3)
ssl(3), bio(3)
SSL_shutdown(3)
[ Back ] |
