X-Git-Url: https://git.openssl.org/?a=blobdiff_plain;f=doc%2Fman3%2FSSL_get_error.pod;h=150dd50f702a5c6617110ba534310a50e0dd9730;hb=ecbfaef2aad61fae0c29c04287913af11981b82e;hp=ddd72f706516a635cf5a09c7c42c2de2719d58fc;hpb=99d63d4662e16afbeff49f29b48f1c87d5558ed0;p=openssl.git diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod index ddd72f7065..150dd50f70 100644 --- 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(), SSL_peek(), or SSL_write() on B. The value returned by -that TLS/SSL I/O function must be passed to SSL_get_error() in parameter -B. +SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_write_ex() or +SSL_write() on B. The value returned by that TLS/SSL I/O function must be +passed to SSL_get_error() in parameter B. In addition to B and B, SSL_get_error() inspects the current thread's OpenSSL error queue. Thus, SSL_get_error() must be @@ -38,36 +38,56 @@ if and only if B 0>. =item SSL_ERROR_ZERO_RETURN -The TLS/SSL connection has been closed. If the protocol version is SSL 3.0 -or TLS 1.0, 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 -does not necessarily indicate that the underlying transport -has been closed. +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 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 has data -available for reading (if the result code is B) -or allows writing data (B), 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 or B condition. +The operation did not complete and can be retried later. + +B is returned when the last operation was a read +operation from a non-blocking B. +It means that not enough data was available at this time to complete the +operation. +If at a later time the underlying B has data available for reading the same +function can be called again. + +SSL_read() and SSL_read_ex() can also set B when there is +still unprocessed data available at either the B or the B layer, even +for a blocking B. +See L for more information. + +B is returned when the last operation was a write +to a non-blocking B and it was unable to sent all data to the B. +When the B is writeable again, the same function can be called again. + +Note that the retry may again lead to an B or +B 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 Bs (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 and B. In particular, -SSL_read() or SSL_peek() may want to write data and SSL_write() 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(), SSL_peek(), and SSL_write() will handle any pending handshakes. +B and B. +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 +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. =item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT @@ -109,35 +129,46 @@ through a call to L. The application should retry the operation after a currently executing asynchronous operation for the current thread has completed. +=item SSL_ERROR_WANT_CLIENT_HELLO_CB + +The operation did not complete because an application callback set by +SSL_CTX_set_client_hello_cb() has asked to be called again. +The TLS/SSL I/O function should be called again later. +Details depend on the application. + =item SSL_ERROR_SYSCALL -Some I/O error occurred. The OpenSSL error queue may contain more -information on the error. If the error queue is empty -(i.e. ERR_get_error() returns 0), B can be used to find out more -about the error: If B, an EOF was observed that violates -the protocol. If B, the underlying B reported an -I/O error (for socket I/O on Unix systems, consult B 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 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 =head1 SEE ALSO -L, L +L =head1 HISTORY -SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0. +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-2016 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.