1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncherySSL_CTX_set_async_callback, 6b077aed3SPierre ProncherySSL_CTX_set_async_callback_arg, 7b077aed3SPierre ProncherySSL_set_async_callback, 8b077aed3SPierre ProncherySSL_set_async_callback_arg, 9b077aed3SPierre ProncherySSL_get_async_status, 10b077aed3SPierre ProncherySSL_async_callback_fn 11b077aed3SPierre Pronchery- manage asynchronous operations 12b077aed3SPierre Pronchery 13b077aed3SPierre Pronchery=head1 SYNOPSIS 14b077aed3SPierre Pronchery 15b077aed3SPierre Pronchery=for openssl multiple includes 16b077aed3SPierre Pronchery 17b077aed3SPierre Pronchery #include <openssl/ssl.h> 18b077aed3SPierre Pronchery 19b077aed3SPierre Pronchery typedef int (*SSL_async_callback_fn)(SSL *s, void *arg); 20b077aed3SPierre Pronchery int SSL_CTX_set_async_callback(SSL_CTX *ctx, SSL_async_callback_fn callback); 21b077aed3SPierre Pronchery int SSL_CTX_set_async_callback_arg(SSL_CTX *ctx, void *arg); 22b077aed3SPierre Pronchery int SSL_set_async_callback(SSL *s, SSL_async_callback_fn callback); 23b077aed3SPierre Pronchery int SSL_set_async_callback_arg(SSL *s, void *arg); 24b077aed3SPierre Pronchery int SSL_get_async_status(SSL *s, int *status); 25b077aed3SPierre Pronchery 26b077aed3SPierre Pronchery=head1 DESCRIPTION 27b077aed3SPierre Pronchery 28b077aed3SPierre ProncherySSL_CTX_set_async_callback() sets an asynchronous callback function. All B<SSL> 29b077aed3SPierre Proncheryobjects generated based on this B<SSL_CTX> will get this callback. If an engine 30b077aed3SPierre Proncherysupports the callback mechanism, it will be automatically called if 31b077aed3SPierre ProncheryB<SSL_MODE_ASYNC> has been set and an asynchronous capable engine completes a 32b077aed3SPierre Proncherycryptography operation to notify the application to resume the paused work flow. 33b077aed3SPierre Pronchery 34b077aed3SPierre ProncherySSL_CTX_set_async_callback_arg() sets the callback argument. 35b077aed3SPierre Pronchery 36b077aed3SPierre ProncherySSL_set_async_callback() allows an application to set a callback in an 37b077aed3SPierre Proncheryasynchronous B<SSL> object, so that when an engine completes a cryptography 38b077aed3SPierre Proncheryoperation, the callback will be called to notify the application to resume the 39b077aed3SPierre Proncherypaused work flow. 40b077aed3SPierre Pronchery 41b077aed3SPierre ProncherySSL_set_async_callback_arg() sets an argument for the B<SSL> object when the 42b077aed3SPierre Proncheryabove callback is called. 43b077aed3SPierre Pronchery 44b077aed3SPierre ProncherySSL_get_async_status() returns the engine status. This function facilitates the 45b077aed3SPierre Proncherycommunication from the engine to the application. During an SSL session, 46b077aed3SPierre Proncherycryptographic operations are dispatched to an engine. The engine status is very 47b077aed3SPierre Proncheryuseful for an application to know if the operation has been successfully 48b077aed3SPierre Proncherydispatched. If the engine does not support this additional callback method, 49b077aed3SPierre ProncheryB<ASYNC_STATUS_UNSUPPORTED> will be returned. See ASYNC_WAIT_CTX_set_status() 50b077aed3SPierre Proncheryfor a description of all of the status values. 51b077aed3SPierre Pronchery 52b077aed3SPierre ProncheryAn example of the above functions would be the following: 53b077aed3SPierre Pronchery 54b077aed3SPierre Pronchery=over 4 55b077aed3SPierre Pronchery 56b077aed3SPierre Pronchery=item 1. 57b077aed3SPierre Pronchery 58b077aed3SPierre ProncheryApplication sets the async callback and callback data on an SSL connection 59b077aed3SPierre Proncheryby calling SSL_set_async_callback(). 60b077aed3SPierre Pronchery 61b077aed3SPierre Pronchery=item 2. 62b077aed3SPierre Pronchery 63b077aed3SPierre ProncheryApplication sets B<SSL_MODE_ASYNC> and makes an asynchronous SSL call 64b077aed3SPierre Pronchery 65b077aed3SPierre Pronchery=item 3. 66b077aed3SPierre Pronchery 67b077aed3SPierre ProncheryOpenSSL submits the asynchronous request to the engine. If a retry occurs at 68b077aed3SPierre Proncherythis point then the status within the B<ASYNC_WAIT_CTX> would be set and the 69b077aed3SPierre Proncheryasync callback function would be called (goto Step 7). 70b077aed3SPierre Pronchery 71b077aed3SPierre Pronchery=item 4. 72b077aed3SPierre Pronchery 73b077aed3SPierre ProncheryThe OpenSSL engine pauses the current job and returns, so that the 74b077aed3SPierre Proncheryapplication can continue processing other connections. 75b077aed3SPierre Pronchery 76b077aed3SPierre Pronchery=item 5. 77b077aed3SPierre Pronchery 78b077aed3SPierre ProncheryAt a future point in time (probably via a polling mechanism or via an 79b077aed3SPierre Proncheryinterrupt) the engine will become aware that the asynchronous request has 80b077aed3SPierre Proncheryfinished processing. 81b077aed3SPierre Pronchery 82b077aed3SPierre Pronchery=item 6. 83b077aed3SPierre Pronchery 84b077aed3SPierre ProncheryThe engine will call the application's callback passing the callback data as 85b077aed3SPierre Proncherya parameter. 86b077aed3SPierre Pronchery 87b077aed3SPierre Pronchery=item 7. 88b077aed3SPierre Pronchery 89b077aed3SPierre ProncheryThe callback function should then run. Note: it is a requirement that the 90b077aed3SPierre Proncherycallback function is small and nonblocking as it will be run in the context of 91b077aed3SPierre Proncherya polling mechanism or an interrupt. 92b077aed3SPierre Pronchery 93b077aed3SPierre Pronchery=item 8. 94b077aed3SPierre Pronchery 95b077aed3SPierre ProncheryIt is the application's responsibility via the callback function to schedule 96b077aed3SPierre Proncheryrecalling the OpenSSL asynchronous function and to continue processing. 97b077aed3SPierre Pronchery 98b077aed3SPierre Pronchery=item 9. 99b077aed3SPierre Pronchery 100b077aed3SPierre ProncheryThe callback function has the option to check the status returned via 101b077aed3SPierre ProncherySSL_get_async_status() to determine whether a retry happened instead of the 102b077aed3SPierre Proncheryrequest being submitted, allowing different processing if required. 103b077aed3SPierre Pronchery 104b077aed3SPierre Pronchery=back 105b077aed3SPierre Pronchery 106b077aed3SPierre Pronchery=head1 RETURN VALUES 107b077aed3SPierre Pronchery 108b077aed3SPierre ProncherySSL_CTX_set_async_callback(), SSL_set_async_callback(), 109b077aed3SPierre ProncherySSL_CTX_set_async_callback_arg(), SSL_CTX_set_async_callback_arg() and 110b077aed3SPierre ProncherySSL_get_async_status() return 1 on success or 0 on error. 111b077aed3SPierre Pronchery 112b077aed3SPierre Pronchery=head1 SEE ALSO 113b077aed3SPierre Pronchery 114b077aed3SPierre ProncheryL<ssl(7)> 115b077aed3SPierre Pronchery 116b077aed3SPierre Pronchery=head1 HISTORY 117b077aed3SPierre Pronchery 118b077aed3SPierre ProncherySSL_CTX_set_async_callback(), SSL_CTX_set_async_callback_arg(), 119b077aed3SPierre ProncherySSL_set_async_callback(), SSL_set_async_callback_arg() and 120b077aed3SPierre ProncherySSL_get_async_status() were first added to OpenSSL 3.0. 121b077aed3SPierre Pronchery 122b077aed3SPierre Pronchery=head1 COPYRIGHT 123b077aed3SPierre Pronchery 124*e7be843bSPierre ProncheryCopyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. 125b077aed3SPierre Pronchery 126b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 127b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 128b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 129b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 130b077aed3SPierre Pronchery 131b077aed3SPierre Pronchery=cut 132