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 25344604SjkimNote that SSL_shutdown() must not be called if a previous fatal error has 26344604Sjkimoccurred on a connection i.e. if SSL_get_error() has returned SSL_ERROR_SYSCALL 27344604Sjkimor SSL_ERROR_SSL. 28344604Sjkim 2989837SkrisThe shutdown procedure consists of 2 steps: the sending of the "close notify" 3089837Skrisshutdown alert and the reception of the peer's "close notify" shutdown 3189837Skrisalert. According to the TLS standard, it is acceptable for an application 3289837Skristo only send its shutdown alert and then close the underlying connection 3389837Skriswithout waiting for the peer's response (this way resources can be saved, 3489837Skrisas the process can already terminate or serve another connection). 3589837SkrisWhen the underlying connection shall be used for more communications, the 3689837Skriscomplete shutdown procedure (bidirectional "close notify" alerts) must be 3789837Skrisperformed, so that the peers stay synchronized. 3876866Skris 3989837SkrisSSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step 4089837Skrisbehaviour. 4189837Skris 4289837Skris=over 4 4389837Skris 4489837Skris=item When the application is the first party to send the "close notify" 45160814Ssimonalert, SSL_shutdown() will only send the alert and then set the 4689837SkrisSSL_SENT_SHUTDOWN flag (so that the session is considered good and will 4789837Skrisbe kept in cache). SSL_shutdown() will then return with 0. If a unidirectional 4889837Skrisshutdown is enough (the underlying connection shall be closed anyway), this 4989837Skrisfirst call to SSL_shutdown() is sufficient. In order to complete the 5089837Skrisbidirectional shutdown handshake, SSL_shutdown() must be called again. 5189837SkrisThe second call will make SSL_shutdown() wait for the peer's "close notify" 5289837Skrisshutdown alert. On success, the second call to SSL_shutdown() will return 5389837Skriswith 1. 5489837Skris 5589837Skris=item If the peer already sent the "close notify" alert B<and> it was 5689837Skrisalready processed implicitly inside another function 5789837Skris(L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. 5889837SkrisSSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN 5989837Skrisflag and will immediately return with 1. 6089837SkrisWhether SSL_RECEIVED_SHUTDOWN is already set can be checked using the 6189837SkrisSSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call. 6289837Skris 6389837Skris=back 6489837Skris 6589837SkrisIt is therefore recommended, to check the return value of SSL_shutdown() 6689837Skrisand call SSL_shutdown() again, if the bidirectional shutdown is not yet 6789837Skriscomplete (return value of the first call is 0). As the shutdown is not 6889837Skrisspecially handled in the SSLv2 protocol, SSL_shutdown() will succeed on 6989837Skristhe first call. 7089837Skris 7189837SkrisThe behaviour of SSL_shutdown() additionally depends on the underlying BIO. 7289837Skris 7368651SkrisIf the underlying BIO is B<blocking>, SSL_shutdown() will only return once the 7489837Skrishandshake step has been finished or an error occurred. 7568651Skris 7668651SkrisIf the underlying BIO is B<non-blocking>, SSL_shutdown() will also return 7768651Skriswhen the underlying BIO could not satisfy the needs of SSL_shutdown() 7868651Skristo continue the handshake. In this case a call to SSL_get_error() with the 7968651Skrisreturn value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or 8068651SkrisB<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 8168651Skristaking appropriate action to satisfy the needs of SSL_shutdown(). 8268651SkrisThe action depends on the underlying BIO. When using a non-blocking socket, 8368651Skrisnothing is to be done, but select() can be used to check for the required 8468651Skriscondition. When using a buffering BIO, like a BIO pair, data must be written 8568651Skrisinto or retrieved out of the BIO before being able to continue. 8668651Skris 8789837SkrisSSL_shutdown() can be modified to only set the connection to "shutdown" 8889837Skrisstate but not actually send the "close notify" alert messages, 8989837Skrissee L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>. 9089837SkrisWhen "quiet shutdown" is enabled, SSL_shutdown() will always succeed 9189837Skrisand return 1. 9289837Skris 9368651Skris=head1 RETURN VALUES 9468651Skris 9568651SkrisThe following return values can occur: 9668651Skris 9768651Skris=over 4 9868651Skris 99261037Sjkim=item Z<>0 10068651Skris 10189837SkrisThe shutdown is not yet finished. Call SSL_shutdown() for a second time, 10289837Skrisif a bidirectional shutdown shall be performed. 10389837SkrisThe output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an 10489837Skriserroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. 10568651Skris 106261037Sjkim=item Z<>1 107261037Sjkim 108261037SjkimThe shutdown was successfully completed. The "close notify" alert was sent 109261037Sjkimand the peer's "close notify" alert was received. 110261037Sjkim 111290207Sjkim=item E<lt>0 11268651Skris 11368651SkrisThe shutdown was not successful because a fatal error occurred either 11489837Skrisat the protocol level or a connection failure occurred. It can also occur if 11568651Skrisaction is need to continue the operation for non-blocking BIOs. 11689837SkrisCall L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret> 11789837Skristo find out the reason. 11868651Skris 11968651Skris=back 12068651Skris 12168651Skris=head1 SEE ALSO 12268651Skris 12368651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, 12476866SkrisL<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, 12589837SkrisL<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, 12679998SkrisL<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>, 12776866SkrisL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 12868651Skris 12968651Skris=cut 130