Deprecate EVP_PKEY_set1_tls_encodedpoint()

[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 876aac7b785993d54ee14e801509ca6d3ca9a9c6..c52fd04d07e0b3cc5ca52ffba9bfefd1f71905f8 100644 (file)
--- a/doc/man3/SSL_get_error.pod
+++ b/doc/man3/SSL_get_error.pod
@@ -14,9 +14,9 @@ SSL_get_error - obtain result code for TLS/SSL I/O operation
 
 SSL_get_error() returns a result code (suitable for the C "switch"
 statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(),
-SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_write_ex() or
-SSL_write() on B<ssl>.  The value returned by that TLS/SSL I/O function must be
-passed to SSL_get_error() in parameter B<ret>.
+SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_shutdown(),
+SSL_write_ex() or SSL_write() on B<ssl>.  The value returned by that TLS/SSL I/O
+function must be passed to SSL_get_error() in parameter B<ret>.
 
 In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
 current thread's OpenSSL error queue.  Thus, SSL_get_error() must be
@@ -25,6 +25,15 @@ other OpenSSL function calls should appear in between.  The current
 thread's error queue must be empty before the TLS/SSL I/O operation is
 attempted, or SSL_get_error() will not work reliably.
 
+=head1 NOTES
+
+Some TLS implementations do not send a close_notify alert on shutdown.
+
+On an unexpected EOF, versions before OpenSSL 3.0 returned
+B<SSL_ERROR_SYSCALL>, nothing was added to the error stack, and errno was 0.
+Since OpenSSL 3.0 the returned error is B<SSL_ERROR_SSL> with a meaningful
+error on the error stack.
+
 =head1 RETURN VALUES
 
 The following return values can currently occur:
@@ -44,12 +53,15 @@ No more data can be read.
 Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily
 indicate that the underlying transport has been closed.
 
+This error can also appear when the option B<SSL_OP_IGNORE_UNEXPECTED_EOF>
+is set. See L<SSL_CTX_set_options(3)> for more details.
+
 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
 
 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>.
+operation from a nonblocking 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
@@ -61,8 +73,8 @@ 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.
+to a nonblocking B<BIO> and it was unable to sent all data to the B<BIO>.
+When the B<BIO> is writable 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.
@@ -72,7 +84,7 @@ 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
+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
@@ -138,17 +150,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
 
@@ -163,7 +178,7 @@ The SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
 
 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