diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/ASYNC_WAIT_CTX_new.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/ASYNC_WAIT_CTX_new.3 | 180 |
1 files changed, 127 insertions, 53 deletions
diff --git a/secure/lib/libcrypto/man/man3/ASYNC_WAIT_CTX_new.3 b/secure/lib/libcrypto/man/man3/ASYNC_WAIT_CTX_new.3 index e484f5f6e026..875e7d1ef64b 100644 --- a/secure/lib/libcrypto/man/man3/ASYNC_WAIT_CTX_new.3 +++ b/secure/lib/libcrypto/man/man3/ASYNC_WAIT_CTX_new.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,19 +130,31 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "ASYNC_WAIT_CTX_NEW 3" -.TH ASYNC_WAIT_CTX_NEW 3 "2022-07-05" "1.1.1q" "OpenSSL" +.IX Title "ASYNC_WAIT_CTX_NEW 3ossl" +.TH ASYNC_WAIT_CTX_NEW 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd \- functions to manage waiting for asynchronous jobs to complete +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, +ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback, +ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn, +ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK, +ASYNC_STATUS_EAGAIN +\&\- functions to manage waiting for asynchronous jobs to complete .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/async.h> \& +\& #define ASYNC_STATUS_UNSUPPORTED 0 +\& #define ASYNC_STATUS_ERR 1 +\& #define ASYNC_STATUS_OK 2 +\& #define ASYNC_STATUS_EAGAIN 3 +\& typedef int (*ASYNC_callback_fn)(void *arg); \& ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void); \& void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx); \& int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key, @@ -160,49 +170,57 @@ ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_ \& size_t *numaddfds, OSSL_ASYNC_FD *delfd, \& size_t *numdelfds); \& int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key); +\& int ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx, +\& ASYNC_callback_fn callback, +\& void *callback_arg); +\& int ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx, +\& ASYNC_callback_fn *callback, +\& void **callback_arg); +\& int ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status); +\& int ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" For an overview of how asynchronous operations are implemented in OpenSSL see -\&\fBASYNC_start_job\fR\|(3). An \s-1ASYNC_WAIT_CTX\s0 object represents an asynchronous +\&\fBASYNC_start_job\fR\|(3). An \fB\s-1ASYNC_WAIT_CTX\s0\fR object represents an asynchronous \&\*(L"session\*(R", i.e. a related set of crypto operations. For example in \s-1SSL\s0 terms this would have a one-to-one correspondence with an \s-1SSL\s0 connection. .PP -Application code must create an \s-1ASYNC_WAIT_CTX\s0 using the \fBASYNC_WAIT_CTX_new()\fR +Application code must create an \fB\s-1ASYNC_WAIT_CTX\s0\fR using the \fBASYNC_WAIT_CTX_new()\fR function prior to calling \fBASYNC_start_job()\fR (see \fBASYNC_start_job\fR\|(3)). When -the job is started it is associated with the \s-1ASYNC_WAIT_CTX\s0 for the duration of -that job. An \s-1ASYNC_WAIT_CTX\s0 should only be used for one \s-1ASYNC_JOB\s0 at any one -time, but can be reused after an \s-1ASYNC_JOB\s0 has finished for a subsequent -\&\s-1ASYNC_JOB.\s0 When the session is complete (e.g. the \s-1SSL\s0 connection is closed), -application code cleans up with \fBASYNC_WAIT_CTX_free()\fR. +the job is started it is associated with the \fB\s-1ASYNC_WAIT_CTX\s0\fR for the duration +of that job. An \fB\s-1ASYNC_WAIT_CTX\s0\fR should only be used for one \fB\s-1ASYNC_JOB\s0\fR at +any one time, but can be reused after an \fB\s-1ASYNC_JOB\s0\fR has finished for a +subsequent \fB\s-1ASYNC_JOB\s0\fR. When the session is complete (e.g. the \s-1SSL\s0 connection +is closed), application code cleans up with \fBASYNC_WAIT_CTX_free()\fR. .PP -ASYNC_WAIT_CTXs can have \*(L"wait\*(R" file descriptors associated with them. Calling -\&\fBASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an \s-1ASYNC_WAIT_CTX\s0 in -the \fBctx\fR parameter will return the wait file descriptors associated with that -job in \fB*fd\fR. The number of file descriptors returned will be stored in -\&\fB*numfds\fR. It is the caller's responsibility to ensure that sufficient memory -has been allocated in \fB*fd\fR to receive all the file descriptors. Calling -\&\fBASYNC_WAIT_CTX_get_all_fds()\fR with a \s-1NULL\s0 \fBfd\fR value will return no file -descriptors but will still populate \fB*numfds\fR. Therefore, application code is -typically expected to call this function twice: once to get the number of fds, -and then again when sufficient memory has been allocated. If only one -asynchronous engine is being used then normally this call will only ever return -one fd. If multiple asynchronous engines are being used then more could be -returned. +\&\fB\s-1ASYNC_WAIT_CTX\s0\fRs can have \*(L"wait\*(R" file descriptors associated with them. +Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an +\&\fB\s-1ASYNC_WAIT_CTX\s0\fR in the \fIctx\fR parameter will return the wait file descriptors +associated with that job in \fI*fd\fR. The number of file descriptors returned will +be stored in \fI*numfds\fR. It is the caller's responsibility to ensure that +sufficient memory has been allocated in \fI*fd\fR to receive all the file +descriptors. Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR with a \s-1NULL\s0 \fIfd\fR value will +return no file descriptors but will still populate \fI*numfds\fR. Therefore, +application code is typically expected to call this function twice: once to get +the number of fds, and then again when sufficient memory has been allocated. If +only one asynchronous engine is being used then normally this call will only +ever return one fd. If multiple asynchronous engines are being used then more +could be returned. .PP The function \fBASYNC_WAIT_CTX_get_changed_fds()\fR can be used to detect if any fds -have changed since the last call time \fBASYNC_start_job()\fR returned an \s-1ASYNC_PAUSE\s0 -result (or since the \s-1ASYNC_WAIT_CTX\s0 was created if no \s-1ASYNC_PAUSE\s0 result has -been received). The \fBnumaddfds\fR and \fBnumdelfds\fR parameters will be populated -with the number of fds added or deleted respectively. \fB*addfd\fR and \fB*delfd\fR +have changed since the last call time \fBASYNC_start_job()\fR returned \fB\s-1ASYNC_PAUSE\s0\fR +(or since the \fB\s-1ASYNC_WAIT_CTX\s0\fR was created if no \fB\s-1ASYNC_PAUSE\s0\fR result has +been received). The \fInumaddfds\fR and \fInumdelfds\fR parameters will be populated +with the number of fds added or deleted respectively. \fI*addfd\fR and \fI*delfd\fR will be populated with the list of added and deleted fds respectively. Similarly to \fBASYNC_WAIT_CTX_get_all_fds()\fR either of these can be \s-1NULL,\s0 but if they are not \&\s-1NULL\s0 then the caller is responsible for ensuring sufficient memory is allocated. .PP -Implementors of async aware code (e.g. engines) are encouraged to return a -stable fd for the lifetime of the \s-1ASYNC_WAIT_CTX\s0 in order to reduce the \*(L"churn\*(R" -of regularly changing fds \- although no guarantees of this are provided to -applications. +Implementers of async aware code (e.g. engines) are encouraged to return a +stable fd for the lifetime of the \fB\s-1ASYNC_WAIT_CTX\s0\fR in order to reduce the +\&\*(L"churn\*(R" of regularly changing fds \- although no guarantees of this are provided +to applications. .PP Applications can wait for the file descriptor to be ready for \*(L"read\*(R" using a system function call such as select or poll (being ready for \*(L"read\*(R" indicates @@ -210,21 +228,21 @@ that the job should be resumed). If no file descriptor is made available then an application will have to periodically \*(L"poll\*(R" the job by attempting to restart it to see if it is ready to continue. .PP -Async aware code (e.g. engines) can get the current \s-1ASYNC_WAIT_CTX\s0 from the job -via \fBASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for waiting -on by calling \fBASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done by an -engine immediately prior to calling \fBASYNC_pause_job()\fR and not by end user code. -An existing association with a file descriptor can be obtained using +Async aware code (e.g. engines) can get the current \fB\s-1ASYNC_WAIT_CTX\s0\fR from the +job via \fBASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for +waiting on by calling \fBASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done +by an engine immediately prior to calling \fBASYNC_pause_job()\fR and not by end user +code. An existing association with a file descriptor can be obtained using \&\fBASYNC_WAIT_CTX_get_fd()\fR and cleared using \fBASYNC_WAIT_CTX_clear_fd()\fR. Both of -these functions requires a \fBkey\fR value which is unique to the async aware +these functions requires a \fIkey\fR value which is unique to the async aware code. This could be any unique value but a good candidate might be the -\&\fB\s-1ENGINE\s0 *\fR for the engine. The \fBcustom_data\fR parameter can be any value, and +\&\fB\s-1ENGINE\s0 *\fR for the engine. The \fIcustom_data\fR parameter can be any value, and will be returned in a subsequent call to \fBASYNC_WAIT_CTX_get_fd()\fR. The \&\fBASYNC_WAIT_CTX_set_wait_fd()\fR function also expects a pointer to a \*(L"cleanup\*(R" routine. This can be \s-1NULL\s0 but if provided will automatically get called when -the \s-1ASYNC_WAIT_CTX\s0 is freed, and gives the engine the opportunity to close the -fd or any other resources. Note: The \*(L"cleanup\*(R" routine does not get called if -the fd is cleared directly via a call to \fBASYNC_WAIT_CTX_clear_fd()\fR. +the \fB\s-1ASYNC_WAIT_CTX\s0\fR is freed, and gives the engine the opportunity to close +the fd or any other resources. Note: The \*(L"cleanup\*(R" routine does not get called +if the fd is cleared directly via a call to \fBASYNC_WAIT_CTX_clear_fd()\fR. .PP An example of typical usage might be an async capable engine. User code would initiate cryptographic operations. The engine would initiate those operations @@ -235,22 +253,74 @@ similar function on the wait file descriptor. The engine can signal to the user code that the job should be resumed by making the wait file descriptor \&\*(L"readable\*(R". Once resumed the engine should clear the wake signal on the wait file descriptor. +.PP +As well as a file descriptor, user code may also be notified via a callback. The +callback and data pointers are stored within the \fB\s-1ASYNC_WAIT_CTX\s0\fR along with an +additional status field that can be used for the notification of retries from an +engine. This additional method can be used when the user thinks that a file +descriptor is too costly in terms of \s-1CPU\s0 cycles or in some context where a file +descriptor is not appropriate. +.PP +\&\fBASYNC_WAIT_CTX_set_callback()\fR sets the callback and the callback argument. The +callback will be called to notify user code when an engine completes a +cryptography operation. It is a requirement that the callback function is small +and nonblocking as it will be run in the context of a polling mechanism or an +interrupt. +.PP +\&\fBASYNC_WAIT_CTX_get_callback()\fR returns the callback set in the \fB\s-1ASYNC_WAIT_CTX\s0\fR +structure. +.PP +\&\fBASYNC_WAIT_CTX_set_status()\fR allows an engine to set the current engine status. +The possible status values are the following: +.IP "\fB\s-1ASYNC_STATUS_UNSUPPORTED\s0\fR" 4 +.IX Item "ASYNC_STATUS_UNSUPPORTED" +The engine does not support the callback mechanism. This is the default value. +The engine must call \fBASYNC_WAIT_CTX_set_status()\fR to set the status to some value +other than \fB\s-1ASYNC_STATUS_UNSUPPORTED\s0\fR if it intends to enable the callback +mechanism. +.IP "\fB\s-1ASYNC_STATUS_ERR\s0\fR" 4 +.IX Item "ASYNC_STATUS_ERR" +The engine has a fatal problem with this request. The user code should clean up +this session. +.IP "\fB\s-1ASYNC_STATUS_OK\s0\fR" 4 +.IX Item "ASYNC_STATUS_OK" +The request has been successfully submitted. +.IP "\fB\s-1ASYNC_STATUS_EAGAIN\s0\fR" 4 +.IX Item "ASYNC_STATUS_EAGAIN" +The engine has some problem which will be recovered soon, such as a buffer is +full, so user code should resume the job. +.PP +\&\fBASYNC_WAIT_CTX_get_status()\fR allows user code to obtain the current status value. +If the status is any value other than \fB\s-1ASYNC_STATUS_OK\s0\fR then the user code +should not expect to receive a callback from the engine even if one has been +set. +.PP +An example of the usage of the callback method might be the following. User +code would initiate cryptographic operations, and the engine code would dispatch +this operation to hardware, and if the dispatch is successful, then the engine +code would call \fBASYNC_pause_job()\fR to return control to the user code. After +that, user code can perform other tasks. When the hardware completes the +operation, normally it is detected by a polling function or an interrupt, as the +user code set a callback by calling \fBASYNC_WAIT_CTX_set_callback()\fR previously, +then the registered callback will be called. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fBASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \s-1ASYNC_WAIT_CTX\s0 or -\&\s-1NULL\s0 on error. +\&\fBASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \fB\s-1ASYNC_WAIT_CTX\s0\fR +or \s-1NULL\s0 on error. .PP ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, -ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on -success or 0 on error. +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, +ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and +ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error. +\&\fBASYNC_WAIT_CTX_get_status()\fR returns the engine status. .SH "NOTES" .IX Header "NOTES" -On Windows platforms the openssl/async.h header is dependent on some -of the types customarily made available by including windows.h. The +On Windows platforms the \fI<openssl/async.h>\fR header is dependent on some +of the types customarily made available by including \fI<windows.h>\fR. The application developer is likely to require control over when the latter is included, commonly as one of the first included headers. Therefore, it is defined as an application developer's responsibility to include -windows.h prior to async.h. +\&\fI<windows.h>\fR prior to \fI<openssl/async.h>\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBcrypto\fR\|(7), \fBASYNC_start_job\fR\|(3) @@ -260,11 +330,15 @@ windows.h prior to async.h. \&\fBASYNC_WAIT_CTX_get_fd()\fR, \fBASYNC_WAIT_CTX_get_all_fds()\fR, \&\fBASYNC_WAIT_CTX_get_changed_fds()\fR and \fBASYNC_WAIT_CTX_clear_fd()\fR were added in OpenSSL 1.1.0. +.PP +\&\fBASYNC_WAIT_CTX_set_callback()\fR, \fBASYNC_WAIT_CTX_get_callback()\fR, +\&\fBASYNC_WAIT_CTX_set_status()\fR, and \fBASYNC_WAIT_CTX_get_status()\fR +were added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>. |