]>
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 | |
51 | L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous | |
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 | ||
55 | Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new() | |
56 | function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When | |
57 | the job is started it is associated with the ASYNC_WAIT_CTX for the duration of | |
58 | that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one | |
59 | time, but can be reused after an ASYNC_JOB has finished for a subsequent | |
60 | ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed), | |
61 | application code cleans up with ASYNC_WAIT_CTX_free(). | |
62 | ||
63 | ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling | |
64 | ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in | |
65 | the B<ctx> parameter will return the wait file descriptors associated with that | |
66 | job in B<*fd>. The number of file descriptors returned will be stored in | |
67 | B<*numfds>. It is the caller's responsibility to ensure that sufficient memory | |
68 | has been allocated in B<*fd> to receive all the file descriptors. Calling | |
69 | ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file | |
70 | descriptors but will still populate B<*numfds>. Therefore application code is | |
71 | typically expected to call this function twice: once to get the number of fds, | |
72 | and then again when sufficient memory has been allocated. If only one | |
24c2cd39 | 73 | asynchronous engine is being used then normally this call will only ever return |
ff75a257 MC |
74 | one fd. If multiple asynchronous engines are being used then more could be |
75 | returned. | |
76 | ||
7baabf45 | 77 | The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds |
ff75a257 MC |
78 | have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE |
79 | result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has | |
80 | been received). The B<numaddfds> and B<numdelfds> parameters will be populated | |
81 | with the number of fds added or deleted respectively. B<*addfd> and B<*delfd> | |
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 | |
87 | stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn" | |
88 | of regularly changing fds - although no guarantees of this are provided to | |
89 | applications. | |
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 | ||
97 | Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job | |
50c3fc00 AG |
98 | via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting |
99 | on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an | |
100 | engine immediately prior to calling ASYNC_pause_job() and not by end user code. | |
101 | 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 |
50c3fc00 AG |
103 | these functions requires a B<key> value which is unique to the async aware |
104 | code. This could be any unique value but a good candidate might be the | |
105 | B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and | |
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 AG |
108 | routine. This can be NULL but if provided will automatically get called when |
109 | the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the | |
110 | fd or any other resources. Note: The "cleanup" routine does not get called if | |
111 | 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 PY |
123 | As well as a file descriptor, user code may also be notified via a callback. The |
124 | callback and data pointers are stored within the ASYNC_WAIT_CTX along with an | |
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 | ||
136 | ASYNC_WAIT_CTX_get_callback() returns the callback set in the ASYNC_WAIT_CTX | |
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: | |
141 | ASYNC_STATUS_UNSUPPORTED: The engine does not support the callback mechanism. | |
142 | This is the default value. The engine must call ASYNC_WAIT_CTX_set_status() to | |
143 | set the status to some value other than ASYNC_STATUS_UNSUPPORTED if it intends | |
144 | to enable the callback mechanism. | |
145 | ASYNC_STATUS_ERR: The engine has a fatal problem with this request. The user | |
146 | code should clean up this session. | |
147 | ASYNC_STATUS_OK: The request has been successfully submitted. | |
148 | ASYNC_STATUS_EAGAIN: The engine has some problem which will be recovered soon, | |
149 | such as a buffer is full, so user code should resume the job. | |
150 | ||
151 | ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value. | |
152 | If the status is any value other than ASYNC_STATUS_OK then the user code should | |
153 | not expect to receive a callback from the engine even if one has been set. | |
154 | ||
155 | An example of the usage of the callback method might be the following. User | |
156 | code would initiate cryptographic operations, and the engine code would dispatch | |
157 | this operation to hardware, and if the dispatch is successful, then the engine | |
158 | code would call ASYNC_pause_job() to return control to the user code. After | |
159 | that, user code can perform other tasks. When the hardware completes the | |
160 | operation, normally it is detected by a polling function or an interrupt, as the | |
161 | user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously, | |
162 | then the registered callback will be called. | |
163 | ||
ff75a257 MC |
164 | =head1 RETURN VALUES |
165 | ||
166 | ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or | |
167 | NULL on error. | |
168 | ||
169 | ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, | |
9f5a87fd PY |
170 | ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, |
171 | ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and | |
172 | ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error. | |
173 | ASYNC_WAIT_CTX_get_status() returs the engine status. | |
174 | ||
ff75a257 | 175 | |
f1f5ee17 AP |
176 | =head1 NOTES |
177 | ||
178 | On Windows platforms the openssl/async.h header is dependent on some | |
179 | of the types customarily made available by including windows.h. The | |
180 | application developer is likely to require control over when the latter | |
181 | is included, commonly as one of the first included headers. Therefore | |
182 | it is defined as an application developer's responsibility to include | |
183 | windows.h prior to async.h. | |
184 | ||
ff75a257 MC |
185 | =head1 SEE ALSO |
186 | ||
b97fdb57 | 187 | L<crypto(7)>, L<ASYNC_start_job(3)> |
ff75a257 MC |
188 | |
189 | =head1 HISTORY | |
190 | ||
fc5ecadd DMSP |
191 | ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(), ASYNC_WAIT_CTX_set_wait_fd(), |
192 | ASYNC_WAIT_CTX_get_fd(), ASYNC_WAIT_CTX_get_all_fds(), | |
193 | ASYNC_WAIT_CTX_get_changed_fds() and ASYNC_WAIT_CTX_clear_fd() | |
194 | were added in OpenSSL 1.1.0. | |
ff75a257 | 195 | |
9f5a87fd PY |
196 | ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(), |
197 | ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status() | |
198 | were added in OpenSSL 3.0.0. | |
199 | ||
e2f92610 RS |
200 | =head1 COPYRIGHT |
201 | ||
202 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
203 | ||
4746f25a | 204 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
205 | this file except in compliance with the License. You can obtain a copy |
206 | in the file LICENSE in the source distribution or at | |
207 | L<https://www.openssl.org/source/license.html>. | |
208 | ||
209 | =cut |