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 (SSL_R_UNEXPECTED_EOF_WHILE_READING). This error reason
+code may be used for control flow decisions (see the man page for
+L<ERR_GET_REASON(3)> for further details on this).
+
=head1 RETURN VALUES
The following return values can currently occur:
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>.
+For non-QUIC SSL objects, B<SSL_ERROR_WANT_READ> is returned when the last
+operation was a read 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
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.
+For non-QUIC SSL objects, B<SSL_ERROR_WANT_WRITE> is returned when the last
+operation was a write to a nonblocking B<BIO> and it was unable to send 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.
may be necessary until progress becomes visible at application
protocol level.
+For QUIC SSL objects, the meaning of B<SSL_ERROR_WANT_READ> and
+B<SSL_ERROR_WANT_WRITE> have different but largely compatible semantics. Since
+QUIC implements its own flow control and uses UDP datagrams, backpressure
+conditions in terms of the underlying BIO providing network I/O are not directly
+relevant to the circumstances in which these errors are produced. In particular,
+B<SSL_ERROR_WANT_WRITE> indicates that the OpenSSL internal send buffer for a
+given QUIC stream has been filled. Likewise, B<SSL_ERROR_WANT_READ> indicates
+that the OpenSSL internal receive buffer for a given QUIC stream is empty.
+
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.
+However, if the call was an SSL_write() or SSL_write_ex(), it should be called
+again to continue sending the application data. If you get B<SSL_ERROR_WANT_WRITE>
+from SSL_write() or SSL_write_ex() then you should not do any other operation
+that could trigger B<IO> other than to repeat the previous SSL_write() call.
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
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2024 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
projects / thirdparty / openssl.git / blobdiff