Clarify that SSL_shutdown() must not be called after a fatal error

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

diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod
index 4e26514a22c900c58d6af8bc876e686212ae5316..150dd50f702a5c6617110ba534310a50e0dd9730 100644 (file)
--- a/doc/man3/SSL_get_error.pod
+++ b/doc/man3/SSL_get_error.pod
@@ -38,34 +38,53 @@ if and only if B<ret E<gt> 0>.
 
 =item SSL_ERROR_ZERO_RETURN
 
-The TLS/SSL connection has been closed.
-If the protocol version is SSL 3.0 or higher, this result code is returned only
-if a closure alert has occurred in the protocol, i.e. if the connection has been
-closed cleanly.
-Note that in this case B<SSL_ERROR_ZERO_RETURN> does not necessarily
+The TLS/SSL peer has closed the connection for writing by sending the
+close_notify alert.
+No more data can be read.
+Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily
 indicate that the underlying transport has been closed.
 
 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
 
-The operation did not complete; the same TLS/SSL I/O function should be
-called again later.  If, by then, the underlying B<BIO> has data
-available for reading (if the result code is B<SSL_ERROR_WANT_READ>)
-or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL
-protocol progress will take place, i.e. at least part of an TLS/SSL
-record will be read or written.  Note that the retry may again lead to
-a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition.
+The operation did not complete and can be retried later.
+
+B<SSL_ERROR_WANT_READ> is returned when the last operation was a read
+operation from a non-blocking B<BIO>.
+It means that not enough data was available at this time to complete the
+operation.
+If at a later time the underlying B<BIO> has data available for reading the same
+function can be called again.
+
+SSL_read() and SSL_read_ex() can also set B<SSL_ERROR_WANT_READ> when there is
+still unprocessed data available at either the B<SSL> or the B<BIO> layer, even
+for a blocking B<BIO>.
+See L<SSL_read(3)> for more information.
+
+B<SSL_ERROR_WANT_WRITE> is returned when the last operation was a write
+to a non-blocking B<BIO> and it was unable to sent all data to the B<BIO>.
+When the B<BIO> is writeable again, the same function can be called again.
+
+Note that the retry may again lead to an B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE> condition.
 There is no fixed upper limit for the number of iterations that
 may be necessary until progress becomes visible at application
 protocol level.
 
+It is safe to call SSL_read() or SSL_read_ex() when more data is available
+even when the call that set this error was an SSL_write() or SSL_write_ex().
+However if the call was an SSL_write() or SSL_write_ex(), it should be called
+again to continue sending the application data.
+
 For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or
 poll() on the underlying socket can be used to find out when the
 TLS/SSL I/O function should be retried.
 
 Caveat: Any TLS/SSL I/O function can lead to either of
-B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>.  In particular,
+B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>.
+In particular,
 SSL_read_ex(), SSL_read(), SSL_peek_ex(), or SSL_peek() may want to write data
-and SSL_write() or SSL_write_ex() may want to read data.  This is mainly because
+and SSL_write() or SSL_write_ex() may want to read data.
+This is mainly because
 TLS/SSL handshakes may occur at any time during the protocol (initiated by
 either the client or the server); SSL_read_ex(), SSL_read(), SSL_peek_ex(),
 SSL_peek(), SSL_write_ex(), and SSL_write() will handle any pending handshakes.
@@ -119,14 +138,20 @@ Details depend on the application.
 
 =item SSL_ERROR_SYSCALL
 
-Some non-recoverable I/O error occurred.
-The OpenSSL error queue may contain more information on the error.
-For socket I/O on Unix systems, consult B<errno> for details.
+Some non-recoverable, fatal I/O error occurred. The OpenSSL error queue may
+contain more information on the error. For socket I/O on Unix systems, consult
+B<errno> for details. If this error occurs then no further I/O operations should
+be performed on the connection and SSL_shutdown() must not be called.
+
+This value can also be returned for other errors, check the error queue for
+details.
 
 =item SSL_ERROR_SSL
 
-A failure in the SSL library occurred, usually a protocol error.  The
-OpenSSL error queue contains more information on the error.
+A non-recoverable, fatal error in the SSL library occurred, usually a protocol
+error.  The OpenSSL error queue contains more information on the error. If this
+error occurs then no further I/O operations should be performed on the
+connection and SSL_shutdown() must not be called.
 
 =back
 
@@ -136,14 +161,14 @@ L<ssl(7)>
 
 =head1 HISTORY
 
-SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
-SSL_ERROR_WANT_CLIENT_HELLO_CB was added in OpenSSL 1.1.1.
+The SSL_ERROR_WANT_ASYNC error code was added in OpenSSL 1.1.0.
+The SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.