1=pod 2 3=head1 NAME 4 5SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, 6SSL_want_x509_lookup, SSL_want_retry_verify, SSL_want_async, SSL_want_async_job, 7SSL_want_client_hello_cb - obtain state information TLS/SSL I/O operation 8 9=head1 SYNOPSIS 10 11 #include <openssl/ssl.h> 12 13 int SSL_want(const SSL *ssl); 14 int SSL_want_nothing(const SSL *ssl); 15 int SSL_want_read(const SSL *ssl); 16 int SSL_want_write(const SSL *ssl); 17 int SSL_want_x509_lookup(const SSL *ssl); 18 int SSL_want_retry_verify(const SSL *ssl); 19 int SSL_want_async(const SSL *ssl); 20 int SSL_want_async_job(const SSL *ssl); 21 int SSL_want_client_hello_cb(const SSL *ssl); 22 23=head1 DESCRIPTION 24 25SSL_want() returns state information for the SSL object B<ssl>. B<ssl> B<MUST NOT> be NULL. 26 27The other SSL_want_*() calls are shortcuts for the possible states returned 28by SSL_want(). 29 30=head1 NOTES 31 32SSL_want() examines the internal state information of the SSL object. Its 33return values are similar to that of L<SSL_get_error(3)>. 34Unlike L<SSL_get_error(3)>, which also evaluates the 35error queue, the results are obtained by examining an internal state flag 36only. The information must therefore only be used for normal operation under 37nonblocking I/O. Error conditions are not handled and must be treated 38using L<SSL_get_error(3)>. 39 40The result returned by SSL_want() should always be consistent with 41the result of L<SSL_get_error(3)>. 42 43=head1 RETURN VALUES 44 45The following return values can currently occur for SSL_want(): 46 47=over 4 48 49=item SSL_NOTHING 50 51There is no data to be written or to be read. 52 53=item SSL_WRITING 54 55There are data in the SSL buffer that must be written to the underlying 56B<BIO> layer in order to complete the actual SSL_*() operation. 57A call to L<SSL_get_error(3)> should return B<SSL_ERROR_WANT_WRITE>. 58 59=item SSL_READING 60 61More data must be read from the underlying B<BIO> layer in order to 62complete the actual SSL_*() operation. 63A call to L<SSL_get_error(3)> should return B<SSL_ERROR_WANT_READ>. 64 65=item SSL_X509_LOOKUP 66 67The operation did not complete because an application callback set by 68SSL_CTX_set_client_cert_cb() has asked to be called again. 69A call to L<SSL_get_error(3)> should return B<SSL_ERROR_WANT_X509_LOOKUP>. 70 71=item SSL_RETRY_VERIFY 72 73The operation did not complete because a certificate verification callback 74has asked to be called again via L<SSL_set_retry_verify(3)>. 75A call to L<SSL_get_error(3)> should return B<SSL_ERROR_WANT_RETRY_VERIFY>. 76 77=item SSL_ASYNC_PAUSED 78 79An asynchronous operation partially completed and was then paused. See 80L<SSL_get_all_async_fds(3)>. A call to L<SSL_get_error(3)> should return 81B<SSL_ERROR_WANT_ASYNC>. 82 83=item SSL_ASYNC_NO_JOBS 84 85The asynchronous job could not be started because there were no async jobs 86available in the pool (see ASYNC_init_thread(3)). A call to L<SSL_get_error(3)> 87should return B<SSL_ERROR_WANT_ASYNC_JOB>. 88 89=item SSL_CLIENT_HELLO_CB 90 91The operation did not complete because an application callback set by 92SSL_CTX_set_client_hello_cb() has asked to be called again. 93A call to L<SSL_get_error(3)> should return B<SSL_ERROR_WANT_CLIENT_HELLO_CB>. 94 95=back 96 97SSL_want_nothing(), SSL_want_read(), SSL_want_write(), 98SSL_want_x509_lookup(), SSL_want_retry_verify(), 99SSL_want_async(), SSL_want_async_job(), and SSL_want_client_hello_cb() 100return 1 when the corresponding condition is true or 0 otherwise. 101 102=head1 QUIC-SPECIFIC CONSIDERATIONS 103 104For QUIC, these functions relate only to the TLS handshake layer. 105 106=head1 SEE ALSO 107 108L<ssl(7)>, L<SSL_get_error(3)> 109 110=head1 HISTORY 111 112The SSL_want_client_hello_cb() function and the SSL_CLIENT_HELLO_CB return value 113were added in OpenSSL 1.1.1. 114 115=head1 COPYRIGHT 116 117Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved. 118 119Licensed under the Apache License 2.0 (the "License"). You may not use 120this file except in compliance with the License. You can obtain a copy 121in the file LICENSE in the source distribution or at 122L<https://www.openssl.org/source/license.html>. 123 124=cut 125
