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

NAME

6       ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
7       ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
8       ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
9       ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback,
10       ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status,
11       ASYNC_callback_fn, ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR,
12       ASYNC_STATUS_OK, ASYNC_STATUS_EAGAIN - functions to manage waiting for
13       asynchronous jobs to complete
14

SYNOPSIS

16        #include <openssl/async.h>
17
18        #define ASYNC_STATUS_UNSUPPORTED    0
19        #define ASYNC_STATUS_ERR            1
20        #define ASYNC_STATUS_OK             2
21        #define ASYNC_STATUS_EAGAIN         3
22        typedef int (*ASYNC_callback_fn)(void *arg);
23        ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
24        void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
25        int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
26                                       OSSL_ASYNC_FD fd,
27                                       void *custom_data,
28                                       void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
29                                                       OSSL_ASYNC_FD, void *));
30        int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
31                                  OSSL_ASYNC_FD *fd, void **custom_data);
32        int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
33                                       size_t *numfds);
34        int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
35                                           size_t *numaddfds, OSSL_ASYNC_FD *delfd,
36                                           size_t *numdelfds);
37        int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
38        int ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx,
39                                        ASYNC_callback_fn callback,
40                                        void *callback_arg);
41        int ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx,
42                                        ASYNC_callback_fn *callback,
43                                        void **callback_arg);
44        int ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status);
45        int ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx);
46

DESCRIPTION

48       For an overview of how asynchronous operations are implemented in
49       OpenSSL see ASYNC_start_job(3). An ASYNC_WAIT_CTX object represents an
50       asynchronous "session", i.e. a related set of crypto operations. For
51       example in SSL terms this would have a one-to-one correspondence with
52       an SSL connection.
53
54       Application code must create an ASYNC_WAIT_CTX using the
55       ASYNC_WAIT_CTX_new() function prior to calling ASYNC_start_job() (see
56       ASYNC_start_job(3)). When the job is started it is associated with the
57       ASYNC_WAIT_CTX for the duration of that job. An ASYNC_WAIT_CTX should
58       only be used for one ASYNC_JOB at any one time, but can be reused after
59       an ASYNC_JOB has finished for a subsequent ASYNC_JOB. When the session
60       is complete (e.g. the SSL connection is closed), application code
61       cleans up with ASYNC_WAIT_CTX_free().
62
63       ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them.
64       Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an
65       ASYNC_WAIT_CTX in the ctx parameter will return the wait file
66       descriptors associated with that job in *fd. The number of file
67       descriptors returned will be stored in *numfds. It is the caller's
68       responsibility to ensure that sufficient memory has been allocated in
69       *fd to receive all the file descriptors. Calling
70       ASYNC_WAIT_CTX_get_all_fds() with a NULL fd value will return no file
71       descriptors but will still populate *numfds. Therefore, application
72       code is typically expected to call this function twice: once to get the
73       number of fds, and then again when sufficient memory has been
74       allocated. If only one asynchronous engine is being used then normally
75       this call will only ever return one fd. If multiple asynchronous
76       engines are being used then more could be returned.
77
78       The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if
79       any fds have changed since the last call time ASYNC_start_job()
80       returned ASYNC_PAUSE (or since the ASYNC_WAIT_CTX was created if no
81       ASYNC_PAUSE result has been received). The numaddfds and numdelfds
82       parameters will be populated with the number of fds added or deleted
83       respectively. *addfd and *delfd will be populated with the list of
84       added and deleted fds respectively. Similarly to
85       ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they
86       are not NULL then the caller is responsible for ensuring sufficient
87       memory is allocated.
88
89       Implementors of async aware code (e.g. engines) are encouraged to
90       return a stable fd for the lifetime of the ASYNC_WAIT_CTX in order to
91       reduce the "churn" of regularly changing fds - although no guarantees
92       of this are provided to applications.
93
94       Applications can wait for the file descriptor to be ready for "read"
95       using a system function call such as select or poll (being ready for
96       "read" indicates that the job should be resumed). If no file descriptor
97       is made available then an application will have to periodically "poll"
98       the job by attempting to restart it to see if it is ready to continue.
99
100       Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from
101       the job via ASYNC_get_wait_ctx(3) and provide a file descriptor to use
102       for waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this
103       would be done by an engine immediately prior to calling
104       ASYNC_pause_job() and not by end user code. An existing association
105       with a file descriptor can be obtained using ASYNC_WAIT_CTX_get_fd()
106       and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of these functions
107       requires a key value which is unique to the async aware code.  This
108       could be any unique value but a good candidate might be the ENGINE *
109       for the engine. The custom_data parameter can be any value, and will be
110       returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
111       ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a
112       "cleanup" routine. This can be NULL but if provided will automatically
113       get called when the ASYNC_WAIT_CTX is freed, and gives the engine the
114       opportunity to close the fd or any other resources. Note: The "cleanup"
115       routine does not get called if the fd is cleared directly via a call to
116       ASYNC_WAIT_CTX_clear_fd().
117
118       An example of typical usage might be an async capable engine. User code
119       would initiate cryptographic operations. The engine would initiate
120       those operations asynchronously and then call
121       ASYNC_WAIT_CTX_set_wait_fd() followed by ASYNC_pause_job() to return
122       control to the user code. The user code can then perform other tasks or
123       wait for the job to be ready by calling "select" or other similar
124       function on the wait file descriptor. The engine can signal to the user
125       code that the job should be resumed by making the wait file descriptor
126       "readable". Once resumed the engine should clear the wake signal on the
127       wait file descriptor.
128
129       As well as a file descriptor, user code may also be notified via a
130       callback. The callback and data pointers are stored within the
131       ASYNC_WAIT_CTX along with an additional status field that can be used
132       for the notification of retries from an engine. This additional method
133       can be used when the user thinks that a file descriptor is too costly
134       in terms of CPU cycles or in some context where a file descriptor is
135       not appropriate.
136
137       ASYNC_WAIT_CTX_set_callback() sets the callback and the callback
138       argument. The callback will be called to notify user code when an
139       engine completes a cryptography operation. It is a requirement that the
140       callback function is small and nonblocking as it will be run in the
141       context of a polling mechanism or an interrupt.
142
143       ASYNC_WAIT_CTX_get_callback() returns the callback set in the
144       ASYNC_WAIT_CTX structure.
145
146       ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine
147       status.  The possible status values are the following:
148
149       ASYNC_STATUS_UNSUPPORTED
150           The engine does not support the callback mechanism. This is the
151           default value.  The engine must call ASYNC_WAIT_CTX_set_status() to
152           set the status to some value other than ASYNC_STATUS_UNSUPPORTED if
153           it intends to enable the callback mechanism.
154
155       ASYNC_STATUS_ERR
156           The engine has a fatal problem with this request. The user code
157           should clean up this session.
158
159       ASYNC_STATUS_OK
160           The request has been successfully submitted.
161
162       ASYNC_STATUS_EAGAIN
163           The engine has some problem which will be recovered soon, such as a
164           buffer is full, so user code should resume the job.
165
166       ASYNC_WAIT_CTX_get_status() allows user code to obtain the current
167       status value.  If the status is any value other than ASYNC_STATUS_OK
168       then the user code should not expect to receive a callback from the
169       engine even if one has been set.
170
171       An example of the usage of the callback method might be the following.
172       User code would initiate cryptographic operations, and the engine code
173       would dispatch this operation to hardware, and if the dispatch is
174       successful, then the engine code would call ASYNC_pause_job() to return
175       control to the user code. After that, user code can perform other
176       tasks. When the hardware completes the operation, normally it is
177       detected by a polling function or an interrupt, as the user code set a
178       callback by calling ASYNC_WAIT_CTX_set_callback() previously, then the
179       registered callback will be called.
180

