1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosSSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup, 6*4724848cSchristosSSL_want_async, SSL_want_async_job, SSL_want_client_hello_cb - obtain state 7*4724848cSchristosinformation TLS/SSL I/O operation 8*4724848cSchristos 9*4724848cSchristos=head1 SYNOPSIS 10*4724848cSchristos 11*4724848cSchristos #include <openssl/ssl.h> 12*4724848cSchristos 13*4724848cSchristos int SSL_want(const SSL *ssl); 14*4724848cSchristos int SSL_want_nothing(const SSL *ssl); 15*4724848cSchristos int SSL_want_read(const SSL *ssl); 16*4724848cSchristos int SSL_want_write(const SSL *ssl); 17*4724848cSchristos int SSL_want_x509_lookup(const SSL *ssl); 18*4724848cSchristos int SSL_want_async(const SSL *ssl); 19*4724848cSchristos int SSL_want_async_job(const SSL *ssl); 20*4724848cSchristos int SSL_want_client_hello_cb(const SSL *ssl); 21*4724848cSchristos 22*4724848cSchristos=head1 DESCRIPTION 23*4724848cSchristos 24*4724848cSchristosSSL_want() returns state information for the SSL object B<ssl>. 25*4724848cSchristos 26*4724848cSchristosThe other SSL_want_*() calls are shortcuts for the possible states returned 27*4724848cSchristosby SSL_want(). 28*4724848cSchristos 29*4724848cSchristos=head1 NOTES 30*4724848cSchristos 31*4724848cSchristosSSL_want() examines the internal state information of the SSL object. Its 32*4724848cSchristosreturn values are similar to that of L<SSL_get_error(3)>. 33*4724848cSchristosUnlike L<SSL_get_error(3)>, which also evaluates the 34*4724848cSchristoserror queue, the results are obtained by examining an internal state flag 35*4724848cSchristosonly. The information must therefore only be used for normal operation under 36*4724848cSchristosnonblocking I/O. Error conditions are not handled and must be treated 37*4724848cSchristosusing L<SSL_get_error(3)>. 38*4724848cSchristos 39*4724848cSchristosThe result returned by SSL_want() should always be consistent with 40*4724848cSchristosthe result of L<SSL_get_error(3)>. 41*4724848cSchristos 42*4724848cSchristos=head1 RETURN VALUES 43*4724848cSchristos 44*4724848cSchristosThe following return values can currently occur for SSL_want(): 45*4724848cSchristos 46*4724848cSchristos=over 4 47*4724848cSchristos 48*4724848cSchristos=item SSL_NOTHING 49*4724848cSchristos 50*4724848cSchristosThere is no data to be written or to be read. 51*4724848cSchristos 52*4724848cSchristos=item SSL_WRITING 53*4724848cSchristos 54*4724848cSchristosThere are data in the SSL buffer that must be written to the underlying 55*4724848cSchristosB<BIO> layer in order to complete the actual SSL_*() operation. 56*4724848cSchristosA call to L<SSL_get_error(3)> should return 57*4724848cSchristosSSL_ERROR_WANT_WRITE. 58*4724848cSchristos 59*4724848cSchristos=item SSL_READING 60*4724848cSchristos 61*4724848cSchristosMore data must be read from the underlying B<BIO> layer in order to 62*4724848cSchristoscomplete the actual SSL_*() operation. 63*4724848cSchristosA call to L<SSL_get_error(3)> should return 64*4724848cSchristosSSL_ERROR_WANT_READ. 65*4724848cSchristos 66*4724848cSchristos=item SSL_X509_LOOKUP 67*4724848cSchristos 68*4724848cSchristosThe operation did not complete because an application callback set by 69*4724848cSchristosSSL_CTX_set_client_cert_cb() has asked to be called again. 70*4724848cSchristosA call to L<SSL_get_error(3)> should return 71*4724848cSchristosSSL_ERROR_WANT_X509_LOOKUP. 72*4724848cSchristos 73*4724848cSchristos=item SSL_ASYNC_PAUSED 74*4724848cSchristos 75*4724848cSchristosAn asynchronous operation partially completed and was then paused. See 76*4724848cSchristosL<SSL_get_all_async_fds(3)>. A call to L<SSL_get_error(3)> should return 77*4724848cSchristosSSL_ERROR_WANT_ASYNC. 78*4724848cSchristos 79*4724848cSchristos=item SSL_ASYNC_NO_JOBS 80*4724848cSchristos 81*4724848cSchristosThe asynchronous job could not be started because there were no async jobs 82*4724848cSchristosavailable in the pool (see ASYNC_init_thread(3)). A call to L<SSL_get_error(3)> 83*4724848cSchristosshould return SSL_ERROR_WANT_ASYNC_JOB. 84*4724848cSchristos 85*4724848cSchristos=item SSL_CLIENT_HELLO_CB 86*4724848cSchristos 87*4724848cSchristosThe operation did not complete because an application callback set by 88*4724848cSchristosSSL_CTX_set_client_hello_cb() has asked to be called again. 89*4724848cSchristosA call to L<SSL_get_error(3)> should return 90*4724848cSchristosSSL_ERROR_WANT_CLIENT_HELLO_CB. 91*4724848cSchristos 92*4724848cSchristos=back 93*4724848cSchristos 94*4724848cSchristosSSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup(), 95*4724848cSchristosSSL_want_async(), SSL_want_async_job(), and SSL_want_client_hello_cb() return 96*4724848cSchristos1, when the corresponding condition is true or 0 otherwise. 97*4724848cSchristos 98*4724848cSchristos=head1 SEE ALSO 99*4724848cSchristos 100*4724848cSchristosL<ssl(7)>, L<SSL_get_error(3)> 101*4724848cSchristos 102*4724848cSchristos=head1 HISTORY 103*4724848cSchristos 104*4724848cSchristosThe SSL_want_client_hello_cb() function and the SSL_CLIENT_HELLO_CB return value 105*4724848cSchristoswere added in OpenSSL 1.1.1. 106*4724848cSchristos 107*4724848cSchristos=head1 COPYRIGHT 108*4724848cSchristos 109*4724848cSchristosCopyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved. 110*4724848cSchristos 111*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 112*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 113*4724848cSchristosin the file LICENSE in the source distribution or at 114*4724848cSchristosL<https://www.openssl.org/source/license.html>. 115*4724848cSchristos 116*4724848cSchristos=cut 117