]>
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, | |
7 | ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage | |
8 | waiting for asynchronous jobs to complete | |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/async.h> | |
13 | ||
14 | ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void); | |
15 | void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx); | |
16 | int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key, | |
17 | OSSL_ASYNC_FD fd, | |
18 | void *custom_data, | |
19 | void (*cleanup)(ASYNC_WAIT_CTX *, const void *, | |
20 | OSSL_ASYNC_FD, void *)); | |
21 | int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key, | |
22 | OSSL_ASYNC_FD *fd, void **custom_data); | |
23 | int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd, | |
24 | size_t *numfds); | |
25 | int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd, | |
26 | size_t *numaddfds, OSSL_ASYNC_FD *delfd, | |
27 | size_t *numdelfds); | |
28 | int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key); | |
29 | ||
30 | ||
31 | =head1 DESCRIPTION | |
32 | ||
33 | For an overview of how asynchronous operations are implemented in OpenSSL see | |
34 | L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous | |
35 | "session", i.e. a related set of crypto operations. For example in SSL terms | |
36 | this would have a one-to-one correspondence with an SSL connection. | |
37 | ||
38 | Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new() | |
39 | function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When | |
40 | the job is started it is associated with the ASYNC_WAIT_CTX for the duration of | |
41 | that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one | |
42 | time, but can be reused after an ASYNC_JOB has finished for a subsequent | |
43 | ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed), | |
44 | application code cleans up with ASYNC_WAIT_CTX_free(). | |
45 | ||
46 | ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling | |
47 | ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in | |
48 | the B<ctx> parameter will return the wait file descriptors associated with that | |
49 | job in B<*fd>. The number of file descriptors returned will be stored in | |
50 | B<*numfds>. It is the caller's responsibility to ensure that sufficient memory | |
51 | has been allocated in B<*fd> to receive all the file descriptors. Calling | |
52 | ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file | |
53 | descriptors but will still populate B<*numfds>. Therefore application code is | |
54 | typically expected to call this function twice: once to get the number of fds, | |
55 | and then again when sufficient memory has been allocated. If only one | |
24c2cd39 | 56 | asynchronous engine is being used then normally this call will only ever return |
ff75a257 MC |
57 | one fd. If multiple asynchronous engines are being used then more could be |
58 | returned. | |
59 | ||
7baabf45 | 60 | The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds |
ff75a257 MC |
61 | have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE |
62 | result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has | |
63 | been received). The B<numaddfds> and B<numdelfds> parameters will be populated | |
64 | with the number of fds added or deleted respectively. B<*addfd> and B<*delfd> | |
65 | will be populated with the list of added and deleted fds respectively. Similarly | |
66 | to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not | |
67 | NULL then the caller is responsible for ensuring sufficient memory is allocated. | |
68 | ||
69 | Implementors of async aware code (e.g. engines) are encouraged to return a | |
70 | stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn" | |
71 | of regularly changing fds - although no guarantees of this are provided to | |
72 | applications. | |
73 | ||
74 | Applications can wait for the file descriptor to be ready for "read" using a | |
75 | system function call such as select or poll (being ready for "read" indicates | |
76 | that the job should be resumed). If no file descriptor is made available then an | |
77 | application will have to periodically "poll" the job by attempting to restart it | |
78 | to see if it is ready to continue. | |
79 | ||
80 | Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job | |
50c3fc00 AG |
81 | via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting |
82 | on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an | |
83 | engine immediately prior to calling ASYNC_pause_job() and not by end user code. | |
84 | An existing association with a file descriptor can be obtained using | |
ff75a257 | 85 | ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of |
50c3fc00 AG |
86 | these functions requires a B<key> value which is unique to the async aware |
87 | code. This could be any unique value but a good candidate might be the | |
88 | B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and | |
89 | will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The | |
ff75a257 | 90 | ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup" |
50c3fc00 AG |
91 | routine. This can be NULL but if provided will automatically get called when |
92 | the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the | |
93 | fd or any other resources. Note: The "cleanup" routine does not get called if | |
94 | the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd(). | |
ff75a257 MC |
95 | |
96 | An example of typical usage might be an async capable engine. User code would | |
97 | initiate cryptographic operations. The engine would initiate those operations | |
98 | asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by | |
99 | ASYNC_pause_job() to return control to the user code. The user code can then | |
100 | perform other tasks or wait for the job to be ready by calling "select" or other | |
101 | similar function on the wait file descriptor. The engine can signal to the user | |
102 | code that the job should be resumed by making the wait file descriptor | |
103 | "readable". Once resumed the engine should clear the wake signal on the wait | |
104 | file descriptor. | |
105 | ||
106 | =head1 RETURN VALUES | |
107 | ||
108 | ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or | |
109 | NULL on error. | |
110 | ||
111 | ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, | |
112 | ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on | |
113 | success or 0 on error. | |
114 | ||
f1f5ee17 AP |
115 | =head1 NOTES |
116 | ||
117 | On Windows platforms the openssl/async.h header is dependent on some | |
118 | of the types customarily made available by including windows.h. The | |
119 | application developer is likely to require control over when the latter | |
120 | is included, commonly as one of the first included headers. Therefore | |
121 | it is defined as an application developer's responsibility to include | |
122 | windows.h prior to async.h. | |
123 | ||
ff75a257 MC |
124 | =head1 SEE ALSO |
125 | ||
b97fdb57 | 126 | L<crypto(7)>, L<ASYNC_start_job(3)> |
ff75a257 MC |
127 | |
128 | =head1 HISTORY | |
129 | ||
130 | ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, | |
131 | ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, | |
132 | ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to | |
133 | OpenSSL 1.1.0. | |
134 | ||
e2f92610 RS |
135 | =head1 COPYRIGHT |
136 | ||
137 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
138 | ||
139 | Licensed under the OpenSSL license (the "License"). You may not use | |
140 | this file except in compliance with the License. You can obtain a copy | |
141 | in the file LICENSE in the source distribution or at | |
142 | L<https://www.openssl.org/source/license.html>. | |
143 | ||
144 | =cut |