RETURN VALUES

182       ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated
183       ASYNC_WAIT_CTX or NULL on error.
184
185       ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd,
186       ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds,
187       ASYNC_WAIT_CTX_clear_fd, ASYNC_WAIT_CTX_set_callback,
188       ASYNC_WAIT_CTX_get_callback and ASYNC_WAIT_CTX_set_status all return 1
189       on success or 0 on error.  ASYNC_WAIT_CTX_get_status() returns the
190       engine status.
191

NOTES

193       On Windows platforms the <openssl/async.h> header is dependent on some
194       of the types customarily made available by including <windows.h>. The
195       application developer is likely to require control over when the latter
196       is included, commonly as one of the first included headers. Therefore,
197       it is defined as an application developer's responsibility to include
198       <windows.h> prior to <openssl/async.h>.
199

SEE ALSO

201       crypto(7), ASYNC_start_job(3)
202

HISTORY

204       ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(),
205       ASYNC_WAIT_CTX_set_wait_fd(), ASYNC_WAIT_CTX_get_fd(),
206       ASYNC_WAIT_CTX_get_all_fds(), ASYNC_WAIT_CTX_get_changed_fds() and
207       ASYNC_WAIT_CTX_clear_fd() were added in OpenSSL 1.1.0.
208
209       ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(),
210       ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status() were added
211       in OpenSSL 3.0.
212
214       Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
215
216       Licensed under the Apache License 2.0 (the "License").  You may not use
217       this file except in compliance with the License.  You can obtain a copy
218       in the file LICENSE in the source distribution or at
219       <https://www.openssl.org/source/license.html>.
220
221
222
2233.1.1                             2023-08-31         ASYNC_WAIT_CTX_NEW(3ossl)
Impressum