1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948SSL_shutdown - shut down a TLS/SSL connection 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948 #include <openssl/ssl.h> 10*2175Sjp161948 11*2175Sjp161948 int SSL_shutdown(SSL *ssl); 12*2175Sjp161948 13*2175Sjp161948=head1 DESCRIPTION 14*2175Sjp161948 15*2175Sjp161948SSL_shutdown() shuts down an active TLS/SSL connection. It sends the 16*2175Sjp161948"close notify" shutdown alert to the peer. 17*2175Sjp161948 18*2175Sjp161948=head1 NOTES 19*2175Sjp161948 20*2175Sjp161948SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. 21*2175Sjp161948Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and 22*2175Sjp161948a currently open session is considered closed and good and will be kept in the 23*2175Sjp161948session cache for further reuse. 24*2175Sjp161948 25*2175Sjp161948The shutdown procedure consists of 2 steps: the sending of the "close notify" 26*2175Sjp161948shutdown alert and the reception of the peer's "close notify" shutdown 27*2175Sjp161948alert. According to the TLS standard, it is acceptable for an application 28*2175Sjp161948to only send its shutdown alert and then close the underlying connection 29*2175Sjp161948without waiting for the peer's response (this way resources can be saved, 30*2175Sjp161948as the process can already terminate or serve another connection). 31*2175Sjp161948When the underlying connection shall be used for more communications, the 32*2175Sjp161948complete shutdown procedure (bidirectional "close notify" alerts) must be 33*2175Sjp161948performed, so that the peers stay synchronized. 34*2175Sjp161948 35*2175Sjp161948SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step 36*2175Sjp161948behaviour. 37*2175Sjp161948 38*2175Sjp161948=over 4 39*2175Sjp161948 40*2175Sjp161948=item When the application is the first party to send the "close notify" 41*2175Sjp161948alert, SSL_shutdown() will only send the alert and then set the 42*2175Sjp161948SSL_SENT_SHUTDOWN flag (so that the session is considered good and will 43*2175Sjp161948be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional 44*2175Sjp161948shutdown is enough (the underlying connection shall be closed anyway), this 45*2175Sjp161948first call to SSL_shutdown() is sufficient. In order to complete the 46*2175Sjp161948bidirectional shutdown handshake, SSL_shutdown() must be called again. 47*2175Sjp161948The second call will make SSL_shutdown() wait for the peer's "close notify" 48*2175Sjp161948shutdown alert. On success, the second call to SSL_shutdown() will return 49*2175Sjp161948with 1. 50*2175Sjp161948 51*2175Sjp161948=item If the peer already sent the "close notify" alert B<and> it was 52*2175Sjp161948already processed implicitly inside another function 53*2175Sjp161948(L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. 54*2175Sjp161948SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN 55*2175Sjp161948flag and will immediately return with 1. 56*2175Sjp161948Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the 57*2175Sjp161948SSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call. 58*2175Sjp161948 59*2175Sjp161948=back 60*2175Sjp161948 61*2175Sjp161948It is therefore recommended, to check the return value of SSL_shutdown() 62*2175Sjp161948and call SSL_shutdown() again, if the bidirectional shutdown is not yet 63*2175Sjp161948complete (return value of the first call is 0). As the shutdown is not 64*2175Sjp161948specially handled in the SSLv2 protocol, SSL_shutdown() will succeed on 65*2175Sjp161948the first call. 66*2175Sjp161948 67*2175Sjp161948The behaviour of SSL_shutdown() additionally depends on the underlying BIO. 68*2175Sjp161948 69*2175Sjp161948If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the 70*2175Sjp161948handshake step has been finished or an error occurred. 71*2175Sjp161948 72*2175Sjp161948If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return 73*2175Sjp161948when the underlying BIO could not satisfy the needs of SSL_shutdown() 74*2175Sjp161948to continue the handshake. In this case a call to SSL_get_error() with the 75*2175Sjp161948return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or 76*2175Sjp161948B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 77*2175Sjp161948taking appropriate action to satisfy the needs of SSL_shutdown(). 78*2175Sjp161948The action depends on the underlying BIO. When using a non-blocking socket, 79*2175Sjp161948nothing is to be done, but select() can be used to check for the required 80*2175Sjp161948condition. When using a buffering BIO, like a BIO pair, data must be written 81*2175Sjp161948into or retrieved out of the BIO before being able to continue. 82*2175Sjp161948 83*2175Sjp161948SSL_shutdown() can be modified to only set the connection to "shutdown" 84*2175Sjp161948state but not actually send the "close notify" alert messages, 85*2175Sjp161948see L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>. 86*2175Sjp161948When "quiet shutdown" is enabled, SSL_shutdown() will always succeed 87*2175Sjp161948and return 1. 88*2175Sjp161948 89*2175Sjp161948=head1 RETURN VALUES 90*2175Sjp161948 91*2175Sjp161948The following return values can occur: 92*2175Sjp161948 93*2175Sjp161948=over 4 94*2175Sjp161948 95*2175Sjp161948=item 1 96*2175Sjp161948 97*2175Sjp161948The shutdown was successfully completed. The "close notify" alert was sent 98*2175Sjp161948and the peer's "close notify" alert was received. 99*2175Sjp161948 100*2175Sjp161948=item 0 101*2175Sjp161948 102*2175Sjp161948The shutdown is not yet finished. Call SSL_shutdown() for a second time, 103*2175Sjp161948if a bidirectional shutdown shall be performed. 104*2175Sjp161948The output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an 105*2175Sjp161948erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. 106*2175Sjp161948 107*2175Sjp161948=item -1 108*2175Sjp161948 109*2175Sjp161948The shutdown was not successful because a fatal error occurred either 110*2175Sjp161948at the protocol level or a connection failure occurred. It can also occur if 111*2175Sjp161948action is need to continue the operation for non-blocking BIOs. 112*2175Sjp161948Call L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret> 113*2175Sjp161948to find out the reason. 114*2175Sjp161948 115*2175Sjp161948=back 116*2175Sjp161948 117*2175Sjp161948=head1 SEE ALSO 118*2175Sjp161948 119*2175Sjp161948L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, 120*2175Sjp161948L<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, 121*2175Sjp161948L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, 122*2175Sjp161948L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>, 123*2175Sjp161948L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 124*2175Sjp161948 125*2175Sjp161948=cut 126