Debian Codegraph @

upstream/debian-unstable/man3/ASYNC_WAIT_CTX_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ASYNC_WAIT_CTX_NEW 3SSL"
58 .TH ASYNC_WAIT_CTX_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
65 ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
66 ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
67 ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback,
68 ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn,
69 ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK,
70 ASYNC_STATUS_EAGAIN
71 \&\- functions to manage waiting for asynchronous jobs to complete
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/async.h>
76 \&
77 \& #define ASYNC_STATUS_UNSUPPORTED 0
78 \& #define ASYNC_STATUS_ERR 1
79 \& #define ASYNC_STATUS_OK 2
80 \& #define ASYNC_STATUS_EAGAIN 3
81 \& typedef int (*ASYNC_callback_fn)(void *arg);
82 \& ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
83 \& void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
84 \& int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
85 \& OSSL_ASYNC_FD fd,
86 \& void *custom_data,
87 \& void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
88 \& OSSL_ASYNC_FD, void *));
89 \& int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
90 \& OSSL_ASYNC_FD *fd, void **custom_data);
91 \& int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
92 \& size_t *numfds);
93 \& int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
94 \& size_t *numaddfds, OSSL_ASYNC_FD *delfd,
95 \& size_t *numdelfds);
96 \& int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
97 \& int ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx,
98 \& ASYNC_callback_fn callback,
99 \& void *callback_arg);
100 \& int ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx,
101 \& ASYNC_callback_fn *callback,
102 \& void **callback_arg);
103 \& int ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status);
104 \& int ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx);
105 .Ve
106 .SH DESCRIPTION
107 .IX Header "DESCRIPTION"
108 For an overview of how asynchronous operations are implemented in OpenSSL see
109 \&\fBASYNC_start_job\fR\|(3). An \fBASYNC_WAIT_CTX\fR object represents an asynchronous
110 "session", i.e. a related set of crypto operations. For example in SSL terms
111 this would have a one-to-one correspondence with an SSL connection.
112 .PP
113 Application code must create an \fBASYNC_WAIT_CTX\fR using the \fBASYNC_WAIT_CTX_new()\fR
114 function prior to calling \fBASYNC_start_job()\fR (see \fBASYNC_start_job\fR\|(3)). When
115 the job is started it is associated with the \fBASYNC_WAIT_CTX\fR for the duration
116 of that job. An \fBASYNC_WAIT_CTX\fR should only be used for one \fBASYNC_JOB\fR at
117 any one time, but can be reused after an \fBASYNC_JOB\fR has finished for a
118 subsequent \fBASYNC_JOB\fR. When the session is complete (e.g. the SSL connection
119 is closed), application code cleans up with \fBASYNC_WAIT_CTX_free()\fR.
120 .PP
121 \&\fBASYNC_WAIT_CTX\fRs can have "wait" file descriptors associated with them.
122 Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an
123 \&\fBASYNC_WAIT_CTX\fR in the \fIctx\fR parameter will return the wait file descriptors
124 associated with that job in \fI*fd\fR. The number of file descriptors returned will
125 be stored in \fI*numfds\fR. It is the caller's responsibility to ensure that
126 sufficient memory has been allocated in \fI*fd\fR to receive all the file
127 descriptors. Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR with a NULL \fIfd\fR value will
128 return no file descriptors but will still populate \fI*numfds\fR. Therefore,
129 application code is typically expected to call this function twice: once to get
130 the number of fds, and then again when sufficient memory has been allocated. If
131 only one asynchronous engine is being used then normally this call will only
132 ever return one fd. If multiple asynchronous engines are being used then more
133 could be returned.
134 .PP
135 The function \fBASYNC_WAIT_CTX_get_changed_fds()\fR can be used to detect if any fds
136 have changed since the last call time \fBASYNC_start_job()\fR returned \fBASYNC_PAUSE\fR
137 (or since the \fBASYNC_WAIT_CTX\fR was created if no \fBASYNC_PAUSE\fR result has
138 been received). The \fInumaddfds\fR and \fInumdelfds\fR parameters will be populated
139 with the number of fds added or deleted respectively. \fI*addfd\fR and \fI*delfd\fR
140 will be populated with the list of added and deleted fds respectively. Similarly
141 to \fBASYNC_WAIT_CTX_get_all_fds()\fR either of these can be NULL, but if they are not
142 NULL then the caller is responsible for ensuring sufficient memory is allocated.
143 .PP
144 Implementers of async aware code (e.g. engines) are encouraged to return a
145 stable fd for the lifetime of the \fBASYNC_WAIT_CTX\fR in order to reduce the
146 "churn" of regularly changing fds \- although no guarantees of this are provided
147 to applications.
148 .PP
149 Applications can wait for the file descriptor to be ready for "read" using a
150 system function call such as select or poll (being ready for "read" indicates
151 that the job should be resumed). If no file descriptor is made available then an
152 application will have to periodically "poll" the job by attempting to restart it
153 to see if it is ready to continue.
154 .PP
155 Async aware code (e.g. engines) can get the current \fBASYNC_WAIT_CTX\fR from the
156 job via \fBASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for
157 waiting on by calling \fBASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done
158 by an engine immediately prior to calling \fBASYNC_pause_job()\fR and not by end user
159 code. An existing association with a file descriptor can be obtained using
160 \&\fBASYNC_WAIT_CTX_get_fd()\fR and cleared using \fBASYNC_WAIT_CTX_clear_fd()\fR. Both of
161 these functions requires a \fIkey\fR value which is unique to the async aware
162 code. This could be any unique value but a good candidate might be the
163 \&\fBENGINE *\fR for the engine. The \fIcustom_data\fR parameter can be any value, and
164 will be returned in a subsequent call to \fBASYNC_WAIT_CTX_get_fd()\fR. The
165 \&\fBASYNC_WAIT_CTX_set_wait_fd()\fR function also expects a pointer to a "cleanup"
166 routine. This can be NULL but if provided will automatically get called when
167 the \fBASYNC_WAIT_CTX\fR is freed, and gives the engine the opportunity to close
168 the fd or any other resources. Note: The "cleanup" routine does not get called
169 if the fd is cleared directly via a call to \fBASYNC_WAIT_CTX_clear_fd()\fR.
170 .PP
171 An example of typical usage might be an async capable engine. User code would
172 initiate cryptographic operations. The engine would initiate those operations
173 asynchronously and then call \fBASYNC_WAIT_CTX_set_wait_fd()\fR followed by
174 \&\fBASYNC_pause_job()\fR to return control to the user code. The user code can then
175 perform other tasks or wait for the job to be ready by calling "select" or other
176 similar function on the wait file descriptor. The engine can signal to the user
177 code that the job should be resumed by making the wait file descriptor
178 "readable". Once resumed the engine should clear the wake signal on the wait
179 file descriptor.
180 .PP
181 As well as a file descriptor, user code may also be notified via a callback. The
182 callback and data pointers are stored within the \fBASYNC_WAIT_CTX\fR along with an
183 additional status field that can be used for the notification of retries from an
184 engine. This additional method can be used when the user thinks that a file
185 descriptor is too costly in terms of CPU cycles or in some context where a file
186 descriptor is not appropriate.
187 .PP
188 \&\fBASYNC_WAIT_CTX_set_callback()\fR sets the callback and the callback argument. The
189 callback will be called to notify user code when an engine completes a
190 cryptography operation. It is a requirement that the callback function is small
191 and nonblocking as it will be run in the context of a polling mechanism or an
192 interrupt.
193 .PP
194 \&\fBASYNC_WAIT_CTX_get_callback()\fR returns the callback set in the \fBASYNC_WAIT_CTX\fR
195 structure.
196 .PP
197 \&\fBASYNC_WAIT_CTX_set_status()\fR allows an engine to set the current engine status.
198 The possible status values are the following:
199 .IP \fBASYNC_STATUS_UNSUPPORTED\fR 4
200 .IX Item "ASYNC_STATUS_UNSUPPORTED"
201 The engine does not support the callback mechanism. This is the default value.
202 The engine must call \fBASYNC_WAIT_CTX_set_status()\fR to set the status to some value
203 other than \fBASYNC_STATUS_UNSUPPORTED\fR if it intends to enable the callback
204 mechanism.
205 .IP \fBASYNC_STATUS_ERR\fR 4
206 .IX Item "ASYNC_STATUS_ERR"
207 The engine has a fatal problem with this request. The user code should clean up
208 this session.
209 .IP \fBASYNC_STATUS_OK\fR 4
210 .IX Item "ASYNC_STATUS_OK"
211 The request has been successfully submitted.
212 .IP \fBASYNC_STATUS_EAGAIN\fR 4
213 .IX Item "ASYNC_STATUS_EAGAIN"
214 The engine has some problem which will be recovered soon, such as a buffer is
215 full, so user code should resume the job.
216 .PP
217 \&\fBASYNC_WAIT_CTX_get_status()\fR allows user code to obtain the current status value.
218 If the status is any value other than \fBASYNC_STATUS_OK\fR then the user code
219 should not expect to receive a callback from the engine even if one has been
220 set.
221 .PP
222 An example of the usage of the callback method might be the following. User
223 code would initiate cryptographic operations, and the engine code would dispatch
224 this operation to hardware, and if the dispatch is successful, then the engine
225 code would call \fBASYNC_pause_job()\fR to return control to the user code. After
226 that, user code can perform other tasks. When the hardware completes the
227 operation, normally it is detected by a polling function or an interrupt, as the
228 user code set a callback by calling \fBASYNC_WAIT_CTX_set_callback()\fR previously,
229 then the registered callback will be called.
230 .PP
231 \&\fBASYNC_WAIT_CTX_free()\fR frees up a single \fBASYNC_WAIT_CTX\fR object.
232 If the argument is NULL, nothing is done.
233 .SH "RETURN VALUES"
234 .IX Header "RETURN VALUES"
235 \&\fBASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \fBASYNC_WAIT_CTX\fR
236 or NULL on error.
237 .PP
238 ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
239 ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
240 ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and
241 ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error.
242 \&\fBASYNC_WAIT_CTX_get_status()\fR returns the engine status.
243 .SH NOTES
244 .IX Header "NOTES"
245 On Windows platforms the \fI<openssl/async.h>\fR header is dependent on some
246 of the types customarily made available by including \fI<windows.h>\fR. The
247 application developer is likely to require control over when the latter
248 is included, commonly as one of the first included headers. Therefore,
249 it is defined as an application developer's responsibility to include
250 \&\fI<windows.h>\fR prior to \fI<openssl/async.h>\fR.
251 .SH "SEE ALSO"
252 .IX Header "SEE ALSO"
253 \&\fBcrypto\fR\|(7), \fBASYNC_start_job\fR\|(3)
254 .SH HISTORY
255 .IX Header "HISTORY"
256 \&\fBASYNC_WAIT_CTX_new()\fR, \fBASYNC_WAIT_CTX_free()\fR, \fBASYNC_WAIT_CTX_set_wait_fd()\fR,
257 \&\fBASYNC_WAIT_CTX_get_fd()\fR, \fBASYNC_WAIT_CTX_get_all_fds()\fR,
258 \&\fBASYNC_WAIT_CTX_get_changed_fds()\fR and \fBASYNC_WAIT_CTX_clear_fd()\fR
259 were added in OpenSSL 1.1.0.
260 .PP
261 \&\fBASYNC_WAIT_CTX_set_callback()\fR, \fBASYNC_WAIT_CTX_get_callback()\fR,
262 \&\fBASYNC_WAIT_CTX_set_status()\fR, and \fBASYNC_WAIT_CTX_get_status()\fR
263 were added in OpenSSL 3.0.
264 .SH COPYRIGHT
265 .IX Header "COPYRIGHT"
266 Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
267 .PP
268 Licensed under the Apache License 2.0 (the "License"). You may not use
269 this file except in compliance with the License. You can obtain a copy
270 in the file LICENSE in the source distribution or at
271 <https://www.openssl.org/source/license.html>.