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