In documentation, consistently refer to OpenSSL 3.0
[openssl.git] / doc / man3 / ASYNC_WAIT_CTX_new.pod
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,
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
13
14 =head1 SYNOPSIS
15
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
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
73 asynchronous engine is being used then normally this call will only ever return
74 one fd. If multiple asynchronous engines are being used then more could be
75 returned.
76
77 The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds
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
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
102 ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
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
107 ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
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().
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
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
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,
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
175
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
185 =head1 SEE ALSO
186
187 L<crypto(7)>, L<ASYNC_start_job(3)>
188
189 =head1 HISTORY
190
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.
195
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.
199
200 =head1 COPYRIGHT
201
202 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
203
204 Licensed under the Apache License 2.0 (the "License").  You may not use
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