aboutsummaryrefslogtreecommitdiffstats
path: root/crypto/openssl/doc/man3/SSL_shutdown.pod
diff options
context:
space:
mode:
Diffstat (limited to 'crypto/openssl/doc/man3/SSL_shutdown.pod')
-rw-r--r--crypto/openssl/doc/man3/SSL_shutdown.pod24
1 files changed, 18 insertions, 6 deletions
diff --git a/crypto/openssl/doc/man3/SSL_shutdown.pod b/crypto/openssl/doc/man3/SSL_shutdown.pod
index 732e5ada04ae..a77721c85269 100644
--- a/crypto/openssl/doc/man3/SSL_shutdown.pod
+++ b/crypto/openssl/doc/man3/SSL_shutdown.pod
@@ -95,13 +95,13 @@ 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
+If the underlying BIO is B<nonblocking>, 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,
+The action depends on the underlying BIO. When using a nonblocking 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.
@@ -116,6 +116,16 @@ 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.
=head1 RETURN VALUES
@@ -128,8 +138,10 @@ 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
@@ -140,7 +152,7 @@ and the peer's close_notify alert was received.
The shutdown was not successful.
Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason.
-It can occur if an action is needed to continue the operation for non-blocking
+It can occur if an action is needed to continue the operation for nonblocking
BIOs.
It can also occur when not all data was read using SSL_read().
@@ -157,7 +169,7 @@ L<ssl(7)>, L<bio(7)>
=head1 COPYRIGHT
-Copyright 2000-2019 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
this file except in compliance with the License. You can obtain a copy