1SSL_SET_ASYNC_CALLBACK(3ossl)       OpenSSL      SSL_SET_ASYNC_CALLBACK(3ossl)
2
3
4

NAME

6       SSL_CTX_set_async_callback, SSL_CTX_set_async_callback_arg,
7       SSL_set_async_callback, SSL_set_async_callback_arg,
8       SSL_get_async_status, SSL_async_callback_fn - manage asynchronous
9       operations
10

SYNOPSIS

12        #include <openssl/ssl.h>
13
14        typedef int (*SSL_async_callback_fn)(SSL *s, void *arg);
15        int SSL_CTX_set_async_callback(SSL_CTX *ctx, SSL_async_callback_fn callback);
16        int SSL_CTX_set_async_callback_arg(SSL_CTX *ctx, void *arg);
17        int SSL_set_async_callback(SSL *s, SSL_async_callback_fn callback);
18        int SSL_set_async_callback_arg(SSL *s, void *arg);
19        int SSL_get_async_status(SSL *s, int *status);
20

DESCRIPTION

22       SSL_CTX_set_async_callback() sets an asynchronous callback function.
23       All SSL objects generated based on this SSL_CTX will get this callback.
24       If an engine supports the callback mechanism, it will be automatically
25       called if SSL_MODE_ASYNC has been set and an asynchronous capable
26       engine completes a cryptography operation to notify the application to
27       resume the paused work flow.
28
29       SSL_CTX_set_async_callback_arg() sets the callback argument.
30
31       SSL_set_async_callback() allows an application to set a callback in an
32       asynchronous SSL object, so that when an engine completes a
33       cryptography operation, the callback will be called to notify the
34       application to resume the paused work flow.
35
36       SSL_set_async_callback_arg() sets an argument for the SSL object when
37       the above callback is called.
38
39       SSL_get_async_status() returns the engine status. This function
40       facilitates the communication from the engine to the application.
41       During an SSL session, cryptographic operations are dispatched to an
42       engine. The engine status is very useful for an application to know if
43       the operation has been successfully dispatched. If the engine does not
44       support this additional callback method, ASYNC_STATUS_UNSUPPORTED will
45       be returned. See ASYNC_WAIT_CTX_set_status() for a description of all
46       of the status values.
47
48       An example of the above functions would be the following:
49
50       1.  Application sets the async callback and callback data on an SSL
51           connection by calling SSL_set_async_callback().
52
53       2.  Application sets SSL_MODE_ASYNC and makes an asynchronous SSL call
54
55       3.  OpenSSL submits the asynchronous request to the engine. If a retry
56           occurs at this point then the status within the ASYNC_WAIT_CTX
57           would be set and the async callback function would be called (goto
58           Step 7).
59
60       4.  The OpenSSL engine pauses the current job and returns, so that the
61           application can continue processing other connections.
62
63       5.  At a future point in time (probably via a polling mechanism or via
64           an interrupt) the engine will become aware that the asynchronous
65           request has finished processing.
66
67       6.  The engine will call the application's callback passing the
68           callback data as a parameter.
69
70       7.  The callback function should then run. Note: it is a requirement
71           that the callback function is small and nonblocking as it will be
72           run in the context of a polling mechanism or an interrupt.
73
74       8.  It is the application's responsibility via the callback function to
75           schedule recalling the OpenSSL asynchronous function and to
76           continue processing.
77
78       9.  The callback function has the option to check the status returned
79           via SSL_get_async_status() to determine whether a retry happened
80           instead of the request being submitted, allowing different
81           processing if required.
82

RETURN VALUES

84       SSL_CTX_set_async_callback(), SSL_set_async_callback(),
85       SSL_CTX_set_async_callback_arg(), SSL_CTX_set_async_callback_arg() and
86       SSL_get_async_status() return 1 on success or 0 on error.
87

SEE ALSO

89       ssl(7)
90

HISTORY

92       SSL_CTX_set_async_callback(), SSL_CTX_set_async_callback_arg(),
93       SSL_set_async_callback(), SSL_set_async_callback_arg() and
94       SSL_get_async_status() were first added to OpenSSL 3.0.
95

97       Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
98
99       Licensed under the Apache License 2.0 (the "License").  You may not use
100       this file except in compliance with the License.  You can obtain a copy
101       in the file LICENSE in the source distribution or at
102       <https://www.openssl.org/source/license.html>.
103
104
105
1063.0.5                             2022-07-05     SSL_SET_ASYNC_CALLBACK(3ossl)
Impressum