SSL_shutdown(3) | OpenSSL | SSL_shutdown(3) |
#include <openssl/ssl.h> int SSL_shutdown(SSL *ssl);
The shutdown procedure consists of 2 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 shall be used for more communications, the complete shutdown procedure (bidirectional "close notify" alerts) must be performed, so that the peers stay synchronized.
SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step behaviour.
SSL_shutdown() only closes the write direction. It is not possible to call SSL_write() after calling SSL_shutdown(). The read direction is closed by the peer.
In order to complete the bidirectional shutdown handshake, the peer needs to send back a "close notify" alert. The SSL_RECEIVED_SHUTDOWN flag will be set after receiving and processing it. SSL_shutdown() will return 1 when it has been received.
The peer is still allowed to send data after receiving the "close notify" event. If the peer did send data it needs to be processed by calling SSL_read() before calling SSL_shutdown() a second time. SSL_read() will indicate the end of the peer data by returning <= 0 and SSL_get_error() returning SSL_ERROR_ZERO_RETURN. It is recommended to call SSL_read() between SSL_shutdown() calls.
The behaviour of SSL_shutdown() additionally depends on the underlying BIO. If the underlying BIO is blocking, SSL_shutdown() will only return once the handshake step has been finished or an error occurred.
If the underlying BIO is non-blocking, SSL_shutdown() will also return when the underlying BIO could not satisfy the needs of SSL_shutdown() 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 then must 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 select() 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.
SSL_shutdown() 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(3). When "quiet shutdown" is enabled, SSL_shutdown() will always succeed and return 1.
It can also occur when not all data was read using SSL_read().
Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.
2018-09-17 | 1.1.1 |