Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ASYNC_WAIT_CTX_NEW(3)		    OpenSSL		 ASYNC_WAIT_CTX_NEW(3)

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

SYNOPSIS
	#include <openssl/async.h>

	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 *,
						       OSSL_ASYNC_FD, void *));
	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);

DESCRIPTION
       For an overview of how asynchronous operations are implemented in
       OpenSSL see ASYNC_start_job(3). An ASYNC_WAIT_CTX object	represents an
       asynchronous "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.

       Application code	must create an ASYNC_WAIT_CTX using the
       ASYNC_WAIT_CTX_new() function prior to calling ASYNC_start_job()	(see
       ASYNC_start_job(3)). When the job is started it is associated with the
       ASYNC_WAIT_CTX for the duration of that job. An ASYNC_WAIT_CTX should
       only be used for	one ASYNC_JOB at any one time, but can be reused after
       an ASYNC_JOB has	finished for a subsequent ASYNC_JOB. When the session
       is complete (e.g. the SSL connection is closed),	application code
       cleans up with ASYNC_WAIT_CTX_free().

       ASYNC_WAIT_CTXs can have	"wait" file descriptors	associated with	them.
       Calling ASYNC_WAIT_CTX_get_all_fds() and	passing	in a pointer to	an
       ASYNC_WAIT_CTX in the ctx parameter will	return the wait	file
       descriptors associated with that	job in *fd. The	number of file
       descriptors returned will be stored in *numfds. It is the caller's
       responsibility to ensure	that sufficient	memory has been	allocated in
       *fd to receive all the file descriptors.	Calling
       ASYNC_WAIT_CTX_get_all_fds() with a NULL	fd value will return no	file
       descriptors but will still populate *numfds. 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.

       The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if
       any fds have changed since the last call	time ASYNC_start_job()
       returned	an ASYNC_PAUSE result (or since	the ASYNC_WAIT_CTX was created
       if no ASYNC_PAUSE result	has been received). The	numaddfds and
       numdelfds parameters will be populated with the number of fds added or
       deleted respectively. *addfd and	*delfd 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	stable fd for the lifetime of the ASYNC_WAIT_CTX in order to
       reduce the "churn" of regularly changing	fds - although no guarantees
       of this are provided to applications.

       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.

       Async aware code	(e.g. engines) can get the current ASYNC_WAIT_CTX from
       the job via 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 ASYNC_WAIT_CTX_get_fd()
       and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of these functions
       requires	a key value which is unique to the async aware code.  This
       could be	any unique value but a good candidate might be the ENGINE *
       for the engine. The custom_data parameter can be	any value, and will be
       returned	in a subsequent	call to	ASYNC_WAIT_CTX_get_fd(). The
       ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a
       "cleanup" routine. This can be NULL but if provided will	automatically
       get called when the 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().

       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.

RETURN VALUES
       ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated
       ASYNC_WAIT_CTX or NULL on error.

       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.

NOTES
       On Windows platforms the	openssl/async.h	header is dependent on some of
       the types customarily made available by including windows.h. 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.

SEE ALSO
       crypto(7), ASYNC_start_job(3)

HISTORY
       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.

COPYRIGHT
       Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

       Licensed	under the OpenSSL license (the "License").  You	may not	use
       this file except	in compliance with the License.	 You can obtain	a copy
       in the file LICENSE in the source distribution or at
       <https://www.openssl.org/source/license.html>.

1.1.1d				  2019-09-10		 ASYNC_WAIT_CTX_NEW(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | NOTES | SEE ALSO | HISTORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ASYNC_WAIT_CTX_new&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help