From d93eb21c7c1e39db098a7f1331a75cc95a783c2a Mon Sep 17 00:00:00 2001
From: =?utf8?q?Lutz=20J=C3=A4nicke?= <jaenicke@openssl.org>
Date: Mon, 20 Aug 2001 14:34:16 +0000
Subject: [PATCH] More interdependencies with respect to shutdown behaviour.

---
 doc/ssl/SSL_read.pod         | 16 +++++++++++++---
 doc/ssl/SSL_set_shutdown.pod |  5 ++++-
 doc/ssl/SSL_shutdown.pod     |  9 ++++++---
 doc/ssl/SSL_write.pod        | 14 ++++++++++++--
 4 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod
index e9557ba1a1..6b47f2fbd1 100644
--- a/doc/ssl/SSL_read.pod
+++ b/doc/ssl/SSL_read.pod
@@ -83,9 +83,18 @@ bytes actually read from the TLS/SSL connection.
 
 =item 0
 
-The read operation was not successful, probably because no data was
-available. Call SSL_get_error() with the return value B<ret> to find out,
-whether an error occurred.
+The read operation was not successful, the SSL connection was closed by the
+peer by sending a "close notify" alert. The SSL_RECEIVED_SHUTDOWN flag in
+the ssl shutdown state is set (see L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>).
+Call SSL_get_error() with the return value B<ret> to find out,
+whether an error occurred or the connection was shut down cleanly
+(SSL_ERROR_ZERO_RETURN).
+
+SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
+only be detected, whether the underlying connection was closed. It cannot
+be checked, whether the closure was initiated by the peer or by something
+else.
 
 =item E<lt>0
 
@@ -101,6 +110,7 @@ L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>,
 L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
 L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>
 L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
 L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
 
 =cut
diff --git a/doc/ssl/SSL_set_shutdown.pod b/doc/ssl/SSL_set_shutdown.pod
index 119bb83c55..6289e635d9 100644
--- a/doc/ssl/SSL_set_shutdown.pod
+++ b/doc/ssl/SSL_set_shutdown.pod
@@ -46,7 +46,10 @@ The shutdown state of the connection is used to determine the state of
 the ssl session. If the session is still open, when
 L<SSL_clear(3)|SSL_clear(3)> or L<SSL_free(3)|SSL_free(3)> is called,
 it is considered bad and removed according to RFC2246.
-The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN.
+The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN
+(according to the TLS RFC, it is acceptable to only send the "close notify"
+alert but to not wait for the peer's answer, when the underlying connection
+is closed).
 SSL_set_shutdown() can be used to set this state without sending a
 close alert to the peer (see L<SSL_shutdown(3)|SSL_shutdown(3)>).
 
diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod
index e205eac309..6b5012be7a 100644
--- a/doc/ssl/SSL_shutdown.pod
+++ b/doc/ssl/SSL_shutdown.pod
@@ -49,9 +49,12 @@ shutdown alert. On success, the second call to SSL_shutdown() will return
 with 1.
 
 =item If the peer already sent the "close notify" alert B<and> it was
-already processed implicitly inside another call of e.g.
-B<SSL_read(3)|SSL_read(3)>, SSL_shutdown() will send the "close notify"
-alert, set the SSL_SENT_SHUTDOWN flag and will immediately return with 1.
+already processed implicitly inside another function
+(L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
+SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN
+flag and will immediately return with 1.
+Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
+SSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call.
 
 =back
 
diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod
index da66f0f056..7299f6e2ee 100644
--- a/doc/ssl/SSL_write.pod
+++ b/doc/ssl/SSL_write.pod
@@ -78,8 +78,18 @@ bytes actually written to the TLS/SSL connection.
 
 =item 0
 
-The write operation was not successful. Call SSL_get_error() with the return
-value B<ret> to find out, whether an error occurred.
+The write operation was not successful, because the write side of the
+SSL connection was shut down (the SSL_SENT_SHUTDOWN flag in the shutdown
+state is set) by calling L<SSL_shutdown(3)|SSL_shutdown(3)> or
+L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>. It is also possible, that the
+underlying connection was closed.
+Call SSL_get_error() with the return value B<ret> to find out,
+whether an error occurred or the connection was shut down cleanly
+(SSL_ERROR_ZERO_RETURN).
+
+SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
+only be detected, whether the underlying connection was closed. It cannot
+be checked, why the closure happened.
 
 =item E<lt>0
 
-- 
2.25.1