SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
close_notify shutdown alert to the peer.
-=head1 NOTES
-
SSL_shutdown() tries to send the close_notify shutdown alert to the peer.
Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
a currently open session is considered closed and good and will be kept in the
session cache for further reuse.
+Note that SSL_shutdown() must not be called if a previous fatal error has
+occurred on a connection i.e. if SSL_get_error() has returned SSL_ERROR_SYSCALL
+or SSL_ERROR_SSL.
+
The shutdown procedure consists of two steps: sending of the close_notify
shutdown alert, and reception of the peer's close_notify shutdown alert.
The order of those two steps depends on the application.
It is not possible to call SSL_write() after calling SSL_shutdown().
The read direction is closed by the peer.
+The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
+If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
+handshake step has been finished or an error occurred.
+
+If the underlying BIO is B<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 B<SSL_ERROR_WANT_READ> or
+B<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.
+
+After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
+to wait for the peer's close_notify alert.
+SSL_shutdown() will return 1 in that case.
+However, it is recommended to wait for it using SSL_read() instead.
+
+SSL_shutdown() can be modified to only set the connection to "shutdown"
+state but not actually send the close_notify alert messages,
+see L<SSL_CTX_set_quiet_shutdown(3)>.
+When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
+and return 1.
+Note that this is not standard compliant behaviour.
+It should only be done when the peer has a way to make sure all
+data has been received and doesn't wait for the close_notify alert
+message, otherwise an unexpected EOF will be reported.
+
+There are implementations that do not send the required close_notify alert.
+If there is a need to communicate with such an implementation, and it's clear
+that all data has been received, do not wait for the peer's close_notify alert.
+Waiting for the close_notify alert when the peer just closes the connection
+will result in an error being generated.
+The error can be ignored using the B<SSL_OP_IGNORE_UNEXPECTED_EOF>.
+For more information see L<SSL_CTX_set_options(3)>.
+
=head2 First to close the connection
When the application is the first party to send the close_notify
Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
-=head1 NOTES
-
-The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
-If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
-handshake step has been finished or an error occurred.
-
-If the underlying BIO is B<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 B<SSL_ERROR_WANT_READ> or
-B<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.
-
-After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
-to wait for the peer's close_notify alert.
-SSL_shutdown() will return 1 in that case.
-However, it is recommended to wait for it using SSL_read() instead.
-
-SSL_shutdown() can be modified to only set the connection to "shutdown"
-state but not actually send the close_notify alert messages,
-see L<SSL_CTX_set_quiet_shutdown(3)>.
-When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
-and return 1.
-
=head1 RETURN VALUES
The following return values can occur:
The shutdown is not yet finished: the close_notify was sent but the peer
did not send it back yet.
Call SSL_read() to do a bidirectional shutdown.
-The output of L<SSL_get_error(3)> may be misleading, as an
-erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
+
+Unlike most other function, returning 0 does not indicate an error.
+L<SSL_get_error(3)> should not get called, it may misleadingly
+indicate an error even though no error occurred.
=item Z<>1
L<SSL_get_error(3)>, L<SSL_connect(3)>,
L<SSL_accept(3)>, L<SSL_set_shutdown(3)>,
-L<SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)>, L<SSL_CTX_set_options(3)>
L<SSL_clear(3)>, L<SSL_free(3)>,
L<ssl(7)>, L<bio(7)>
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (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
L<https://www.openssl.org/source/license.html>.
projects / openssl.git / blobdiff