1=pod 2 3=head1 NAME 4 5SSL_shutdown - shut down a TLS/SSL connection 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 int SSL_shutdown(SSL *ssl); 12 13=head1 DESCRIPTION 14 15SSL_shutdown() shuts down an active TLS/SSL connection. It sends the 16"close notify" shutdown alert to the peer. 17 18=head1 NOTES 19 20SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. 21Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and 22a currently open session is considered closed and good and will be kept in the 23session cache for further reuse. 24 25The shutdown procedure consists of 2 steps: the sending of the "close notify" 26shutdown alert and the reception of the peer's "close notify" shutdown 27alert. According to the TLS standard, it is acceptable for an application 28to only send its shutdown alert and then close the underlying connection 29without waiting for the peer's response (this way resources can be saved, 30as the process can already terminate or serve another connection). 31When the underlying connection shall be used for more communications, the 32complete shutdown procedure (bidirectional "close notify" alerts) must be 33performed, so that the peers stay synchronized. 34 35SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step 36behaviour. 37 38SSL_shutdown() only closes the write direction. 39It is not possible to call SSL_write() after calling SSL_shutdown(). 40The read direction is closed by the peer. 41 42=head2 First to close the connection 43 44When the application is the first party to send the "close notify" 45alert, SSL_shutdown() will only send the alert and then set the 46SSL_SENT_SHUTDOWN flag (so that the session is considered good and will 47be kept in the cache). 48SSL_shutdown() will then return with 0. 49If a unidirectional shutdown is enough (the underlying connection shall be 50closed anyway), this first call to SSL_shutdown() is sufficient. 51 52In order to complete the bidirectional shutdown handshake, the peer needs 53to send back a "close notify" alert. 54The SSL_RECEIVED_SHUTDOWN flag will be set after receiving and processing 55it. 56SSL_shutdown() will return 1 when it has been received. 57 58The peer is still allowed to send data after receiving the "close notify" 59event. 60If the peer did send data it needs to be processed by calling SSL_read() 61before calling SSL_shutdown() a second time. 62SSL_read() will indicate the end of the peer data by returning <= 0 63and SSL_get_error() returning SSL_ERROR_ZERO_RETURN. 64It is recommended to call SSL_read() between SSL_shutdown() calls. 65 66=head2 Peer closes the connection 67 68If the peer already sent the "close notify" alert B<and> it was 69already processed implicitly inside another function 70(L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. 71SSL_read() will return <= 0 in that case, and SSL_get_error() will return 72SSL_ERROR_ZERO_RETURN. 73SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN 74flag and will immediately return with 1. 75Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the 76SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call. 77 78=head1 NOTES 79 80It is recommended to do a bidirectional shutdown by checking the return value 81of SSL_shutdown() and call it again until it returns 1 or a fatal error. 82 83The behaviour of SSL_shutdown() additionally depends on the underlying BIO. 84If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the 85handshake step has been finished or an error occurred. 86 87If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return 88when the underlying BIO could not satisfy the needs of SSL_shutdown() 89to continue the handshake. In this case a call to SSL_get_error() with the 90return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or 91B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 92taking appropriate action to satisfy the needs of SSL_shutdown(). 93The action depends on the underlying BIO. When using a non-blocking socket, 94nothing is to be done, but select() can be used to check for the required 95condition. When using a buffering BIO, like a BIO pair, data must be written 96into or retrieved out of the BIO before being able to continue. 97 98SSL_shutdown() can be modified to only set the connection to "shutdown" 99state but not actually send the "close notify" alert messages, 100see L<SSL_CTX_set_quiet_shutdown(3)>. 101When "quiet shutdown" is enabled, SSL_shutdown() will always succeed 102and return 1. 103 104=head1 RETURN VALUES 105 106The following return values can occur: 107 108=over 4 109 110=item Z<>0 111 112The shutdown is not yet finished: the "close notify" was send but the peer 113did not send it back yet. 114Call SSL_shutdown() again to do a bidirectional shutdown. 115The output of L<SSL_get_error(3)> may be misleading, as an 116erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. 117 118=item Z<>1 119 120The shutdown was successfully completed. The "close notify" alert was sent 121and the peer's "close notify" alert was received. 122 123=item E<lt>0 124 125The shutdown was not successful. 126Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. 127It can occur if an action is needed to continue the operation for non-blocking 128BIOs. 129 130It can also occur when not all data was read using SSL_read(). 131 132=back 133 134=head1 SEE ALSO 135 136L<SSL_get_error(3)>, L<SSL_connect(3)>, 137L<SSL_accept(3)>, L<SSL_set_shutdown(3)>, 138L<SSL_CTX_set_quiet_shutdown(3)>, 139L<SSL_clear(3)>, L<SSL_free(3)>, 140L<ssl(7)>, L<bio(7)> 141 142=head1 COPYRIGHT 143 144Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. 145 146Licensed under the OpenSSL license (the "License"). You may not use 147this file except in compliance with the License. You can obtain a copy 148in the file LICENSE in the source distribution or at 149L<https://www.openssl.org/source/license.html>. 150 151=cut 152