1ASYNC_WAIT_CTX_NEW(3)               OpenSSL              ASYNC_WAIT_CTX_NEW(3)
2
3
4

NAME

6       ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
7       ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
8       ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to
9       manage waiting for asynchronous jobs to complete
10

SYNOPSIS

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

DESCRIPTION

31       For an overview of how asynchronous operations are implemented in
32       OpenSSL see ASYNC_start_job(3). An ASYNC_WAIT_CTX object represents an
33       asynchronous "session", i.e. a related set of crypto operations. For
34       example in SSL terms this would have a one-to-one correspondence with
35       an SSL connection.
36
37       Application code must create an ASYNC_WAIT_CTX using the
38       ASYNC_WAIT_CTX_new() function prior to calling ASYNC_start_job() (see
39       ASYNC_start_job(3)). When the job is started it is associated with the
40       ASYNC_WAIT_CTX for the duration of that job. An ASYNC_WAIT_CTX should
41       only be used for one ASYNC_JOB at any one time, but can be reused after
42       an ASYNC_JOB has finished for a subsequent ASYNC_JOB. When the session
43       is complete (e.g. the SSL connection is closed), application code
44       cleans up with ASYNC_WAIT_CTX_free().
45
46       ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them.
47       Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an
48       ASYNC_WAIT_CTX in the ctx parameter will return the wait file
49       descriptors associated with that job in *fd. The number of file
50       descriptors returned will be stored in *numfds. It is the caller's
51       responsibility to ensure that sufficient memory has been allocated in
52       *fd to receive all the file descriptors. Calling
53       ASYNC_WAIT_CTX_get_all_fds() with a NULL fd value will return no file
54       descriptors but will still populate *numfds. Therefore, application
55       code is typically expected to call this function twice: once to get the
56       number of fds, and then again when sufficient memory has been
57       allocated. If only one asynchronous engine is being used then normally
58       this call will only ever return one fd. If multiple asynchronous
59       engines are being used then more could be returned.
60
61       The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if
62       any fds have changed since the last call time ASYNC_start_job()
63       returned an ASYNC_PAUSE result (or since the ASYNC_WAIT_CTX was created
64       if no ASYNC_PAUSE result has been received). The numaddfds and
65       numdelfds parameters will be populated with the number of fds added or
66       deleted respectively. *addfd and *delfd will be populated with the list
67       of added and deleted fds respectively. Similarly to
68       ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they
69       are not NULL then the caller is responsible for ensuring sufficient
70       memory is allocated.
71
72       Implementors of async aware code (e.g. engines) are encouraged to
73       return a stable fd for the lifetime of the ASYNC_WAIT_CTX in order to
74       reduce the "churn" of regularly changing fds - although no guarantees
75       of this are provided to applications.
76
77       Applications can wait for the file descriptor to be ready for "read"
78       using a system function call such as select or poll (being ready for
79       "read" indicates that the job should be resumed). If no file descriptor
80       is made available then an application will have to periodically "poll"
81       the job by attempting to restart it to see if it is ready to continue.
82
83       Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from
84       the job via ASYNC_get_wait_ctx(3) and provide a file descriptor to use
85       for waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this
86       would be done by an engine immediately prior to calling
87       ASYNC_pause_job() and not by end user code.  An existing association
88       with a file descriptor can be obtained using ASYNC_WAIT_CTX_get_fd()
89       and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of these functions
90       requires a key value which is unique to the async aware code.  This
91       could be any unique value but a good candidate might be the ENGINE *
92       for the engine. The custom_data parameter can be any value, and will be
93       returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
94       ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a
95       "cleanup" routine. This can be NULL but if provided will automatically
96       get called when the ASYNC_WAIT_CTX is freed, and gives the engine the
97       opportunity to close the fd or any other resources. Note: The "cleanup"
98       routine does not get called if the fd is cleared directly via a call to
99       ASYNC_WAIT_CTX_clear_fd().
100
101       An example of typical usage might be an async capable engine. User code
102       would initiate cryptographic operations. The engine would initiate
103       those operations asynchronously and then call
104       ASYNC_WAIT_CTX_set_wait_fd() followed by ASYNC_pause_job() to return
105       control to the user code. The user code can then perform other tasks or
106       wait for the job to be ready by calling "select" or other similar
107       function on the wait file descriptor. The engine can signal to the user
108       code that the job should be resumed by making the wait file descriptor
109       "readable". Once resumed the engine should clear the wake signal on the
110       wait file descriptor.
111

RETURN VALUES

113       ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated
114       ASYNC_WAIT_CTX or NULL on error.
115
116       ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd,
117       ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds and
118       ASYNC_WAIT_CTX_clear_fd all return 1 on success or 0 on error.
119

NOTES

121       On Windows platforms the openssl/async.h header is dependent on some of
122       the types customarily made available by including windows.h. The
123       application developer is likely to require control over when the latter
124       is included, commonly as one of the first included headers. Therefore,
125       it is defined as an application developer's responsibility to include
126       windows.h prior to async.h.
127

SEE ALSO

129       crypto(7), ASYNC_start_job(3)
130

HISTORY

132       ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(),
133       ASYNC_WAIT_CTX_set_wait_fd(), ASYNC_WAIT_CTX_get_fd(),
134       ASYNC_WAIT_CTX_get_all_fds(), ASYNC_WAIT_CTX_get_changed_fds() and
135       ASYNC_WAIT_CTX_clear_fd() were added in OpenSSL 1.1.0.
136
138       Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
139
140       Licensed under the OpenSSL license (the "License").  You may not use
141       this file except in compliance with the License.  You can obtain a copy
142       in the file LICENSE in the source distribution or at
143       <https://www.openssl.org/source/license.html>.
144
145
146
1471.1.1q                            2023-02-06             ASYNC_WAIT_CTX_NEW(3)
Impressum