SSL_shutdown.pod revision 160814
168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisSSL_shutdown - shut down a TLS/SSL connection 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/ssl.h> 1068651Skris 1168651Skris int SSL_shutdown(SSL *ssl); 1268651Skris 1368651Skris=head1 DESCRIPTION 1468651Skris 1576866SkrisSSL_shutdown() shuts down an active TLS/SSL connection. It sends the 1676866Skris"close notify" shutdown alert to the peer. 1768651Skris 1876866Skris=head1 NOTES 1976866Skris 2076866SkrisSSL_shutdown() tries to send the "close notify" shutdown alert to the peer. 2176866SkrisWhether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and 2276866Skrisa currently open session is considered closed and good and will be kept in the 2376866Skrissession cache for further reuse. 2476866Skris 2589837SkrisThe shutdown procedure consists of 2 steps: the sending of the "close notify" 2689837Skrisshutdown alert and the reception of the peer's "close notify" shutdown 2789837Skrisalert. According to the TLS standard, it is acceptable for an application 2889837Skristo only send its shutdown alert and then close the underlying connection 2989837Skriswithout waiting for the peer's response (this way resources can be saved, 3089837Skrisas the process can already terminate or serve another connection). 3189837SkrisWhen the underlying connection shall be used for more communications, the 3289837Skriscomplete shutdown procedure (bidirectional "close notify" alerts) must be 3389837Skrisperformed, so that the peers stay synchronized. 3476866Skris 3589837SkrisSSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step 3689837Skrisbehaviour. 3789837Skris 3889837Skris=over 4 3989837Skris 4089837Skris=item When the application is the first party to send the "close notify" 41160814Ssimonalert, SSL_shutdown() will only send the alert and then set the 4289837SkrisSSL_SENT_SHUTDOWN flag (so that the session is considered good and will 4389837Skrisbe kept in cache). SSL_shutdown() will then return with 0. If a unidirectional 4489837Skrisshutdown is enough (the underlying connection shall be closed anyway), this 4589837Skrisfirst call to SSL_shutdown() is sufficient. In order to complete the 4689837Skrisbidirectional shutdown handshake, SSL_shutdown() must be called again. 4789837SkrisThe second call will make SSL_shutdown() wait for the peer's "close notify" 4889837Skrisshutdown alert. On success, the second call to SSL_shutdown() will return 4989837Skriswith 1. 5089837Skris 5189837Skris=item If the peer already sent the "close notify" alert B<and> it was 5289837Skrisalready processed implicitly inside another function 5389837Skris(L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. 5489837SkrisSSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN 5589837Skrisflag and will immediately return with 1. 5689837SkrisWhether SSL_RECEIVED_SHUTDOWN is already set can be checked using the 5789837SkrisSSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call. 5889837Skris 5989837Skris=back 6089837Skris 6189837SkrisIt is therefore recommended, to check the return value of SSL_shutdown() 6289837Skrisand call SSL_shutdown() again, if the bidirectional shutdown is not yet 6389837Skriscomplete (return value of the first call is 0). As the shutdown is not 6489837Skrisspecially handled in the SSLv2 protocol, SSL_shutdown() will succeed on 6589837Skristhe first call. 6689837Skris 6789837SkrisThe behaviour of SSL_shutdown() additionally depends on the underlying BIO. 6889837Skris 6968651SkrisIf the underlying BIO is B<blocking>, SSL_shutdown() will only return once the 7089837Skrishandshake step has been finished or an error occurred. 7168651Skris 7268651SkrisIf the underlying BIO is B<non-blocking>, SSL_shutdown() will also return 7368651Skriswhen the underlying BIO could not satisfy the needs of SSL_shutdown() 7468651Skristo continue the handshake. In this case a call to SSL_get_error() with the 7568651Skrisreturn value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or 7668651SkrisB<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 7768651Skristaking appropriate action to satisfy the needs of SSL_shutdown(). 7868651SkrisThe action depends on the underlying BIO. When using a non-blocking socket, 7968651Skrisnothing is to be done, but select() can be used to check for the required 8068651Skriscondition. When using a buffering BIO, like a BIO pair, data must be written 8168651Skrisinto or retrieved out of the BIO before being able to continue. 8268651Skris 8389837SkrisSSL_shutdown() can be modified to only set the connection to "shutdown" 8489837Skrisstate but not actually send the "close notify" alert messages, 8589837Skrissee L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>. 8689837SkrisWhen "quiet shutdown" is enabled, SSL_shutdown() will always succeed 8789837Skrisand return 1. 8889837Skris 8968651Skris=head1 RETURN VALUES 9068651Skris 9168651SkrisThe following return values can occur: 9268651Skris 9368651Skris=over 4 9468651Skris 9568651Skris=item 1 9668651Skris 9789837SkrisThe shutdown was successfully completed. The "close notify" alert was sent 9889837Skrisand the peer's "close notify" alert was received. 9968651Skris 10068651Skris=item 0 10168651Skris 10289837SkrisThe shutdown is not yet finished. Call SSL_shutdown() for a second time, 10389837Skrisif a bidirectional shutdown shall be performed. 10489837SkrisThe output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an 10589837Skriserroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. 10668651Skris 10768651Skris=item -1 10868651Skris 10968651SkrisThe shutdown was not successful because a fatal error occurred either 11089837Skrisat the protocol level or a connection failure occurred. It can also occur if 11168651Skrisaction is need to continue the operation for non-blocking BIOs. 11289837SkrisCall L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret> 11389837Skristo find out the reason. 11468651Skris 11568651Skris=back 11668651Skris 11768651Skris=head1 SEE ALSO 11868651Skris 11968651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, 12076866SkrisL<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, 12189837SkrisL<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, 12279998SkrisL<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>, 12376866SkrisL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 12468651Skris 12568651Skris=cut 126