From: Hugo Landau <hlandau@openssl.org>
Date: Thu, 26 Jan 2023 13:24:35 +0000 (+0000)
Subject: QUIC FIN Support: Documentation fixups
X-Git-Tag: openssl-3.2.0-alpha1~1369
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ff6e3a26f92208df8b4257760c72cae5c0e0269c;p=thirdparty%2Fopenssl.git

QUIC FIN Support: Documentation fixups

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19897)
---

diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod
index 08864364cc6..f0bdc5dd742 100644
--- a/doc/man3/SSL_shutdown.pod
+++ b/doc/man3/SSL_shutdown.pod
@@ -182,7 +182,7 @@ applications. Ordinarily, QUIC expects a connection to continue to be serviced
 for a substantial period of time after it is nominally closed. This is necessary
 to ensure that any connection closure notification sent to the peer was
 successfully received. However, a consequence of this is that a fully
-RFC-compliant QUIC connection closure process could take on the order of
+RFC-compliant QUIC connection closure process could take of the order of
 seconds. This may be unsuitable for some applications, such as short-lived
 processes which need to exit immediately after completing an application-layer
 transaction.
@@ -226,29 +226,33 @@ by making a subsequent call to SSL_shutdown_ex() without the flag set.
 
 =head1 RETURN VALUES
 
-For both SSL_shutdown() and SSL_shutdown_ex() following return values can occur:
+For both SSL_shutdown() and SSL_shutdown_ex() the following return values can occur:
 
 =over 4
 
 =item Z<>0
 
-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 shutdown process is ongoing and has not yet completed.
 
-For QUIC connection SSL objects, a CONNECTION_CLOSE frame may have been sent
-but the connection closure process has not yet completed.
+For TLS and DTLS, this means that a close_notify alert has been sent but the
+peer has not yet replied in turn with its own close_notify.
+
+For QUIC connection SSL objects, a CONNECTION_CLOSE frame may have been
+sent but the connection closure process has not yet completed.
 
 Unlike most other functions, returning 0 does not indicate an error.
-L<SSL_get_error(3)> should not be called; it may misleadingly
-indicate an error even though no error occurred.
+L<SSL_get_error(3)> should not be called; it may misleadingly indicate an error
+even though no error occurred.
 
 =item Z<>1
 
-The shutdown was successfully completed. For non-QUIC SSL objects, this means
-that the close_notify alert was sent and the peer's close_notify alert was
-received. For QUIC connection SSL objects, this means that the connection
-closure process has completed.
+The shutdown was successfully completed.
+
+For TLS and DTLS, this means that a close_notify alert was sent and the peer's
+close_notify alert was received.
+
+For QUIC connection SSL objects, this means that the connection closure process
+has completed.
 
 =item E<lt>0
 
diff --git a/doc/man3/SSL_stream_conclude.pod b/doc/man3/SSL_stream_conclude.pod
index a4da6ef1f78..a3573722126 100644
--- a/doc/man3/SSL_stream_conclude.pod
+++ b/doc/man3/SSL_stream_conclude.pod
@@ -38,10 +38,14 @@ TODO(QUIC): Once streams are implemented, revise this text
 
 =end comment
 
+This function is not supported on non-QUIC SSL objects.
+
 =head1 RETURN VALUES
 
 Returns 1 on success and 0 on failure.
 
+Returns 0 if called on a non-QUIC SSL object.
+
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_shutdown_ex(3)>