SSL_shutdown() has even more properties...

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

diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod
index ada25c8cae1ef9f8e3b6ddf2ef64828c374d0832..e205eac3091c27f9f99ec5a136cf2f980a15cd0b 100644 (file)
--- a/doc/ssl/SSL_shutdown.pod
+++ b/doc/ssl/SSL_shutdown.pod
@@ -23,16 +23,27 @@ a currently open session is considered closed and good and will be kept in the
 session cache for further reuse.
 
 The shutdown procedure consists of 2 steps: the sending of the "close notify"
-shutdown alert and the receipt ion of the peer's "close notify" shutdown
-alert:
+shutdown alert and the reception of the peer's "close notify" shutdown
+alert. According to the TLS standard, it is acceptable for an application
+to only send its shutdown alert and then close the underlying connection
+without waiting for the peer's response (this way resources can be saved,
+as the process can already terminate or serve another connection).
+When the underlying connection shall be used for more communications, the
+complete shutdown procedure (bidirectional "close notify" alerts) must be
+performed, so that the peers stay synchronized.
+
+SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step
+behaviour.
 
 =over 4
 
 =item When the application is the first party to send the "close notify"
 alert, SSL_shutdown() will only send the alert and the set the
 SSL_SENT_SHUTDOWN flag (so that the session is considered good and will
-be kept in cache). SSL_shutdown() will then return with 0. In order to
-complete the shutdown handshake, SSL_shutdown() must be called again.
+be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional
+shutdown is enough (the underlying connection shall be closed anyway), this
+first call to SSL_shutdown() is sufficient. In order to complete the
+bidirectional shutdown handshake, SSL_shutdown() must be called again.
 The second call will make SSL_shutdown() wait for the peer's "close notify"
 shutdown alert. On success, the second call to SSL_shutdown() will return
 with 1.
@@ -40,7 +51,7 @@ 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 and will immediately return with 1.
+alert, set the SSL_SENT_SHUTDOWN flag and will immediately return with 1.
 
 =back
 
@@ -66,6 +77,12 @@ 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.
 
+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)|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:
@@ -79,7 +96,8 @@ and the peer's "close notify" alert was received.
 
 =item 0
 
-The shutdown is not yet finished. Call SSL_shutdown() for a second time.
+The shutdown is not yet finished. Call SSL_shutdown() for a second time,
+if a bidirectional shutdown shall be performed.
 The output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an
 erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
 
@@ -97,6 +115,7 @@ to find out the reason.
 
 L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
 L<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>,
 L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>,
 L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>