1*1dcdf01fSchristos=pod 2*1dcdf01fSchristos 3*1dcdf01fSchristos=head1 NAME 4*1dcdf01fSchristos 5*1dcdf01fSchristosSSL_get_error - obtain result code for TLS/SSL I/O operation 6*1dcdf01fSchristos 7*1dcdf01fSchristos=head1 SYNOPSIS 8*1dcdf01fSchristos 9*1dcdf01fSchristos #include <openssl/ssl.h> 10*1dcdf01fSchristos 11*1dcdf01fSchristos int SSL_get_error(const SSL *ssl, int ret); 12*1dcdf01fSchristos 13*1dcdf01fSchristos=head1 DESCRIPTION 14*1dcdf01fSchristos 15*1dcdf01fSchristosSSL_get_error() returns a result code (suitable for the C "switch" 16*1dcdf01fSchristosstatement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(), 17*1dcdf01fSchristosSSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_shutdown(), 18*1dcdf01fSchristosSSL_write_ex() or SSL_write() on B<ssl>. The value returned by that TLS/SSL I/O 19*1dcdf01fSchristosfunction must be passed to SSL_get_error() in parameter B<ret>. 20*1dcdf01fSchristos 21*1dcdf01fSchristosIn addition to B<ssl> and B<ret>, SSL_get_error() inspects the 22*1dcdf01fSchristoscurrent thread's OpenSSL error queue. Thus, SSL_get_error() must be 23*1dcdf01fSchristosused in the same thread that performed the TLS/SSL I/O operation, and no 24*1dcdf01fSchristosother OpenSSL function calls should appear in between. The current 25*1dcdf01fSchristosthread's error queue must be empty before the TLS/SSL I/O operation is 26*1dcdf01fSchristosattempted, or SSL_get_error() will not work reliably. 27*1dcdf01fSchristos 28*1dcdf01fSchristos=head1 RETURN VALUES 29*1dcdf01fSchristos 30*1dcdf01fSchristosThe following return values can currently occur: 31*1dcdf01fSchristos 32*1dcdf01fSchristos=over 4 33*1dcdf01fSchristos 34*1dcdf01fSchristos=item SSL_ERROR_NONE 35*1dcdf01fSchristos 36*1dcdf01fSchristosThe TLS/SSL I/O operation completed. This result code is returned 37*1dcdf01fSchristosif and only if B<ret E<gt> 0>. 38*1dcdf01fSchristos 39*1dcdf01fSchristos=item SSL_ERROR_ZERO_RETURN 40*1dcdf01fSchristos 41*1dcdf01fSchristosThe TLS/SSL peer has closed the connection for writing by sending the 42*1dcdf01fSchristosclose_notify alert. 43*1dcdf01fSchristosNo more data can be read. 44*1dcdf01fSchristosNote that B<SSL_ERROR_ZERO_RETURN> does not necessarily 45*1dcdf01fSchristosindicate that the underlying transport has been closed. 46*1dcdf01fSchristos 47*1dcdf01fSchristos=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE 48*1dcdf01fSchristos 49*1dcdf01fSchristosThe operation did not complete and can be retried later. 50*1dcdf01fSchristos 51*1dcdf01fSchristosB<SSL_ERROR_WANT_READ> is returned when the last operation was a read 52*1dcdf01fSchristosoperation from a nonblocking B<BIO>. 53*1dcdf01fSchristosIt means that not enough data was available at this time to complete the 54*1dcdf01fSchristosoperation. 55*1dcdf01fSchristosIf at a later time the underlying B<BIO> has data available for reading the same 56*1dcdf01fSchristosfunction can be called again. 57*1dcdf01fSchristos 58*1dcdf01fSchristosSSL_read() and SSL_read_ex() can also set B<SSL_ERROR_WANT_READ> when there is 59*1dcdf01fSchristosstill unprocessed data available at either the B<SSL> or the B<BIO> layer, even 60*1dcdf01fSchristosfor a blocking B<BIO>. 61*1dcdf01fSchristosSee L<SSL_read(3)> for more information. 62*1dcdf01fSchristos 63*1dcdf01fSchristosB<SSL_ERROR_WANT_WRITE> is returned when the last operation was a write 64*1dcdf01fSchristosto a nonblocking B<BIO> and it was unable to sent all data to the B<BIO>. 65*1dcdf01fSchristosWhen the B<BIO> is writable again, the same function can be called again. 66*1dcdf01fSchristos 67*1dcdf01fSchristosNote that the retry may again lead to an B<SSL_ERROR_WANT_READ> or 68*1dcdf01fSchristosB<SSL_ERROR_WANT_WRITE> condition. 69*1dcdf01fSchristosThere is no fixed upper limit for the number of iterations that 70*1dcdf01fSchristosmay be necessary until progress becomes visible at application 71*1dcdf01fSchristosprotocol level. 72*1dcdf01fSchristos 73*1dcdf01fSchristosIt is safe to call SSL_read() or SSL_read_ex() when more data is available 74*1dcdf01fSchristoseven when the call that set this error was an SSL_write() or SSL_write_ex(). 75*1dcdf01fSchristosHowever, if the call was an SSL_write() or SSL_write_ex(), it should be called 76*1dcdf01fSchristosagain to continue sending the application data. 77*1dcdf01fSchristos 78*1dcdf01fSchristosFor socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or 79*1dcdf01fSchristospoll() on the underlying socket can be used to find out when the 80*1dcdf01fSchristosTLS/SSL I/O function should be retried. 81*1dcdf01fSchristos 82*1dcdf01fSchristosCaveat: Any TLS/SSL I/O function can lead to either of 83*1dcdf01fSchristosB<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. 84*1dcdf01fSchristosIn particular, 85*1dcdf01fSchristosSSL_read_ex(), SSL_read(), SSL_peek_ex(), or SSL_peek() may want to write data 86*1dcdf01fSchristosand SSL_write() or SSL_write_ex() may want to read data. 87*1dcdf01fSchristosThis is mainly because 88*1dcdf01fSchristosTLS/SSL handshakes may occur at any time during the protocol (initiated by 89*1dcdf01fSchristoseither the client or the server); SSL_read_ex(), SSL_read(), SSL_peek_ex(), 90*1dcdf01fSchristosSSL_peek(), SSL_write_ex(), and SSL_write() will handle any pending handshakes. 91*1dcdf01fSchristos 92*1dcdf01fSchristos=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT 93*1dcdf01fSchristos 94*1dcdf01fSchristosThe operation did not complete; the same TLS/SSL I/O function should be 95*1dcdf01fSchristoscalled again later. The underlying BIO was not connected yet to the peer 96*1dcdf01fSchristosand the call would block in connect()/accept(). The SSL function should be 97*1dcdf01fSchristoscalled again when the connection is established. These messages can only 98*1dcdf01fSchristosappear with a BIO_s_connect() or BIO_s_accept() BIO, respectively. 99*1dcdf01fSchristosIn order to find out, when the connection has been successfully established, 100*1dcdf01fSchristoson many platforms select() or poll() for writing on the socket file descriptor 101*1dcdf01fSchristoscan be used. 102*1dcdf01fSchristos 103*1dcdf01fSchristos=item SSL_ERROR_WANT_X509_LOOKUP 104*1dcdf01fSchristos 105*1dcdf01fSchristosThe operation did not complete because an application callback set by 106*1dcdf01fSchristosSSL_CTX_set_client_cert_cb() has asked to be called again. 107*1dcdf01fSchristosThe TLS/SSL I/O function should be called again later. 108*1dcdf01fSchristosDetails depend on the application. 109*1dcdf01fSchristos 110*1dcdf01fSchristos=item SSL_ERROR_WANT_ASYNC 111*1dcdf01fSchristos 112*1dcdf01fSchristosThe operation did not complete because an asynchronous engine is still 113*1dcdf01fSchristosprocessing data. This will only occur if the mode has been set to SSL_MODE_ASYNC 114*1dcdf01fSchristosusing L<SSL_CTX_set_mode(3)> or L<SSL_set_mode(3)> and an asynchronous capable 115*1dcdf01fSchristosengine is being used. An application can determine whether the engine has 116*1dcdf01fSchristoscompleted its processing using select() or poll() on the asynchronous wait file 117*1dcdf01fSchristosdescriptor. This file descriptor is available by calling 118*1dcdf01fSchristosL<SSL_get_all_async_fds(3)> or L<SSL_get_changed_async_fds(3)>. The TLS/SSL I/O 119*1dcdf01fSchristosfunction should be called again later. The function B<must> be called from the 120*1dcdf01fSchristossame thread that the original call was made from. 121*1dcdf01fSchristos 122*1dcdf01fSchristos=item SSL_ERROR_WANT_ASYNC_JOB 123*1dcdf01fSchristos 124*1dcdf01fSchristosThe asynchronous job could not be started because there were no async jobs 125*1dcdf01fSchristosavailable in the pool (see ASYNC_init_thread(3)). This will only occur if the 126*1dcdf01fSchristosmode has been set to SSL_MODE_ASYNC using L<SSL_CTX_set_mode(3)> or 127*1dcdf01fSchristosL<SSL_set_mode(3)> and a maximum limit has been set on the async job pool 128*1dcdf01fSchristosthrough a call to L<ASYNC_init_thread(3)>. The application should retry the 129*1dcdf01fSchristosoperation after a currently executing asynchronous operation for the current 130*1dcdf01fSchristosthread has completed. 131*1dcdf01fSchristos 132*1dcdf01fSchristos=item SSL_ERROR_WANT_CLIENT_HELLO_CB 133*1dcdf01fSchristos 134*1dcdf01fSchristosThe operation did not complete because an application callback set by 135*1dcdf01fSchristosSSL_CTX_set_client_hello_cb() has asked to be called again. 136*1dcdf01fSchristosThe TLS/SSL I/O function should be called again later. 137*1dcdf01fSchristosDetails depend on the application. 138*1dcdf01fSchristos 139*1dcdf01fSchristos=item SSL_ERROR_SYSCALL 140*1dcdf01fSchristos 141*1dcdf01fSchristosSome non-recoverable, fatal I/O error occurred. The OpenSSL error queue may 142*1dcdf01fSchristoscontain more information on the error. For socket I/O on Unix systems, consult 143*1dcdf01fSchristosB<errno> for details. If this error occurs then no further I/O operations should 144*1dcdf01fSchristosbe performed on the connection and SSL_shutdown() must not be called. 145*1dcdf01fSchristos 146*1dcdf01fSchristosThis value can also be returned for other errors, check the error queue for 147*1dcdf01fSchristosdetails. 148*1dcdf01fSchristos 149*1dcdf01fSchristos=item SSL_ERROR_SSL 150*1dcdf01fSchristos 151*1dcdf01fSchristosA non-recoverable, fatal error in the SSL library occurred, usually a protocol 152*1dcdf01fSchristoserror. The OpenSSL error queue contains more information on the error. If this 153*1dcdf01fSchristoserror occurs then no further I/O operations should be performed on the 154*1dcdf01fSchristosconnection and SSL_shutdown() must not be called. 155*1dcdf01fSchristos 156*1dcdf01fSchristos=back 157*1dcdf01fSchristos 158*1dcdf01fSchristos=head1 BUGS 159*1dcdf01fSchristos 160*1dcdf01fSchristosThe B<SSL_ERROR_SYSCALL> with B<errno> value of 0 indicates unexpected EOF from 161*1dcdf01fSchristosthe peer. This will be properly reported as B<SSL_ERROR_SSL> with reason 162*1dcdf01fSchristoscode B<SSL_R_UNEXPECTED_EOF_WHILE_READING> in the OpenSSL 3.0 release because 163*1dcdf01fSchristosit is truly a TLS protocol error to terminate the connection without 164*1dcdf01fSchristosa SSL_shutdown(). 165*1dcdf01fSchristos 166*1dcdf01fSchristosThe issue is kept unfixed in OpenSSL 1.1.1 releases because many applications 167*1dcdf01fSchristoswhich choose to ignore this protocol error depend on the existing way of 168*1dcdf01fSchristosreporting the error. 169*1dcdf01fSchristos 170*1dcdf01fSchristos=head1 SEE ALSO 171*1dcdf01fSchristos 172*1dcdf01fSchristosL<ssl(7)> 173*1dcdf01fSchristos 174*1dcdf01fSchristos=head1 HISTORY 175*1dcdf01fSchristos 176*1dcdf01fSchristosThe SSL_ERROR_WANT_ASYNC error code was added in OpenSSL 1.1.0. 177*1dcdf01fSchristosThe SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1. 178*1dcdf01fSchristos 179*1dcdf01fSchristos=head1 COPYRIGHT 180*1dcdf01fSchristos 181*1dcdf01fSchristosCopyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 182*1dcdf01fSchristos 183*1dcdf01fSchristosLicensed under the OpenSSL license (the "License"). You may not use 184*1dcdf01fSchristosthis file except in compliance with the License. You can obtain a copy 185*1dcdf01fSchristosin the file LICENSE in the source distribution or at 186*1dcdf01fSchristosL<https://www.openssl.org/source/license.html>. 187*1dcdf01fSchristos 188*1dcdf01fSchristos=cut 189