1ASYNC_WAIT_CTX_NEW(3ossl) OpenSSL ASYNC_WAIT_CTX_NEW(3ossl)
2
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
16 #include <openssl/async.h>
17 #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
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 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 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 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 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 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 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 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 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 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 ASYNC_WAIT_CTX_get_callback() returns the callback set in the
144 ASYNC_WAIT_CTX structure.
145 ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine
147 status. The possible status values are the following:
148 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 ASYNC_STATUS_ERR
156 The engine has a fatal problem with this request. The user code
157 should clean up this session.
158 ASYNC_STATUS_OK
160 The request has been successfully submitted.
161 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 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 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
182 ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated
183 ASYNC_WAIT_CTX or NULL on error.
184 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
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
201 crypto(7), ASYNC_start_job(3)
202
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 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 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>.
2203.1.1 2023-08-31 ASYNC_WAIT_CTX_NEW(3ossl)