root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity
openssl/doc/man3/ASYNC_WAIT_CTX_new.pod

227 lines
11 KiB
Plaintext
Raw Normal View History

Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
=pod
=head1 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,
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
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
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
=head1 SYNOPSIS
#include <openssl/async.h>
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
#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);
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
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,
OSSL_ASYNC_FD fd,
void *custom_data,
void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
doc/man3: reformat the function prototypes in the synopses I tried hard to keep the lines at 80 characters or less, but in a few cases I had to punt and just indented the subsequent lines by 4 spaces. A few well-placed typedefs for callback functions would really help, but these would be part of the API, so that's probably for later. I also took the liberty of inserting empty lines in overlong blocks to provide some visual space. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1956)
2017-01-21 02:58:49 +08:00
OSSL_ASYNC_FD, void *));
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
OSSL_ASYNC_FD *fd, void **custom_data);
int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
size_t *numfds);
int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
size_t *numaddfds, OSSL_ASYNC_FD *delfd,
size_t *numdelfds);
int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
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);
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
=head1 DESCRIPTION
For an overview of how asynchronous operations are implemented in OpenSSL see
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
L<ASYNC_start_job(3)>. An B<ASYNC_WAIT_CTX> object represents an asynchronous
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
"session", i.e. a related set of crypto operations. For example in SSL terms
this would have a one-to-one correspondence with an SSL connection.
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
Application code must create an B<ASYNC_WAIT_CTX> using the ASYNC_WAIT_CTX_new()
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
the job is started it is associated with the B<ASYNC_WAIT_CTX> for the duration
of that job. An B<ASYNC_WAIT_CTX> should only be used for one B<ASYNC_JOB> at
any one time, but can be reused after an B<ASYNC_JOB> has finished for a
subsequent B<ASYNC_JOB>. When the session is complete (e.g. the SSL connection
is closed), application code cleans up with ASYNC_WAIT_CTX_free().
B<ASYNC_WAIT_CTX>s can have "wait" file descriptors associated with them.
Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an
B<ASYNC_WAIT_CTX> in the I<ctx> parameter will return the wait file descriptors
associated with that job in I<*fd>. The number of file descriptors returned will
be stored in I<*numfds>. It is the caller's responsibility to ensure that
sufficient memory has been allocated in I<*fd> to receive all the file
descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL I<fd> value will
Fix typos and repeated words CLA: trivial Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/12320)
2020-06-30 03:13:07 +08:00
return no file descriptors but will still populate I<*numfds>. Therefore,
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
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.
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
Fix typo in ASYNC_WAIT_CTX_new.pod doc For the function that get the changed fds, it should be 'ASYNC_WAIT_CTX_get_changed_fds()' instead of 'ASYNC_WAIT_CTX_fds_have_changed()'. CLA: trivial Signed-off-by: Paul Yang <paulyang.inf@gmail.com> Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/2966)
2017-03-16 16:58:30 +08:00
The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
have changed since the last call time ASYNC_start_job() returned B<ASYNC_PAUSE>
(or since the B<ASYNC_WAIT_CTX> was created if no B<ASYNC_PAUSE> result has
been received). The I<numaddfds> and I<numdelfds> parameters will be populated
with the number of fds added or deleted respectively. I<*addfd> and I<*delfd>
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
will be populated with the list of added and deleted fds respectively. Similarly
to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
NULL then the caller is responsible for ensuring sufficient memory is allocated.
Implementors of async aware code (e.g. engines) are encouraged to return a
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
stable fd for the lifetime of the B<ASYNC_WAIT_CTX> in order to reduce the
"churn" of regularly changing fds - although no guarantees of this are provided
to applications.
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
Applications can wait for the file descriptor to be ready for "read" using a
system function call such as select or poll (being ready for "read" indicates
that the job should be resumed). If no file descriptor is made available then an
application will have to periodically "poll" the job by attempting to restart it
to see if it is ready to continue.
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
Async aware code (e.g. engines) can get the current B<ASYNC_WAIT_CTX> from the
job via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for
waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done
by an engine immediately prior to calling ASYNC_pause_job() and not by end user
code. An existing association with a file descriptor can be obtained using
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
these functions requires a I<key> value which is unique to the async aware
Fix broken link to ASYNC_get_wait_ctx and rewrap the paragraph Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1745)
2016-10-18 17:53:14 +08:00
code. This could be any unique value but a good candidate might be the
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
B<ENGINE *> for the engine. The I<custom_data> parameter can be any value, and
Fix broken link to ASYNC_get_wait_ctx and rewrap the paragraph Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1745)
2016-10-18 17:53:14 +08:00
will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
Fix broken link to ASYNC_get_wait_ctx and rewrap the paragraph Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1745)
2016-10-18 17:53:14 +08:00
routine. This can be NULL but if provided will automatically get called when
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
the B<ASYNC_WAIT_CTX> is freed, and gives the engine the opportunity to close
the fd or any other resources. Note: The "cleanup" routine does not get called
if the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
An example of typical usage might be an async capable engine. User code would
initiate cryptographic operations. The engine would initiate those operations
asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
ASYNC_pause_job() to return control to the user code. The user code can then
perform other tasks or wait for the job to be ready by calling "select" or other
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
"readable". Once resumed the engine should clear the wake signal on the wait
file descriptor.
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
As well as a file descriptor, user code may also be notified via a callback. The
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
callback and data pointers are stored within the B<ASYNC_WAIT_CTX> along with an
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
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 CPU cycles or in some context where a file
descriptor is not appropriate.
ASYNC_WAIT_CTX_set_callback() 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
Align documentation with recommendations of Linux Documentation Project This change applies the recommendation of the Linux Documentation Project to the documentation files of OpenSSL. Additionally, util/find-doc-nits was updated accordingly. The change follows a suggestion of mspncp on https://github.com/openssl/openssl/pull/12370 and incoporates the requested changes on the pull request Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/12460)
2020-07-17 18:31:26 +08:00
and nonblocking as it will be run in the context of a polling mechanism or an
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
interrupt.
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
ASYNC_WAIT_CTX_get_callback() returns the callback set in the B<ASYNC_WAIT_CTX>
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
structure.
ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status.
The possible status values are the following:
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
=over 4
=item B<ASYNC_STATUS_UNSUPPORTED>
The engine does not support the callback mechanism. This is the default value.
The engine must call ASYNC_WAIT_CTX_set_status() to set the status to some value
other than B<ASYNC_STATUS_UNSUPPORTED> if it intends to enable the callback
mechanism.
=item B<ASYNC_STATUS_ERR>
The engine has a fatal problem with this request. The user code should clean up
this session.
=item B<ASYNC_STATUS_OK>
The request has been successfully submitted.
=item B<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.
=back
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value.
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
If the status is any value other than B<ASYNC_STATUS_OK> then the user code
should not expect to receive a callback from the engine even if one has been
set.
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
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 ASYNC_pause_job() 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 ASYNC_WAIT_CTX_set_callback() previously,
then the registered callback will be called.
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
=head1 RETURN VALUES
Make ASYNC manuals conform with man-pages(7) Details from man-pages(7) that are used: Formatting conventions for manual pages describing functions ... Variable names should, like argument names, be specified in italics. ... Formatting conventions (general) ... Special macros, which are usually in uppercase, are in bold. Exception: don't boldface NULL. ... Additionally, expanded some lists to make better use of POD formatting. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10043)
2019-09-28 14:45:05 +08:00
ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated B<ASYNC_WAIT_CTX>
or NULL on error.
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
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.
Fix some typos Reported-by: misspell-fixer <https://github.com/vlajos/misspell-fixer> CLA: trivial Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10544)
2019-12-01 07:18:47 +08:00
ASYNC_WAIT_CTX_get_status() returns the engine status.
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
include/openssl: don't include <windows.h> in public headers. If application uses any of Windows-specific interfaces, make it application developer's respondibility to include <windows.h>. Rationale is that <windows.h> is quite "toxic" and is sensitive to inclusion order (most notably in relation to <winsock2.h>). It's only natural to give complete control to the application developer. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2016-06-26 19:40:15 +08:00
=head1 NOTES
Make header references conform with man-pages(7) in all manuals Details from man-pages(7) that are used: Formatting conventions (general) ... Filenames (whether pathnames, or references to header files) are always in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐ cluded files are in bold (e.g., #include <stdio.h>). When referring to a standard header file include, specify the header file surrounded by angle brackets, in the usual C way (e.g., <stdio.h>). ... Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13843)
2021-01-12 22:44:43 +08:00
On Windows platforms the F<< <openssl/async.h> >> header is dependent on some
of the types customarily made available by including F<< <windows.h> >>. The
include/openssl: don't include <windows.h> in public headers. If application uses any of Windows-specific interfaces, make it application developer's respondibility to include <windows.h>. Rationale is that <windows.h> is quite "toxic" and is sensitive to inclusion order (most notably in relation to <winsock2.h>). It's only natural to give complete control to the application developer. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2016-06-26 19:40:15 +08:00
application developer is likely to require control over when the latter
Fix typos and repeated words CLA: trivial Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/12320)
2020-06-30 03:13:07 +08:00
is included, commonly as one of the first included headers. Therefore,
include/openssl: don't include <windows.h> in public headers. If application uses any of Windows-specific interfaces, make it application developer's respondibility to include <windows.h>. Rationale is that <windows.h> is quite "toxic" and is sensitive to inclusion order (most notably in relation to <winsock2.h>). It's only natural to give complete control to the application developer. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2016-06-26 19:40:15 +08:00
it is defined as an application developer's responsibility to include
Make header references conform with man-pages(7) in all manuals Details from man-pages(7) that are used: Formatting conventions (general) ... Filenames (whether pathnames, or references to header files) are always in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐ cluded files are in bold (e.g., #include <stdio.h>). When referring to a standard header file include, specify the header file surrounded by angle brackets, in the usual C way (e.g., <stdio.h>). ... Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13843)
2021-01-12 22:44:43 +08:00
F<< <windows.h> >> prior to F<< <openssl/async.h> >>.
include/openssl: don't include <windows.h> in public headers. If application uses any of Windows-specific interfaces, make it application developer's respondibility to include <windows.h>. Rationale is that <windows.h> is quite "toxic" and is sensitive to inclusion order (most notably in relation to <winsock2.h>). It's only natural to give complete control to the application developer. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2016-06-26 19:40:15 +08:00
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
=head1 SEE ALSO
Fix referenses in section 3 manuals Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1900)
2016-11-11 16:33:09 +08:00
L<crypto(7)>, L<ASYNC_start_job(3)>
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
=head1 HISTORY
man: harmonize the various formulations in the HISTORY sections While stereotyped repetitions are frowned upon in literature, they serve a useful purpose in manual pages, because it is easier for the user to find certain information if it is always presented in the same way. For that reason, this commit harmonizes the varying formulations in the HISTORY section about which functions, flags, etc. were added in which OpenSSL version. It also attempts to make the pod files more grep friendly by avoiding to insert line breaks between the symbol names and the corresponding version number in which they were introduced (wherever possible). Some punctuation and typographical errors were fixed on the way. Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7854)
2018-12-09 08:02:36 +08:00
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() and ASYNC_WAIT_CTX_clear_fd()
were added in OpenSSL 1.1.0.
Refactor the async wait fd logic Implementation experience has shown that the original plan for async wait fds was too simplistic. Originally the async logic created a pipe internally and user/engine code could then get access to it via API calls. It is more flexible if the engine is able to create its own fd and provide it to the async code. Another issue is that there can be a lot of churn in the fd value within the context of (say) a single SSL connection leading to continually adding and removing fds from (say) epoll. It is better if we can provide some stability of the fd value across a whole SSL connection. This is problematic because an engine has no concept of an SSL connection. This commit refactors things to introduce an ASYNC_WAIT_CTX which acts as a proxy for an SSL connection down at the engine layer. Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-01-25 23:28:57 +08:00
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(),
ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status()
In documentation, consistently refer to OpenSSL 3.0 3.0.0 is a habit from pre-3.0 OpenSSL, which doesn't make sense with the new version scheme. Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9376)
2019-07-15 21:03:44 +08:00
were added in OpenSSL 3.0.
add an additional async notification communication method based on callback Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Paul Yang <yang.yang@baishancloud.com> Signed-off-by: Ping Yu <ping.yu@intel.com> Signed-off-by: Steven Linsell <stevenx.linsell@intel.com> (Merged from https://github.com/openssl/openssl/pull/7573)
2018-11-06 04:41:01 +08:00
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
=head1 COPYRIGHT
Update copyright year Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/13999)
2021-01-28 20:54:57 +08:00
Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut