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