]>
Commit | Line | Data |
---|---|---|
ff75a257 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, | |
6 | ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, | |
9f5a87fd PY |
7 | ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, |
8 | ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback, | |
9 | ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn, | |
10 | ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK, | |
11 | ASYNC_STATUS_EAGAIN | |
12 | - functions to manage waiting for asynchronous jobs to complete | |
ff75a257 MC |
13 | |
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/async.h> | |
17 | ||
9f5a87fd PY |
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); | |
ff75a257 MC |
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 *, | |
e9b77246 | 29 | OSSL_ASYNC_FD, void *)); |
ff75a257 MC |
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); | |
9f5a87fd PY |
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); | |
ff75a257 MC |
46 | |
47 | ||
48 | =head1 DESCRIPTION | |
49 | ||
50 | For an overview of how asynchronous operations are implemented in OpenSSL see | |
dfe1752c | 51 | L<ASYNC_start_job(3)>. An B<ASYNC_WAIT_CTX> object represents an asynchronous |
ff75a257 MC |
52 | "session", i.e. a related set of crypto operations. For example in SSL terms |
53 | this would have a one-to-one correspondence with an SSL connection. | |
54 | ||
dfe1752c | 55 | Application code must create an B<ASYNC_WAIT_CTX> using the ASYNC_WAIT_CTX_new() |
ff75a257 | 56 | function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When |
dfe1752c RL |
57 | the job is started it is associated with the B<ASYNC_WAIT_CTX> for the duration |
58 | of that job. An B<ASYNC_WAIT_CTX> should only be used for one B<ASYNC_JOB> at | |
59 | any one time, but can be reused after an B<ASYNC_JOB> has finished for a | |
60 | subsequent B<ASYNC_JOB>. When the session is complete (e.g. the SSL connection | |
61 | is closed), application code cleans up with ASYNC_WAIT_CTX_free(). | |
62 | ||
63 | B<ASYNC_WAIT_CTX>s can have "wait" file descriptors associated with them. | |
64 | Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an | |
65 | B<ASYNC_WAIT_CTX> in the I<ctx> parameter will return the wait file descriptors | |
66 | associated with that job in I<*fd>. The number of file descriptors returned will | |
67 | be stored in I<*numfds>. It is the caller's responsibility to ensure that | |
68 | sufficient memory has been allocated in I<*fd> to receive all the file | |
69 | descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL I<fd> value will | |
8c1cbc72 | 70 | return no file descriptors but will still populate I<*numfds>. Therefore, |
dfe1752c RL |
71 | application code is typically expected to call this function twice: once to get |
72 | the number of fds, and then again when sufficient memory has been allocated. If | |
73 | only one asynchronous engine is being used then normally this call will only | |
74 | ever return one fd. If multiple asynchronous engines are being used then more | |
75 | could be returned. | |
ff75a257 | 76 | |
7baabf45 | 77 | The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds |
dfe1752c RL |
78 | have changed since the last call time ASYNC_start_job() returned B<ASYNC_PAUSE> |
79 | (or since the B<ASYNC_WAIT_CTX> was created if no B<ASYNC_PAUSE> result has | |
80 | been received). The I<numaddfds> and I<numdelfds> parameters will be populated | |
81 | with the number of fds added or deleted respectively. I<*addfd> and I<*delfd> | |
ff75a257 MC |
82 | will be populated with the list of added and deleted fds respectively. Similarly |
83 | to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not | |
84 | NULL then the caller is responsible for ensuring sufficient memory is allocated. | |
85 | ||
86 | Implementors of async aware code (e.g. engines) are encouraged to return a | |
dfe1752c RL |
87 | stable fd for the lifetime of the B<ASYNC_WAIT_CTX> in order to reduce the |
88 | "churn" of regularly changing fds - although no guarantees of this are provided | |
89 | to applications. | |
ff75a257 MC |
90 | |
91 | Applications can wait for the file descriptor to be ready for "read" using a | |
92 | system function call such as select or poll (being ready for "read" indicates | |
93 | that the job should be resumed). If no file descriptor is made available then an | |
94 | application will have to periodically "poll" the job by attempting to restart it | |
95 | to see if it is ready to continue. | |
96 | ||
dfe1752c RL |
97 | Async aware code (e.g. engines) can get the current B<ASYNC_WAIT_CTX> from the |
98 | job via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for | |
99 | waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done | |
100 | by an engine immediately prior to calling ASYNC_pause_job() and not by end user | |
101 | code. An existing association with a file descriptor can be obtained using | |
ff75a257 | 102 | ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of |
dfe1752c | 103 | these functions requires a I<key> value which is unique to the async aware |
50c3fc00 | 104 | code. This could be any unique value but a good candidate might be the |
dfe1752c | 105 | B<ENGINE *> for the engine. The I<custom_data> parameter can be any value, and |
50c3fc00 | 106 | will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The |
ff75a257 | 107 | ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup" |
50c3fc00 | 108 | routine. This can be NULL but if provided will automatically get called when |
dfe1752c RL |
109 | the B<ASYNC_WAIT_CTX> is freed, and gives the engine the opportunity to close |
110 | the fd or any other resources. Note: The "cleanup" routine does not get called | |
111 | if the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd(). | |
ff75a257 MC |
112 | |
113 | An example of typical usage might be an async capable engine. User code would | |
114 | initiate cryptographic operations. The engine would initiate those operations | |
115 | asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by | |
116 | ASYNC_pause_job() to return control to the user code. The user code can then | |
117 | perform other tasks or wait for the job to be ready by calling "select" or other | |
118 | similar function on the wait file descriptor. The engine can signal to the user | |
119 | code that the job should be resumed by making the wait file descriptor | |
120 | "readable". Once resumed the engine should clear the wake signal on the wait | |
121 | file descriptor. | |
122 | ||
9f5a87fd | 123 | As well as a file descriptor, user code may also be notified via a callback. The |
dfe1752c | 124 | callback and data pointers are stored within the B<ASYNC_WAIT_CTX> along with an |
9f5a87fd PY |
125 | additional status field that can be used for the notification of retries from an |
126 | engine. This additional method can be used when the user thinks that a file | |
127 | descriptor is too costly in terms of CPU cycles or in some context where a file | |
128 | descriptor is not appropriate. | |
129 | ||
130 | ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The | |
131 | callback will be called to notify user code when an engine completes a | |
132 | cryptography operation. It is a requirement that the callback function is small | |
133 | and non-blocking as it will be run in the context of a polling mechanism or an | |
134 | interrupt. | |
135 | ||
dfe1752c | 136 | ASYNC_WAIT_CTX_get_callback() returns the callback set in the B<ASYNC_WAIT_CTX> |
9f5a87fd PY |
137 | structure. |
138 | ||
139 | ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status. | |
140 | The possible status values are the following: | |
dfe1752c RL |
141 | |
142 | =over 4 | |
143 | ||
144 | =item B<ASYNC_STATUS_UNSUPPORTED> | |
145 | ||
146 | The engine does not support the callback mechanism. This is the default value. | |
147 | The engine must call ASYNC_WAIT_CTX_set_status() to set the status to some value | |
148 | other than B<ASYNC_STATUS_UNSUPPORTED> if it intends to enable the callback | |
149 | mechanism. | |
150 | ||
151 | =item B<ASYNC_STATUS_ERR> | |
152 | ||
153 | The engine has a fatal problem with this request. The user code should clean up | |
154 | this session. | |
155 | ||
156 | =item B<ASYNC_STATUS_OK> | |
157 | ||
158 | The request has been successfully submitted. | |
159 | ||
160 | =item B<ASYNC_STATUS_EAGAIN> | |
161 | ||
162 | The engine has some problem which will be recovered soon, such as a buffer is | |
163 | full, so user code should resume the job. | |
164 | ||
165 | =back | |
9f5a87fd PY |
166 | |
167 | ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value. | |
dfe1752c RL |
168 | If the status is any value other than B<ASYNC_STATUS_OK> then the user code |
169 | should not expect to receive a callback from the engine even if one has been | |
170 | set. | |
9f5a87fd PY |
171 | |
172 | An example of the usage of the callback method might be the following. User | |
173 | code would initiate cryptographic operations, and the engine code would dispatch | |
174 | this operation to hardware, and if the dispatch is successful, then the engine | |
175 | code would call ASYNC_pause_job() to return control to the user code. After | |
176 | that, user code can perform other tasks. When the hardware completes the | |
177 | operation, normally it is detected by a polling function or an interrupt, as the | |
178 | user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously, | |
179 | then the registered callback will be called. | |
180 | ||
ff75a257 MC |
181 | =head1 RETURN VALUES |
182 | ||
dfe1752c RL |
183 | ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated B<ASYNC_WAIT_CTX> |
184 | or NULL on error. | |
ff75a257 MC |
185 | |
186 | ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, | |
9f5a87fd PY |
187 | ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, |
188 | ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and | |
189 | ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error. | |
79c44b4e | 190 | ASYNC_WAIT_CTX_get_status() returns the engine status. |
9f5a87fd | 191 | |
ff75a257 | 192 | |
f1f5ee17 AP |
193 | =head1 NOTES |
194 | ||
195 | On Windows platforms the openssl/async.h header is dependent on some | |
196 | of the types customarily made available by including windows.h. The | |
197 | application developer is likely to require control over when the latter | |
8c1cbc72 | 198 | is included, commonly as one of the first included headers. Therefore, |
f1f5ee17 AP |
199 | it is defined as an application developer's responsibility to include |
200 | windows.h prior to async.h. | |
201 | ||
ff75a257 MC |
202 | =head1 SEE ALSO |
203 | ||
b97fdb57 | 204 | L<crypto(7)>, L<ASYNC_start_job(3)> |
ff75a257 MC |
205 | |
206 | =head1 HISTORY | |
207 | ||
fc5ecadd DMSP |
208 | ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(), ASYNC_WAIT_CTX_set_wait_fd(), |
209 | ASYNC_WAIT_CTX_get_fd(), ASYNC_WAIT_CTX_get_all_fds(), | |
210 | ASYNC_WAIT_CTX_get_changed_fds() and ASYNC_WAIT_CTX_clear_fd() | |
211 | were added in OpenSSL 1.1.0. | |
ff75a257 | 212 | |
9f5a87fd PY |
213 | ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(), |
214 | ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status() | |
4674aaf4 | 215 | were added in OpenSSL 3.0. |
9f5a87fd | 216 | |
e2f92610 RS |
217 | =head1 COPYRIGHT |
218 | ||
e39e295e | 219 | Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 220 | |
4746f25a | 221 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
222 | this file except in compliance with the License. You can obtain a copy |
223 | in the file LICENSE in the source distribution or at | |
224 | L<https://www.openssl.org/source/license.html>. | |
225 | ||
226 | =cut |