Modify providers that keep track of underlying algorithms

[openssl.git] / doc / man3 / SSL_shutdown.pod

diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod
index f9b7212a33b051302b6f86a1defef5fe1b4eb15f..608cd7195ee92d0169d23625951eed8bff8aaadf 100644 (file)
--- a/doc/man3/SSL_shutdown.pod
+++ b/doc/man3/SSL_shutdown.pod
@@ -15,13 +15,15 @@ SSL_shutdown - shut down a TLS/SSL connection
 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.
@@ -48,6 +50,32 @@ SSL_shutdown() only closes the write direction.
 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.
+
 =head2 First to close the connection
 
 When the application is the first party to send the close_notify
@@ -85,34 +113,6 @@ If successful, SSL_shutdown() will return 1.
 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: