SSL_shutdown(3)SSL_shutdown(3)NAMESSL_shutdown - Shut down a TLS/SSL connection
SYNOPSIS
#include <openssl/ssl.h>
int SSL_shutdown(
SSL *ssl );
DESCRIPTION
The SSL_shutdown() function shuts down an active TLS/SSL connection. It
sends the “lose notify” shutdown alert to the peer.
NOTES
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 consid‐
ered 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 underly‐
ing 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 bidirec‐
tional 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 suffi‐
cient. 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 imme‐
diately 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 spe‐
cially handled in the SSLv2 protocol, SSL_shutdown() will succeed on
the first call.
The behavior of the SSL_shutdown() function also depends on the under‐
lying 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.
RETURN VALUES
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 erro‐
neous 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 rea‐
son.
SEE ALSO
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)