ASYNC_WAIT_CTX_new.pod 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226
  1. =pod
  2. =head1 NAME
  3. ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
  4. ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
  5. ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
  6. ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback,
  7. ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn,
  8. ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK,
  9. ASYNC_STATUS_EAGAIN
  10. - functions to manage waiting for asynchronous jobs to complete
  11. =head1 SYNOPSIS
  12. #include <openssl/async.h>
  13. #define ASYNC_STATUS_UNSUPPORTED 0
  14. #define ASYNC_STATUS_ERR 1
  15. #define ASYNC_STATUS_OK 2
  16. #define ASYNC_STATUS_EAGAIN 3
  17. typedef int (*ASYNC_callback_fn)(void *arg);
  18. ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
  19. void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
  20. int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
  21. OSSL_ASYNC_FD fd,
  22. void *custom_data,
  23. void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
  24. OSSL_ASYNC_FD, void *));
  25. int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
  26. OSSL_ASYNC_FD *fd, void **custom_data);
  27. int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
  28. size_t *numfds);
  29. int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
  30. size_t *numaddfds, OSSL_ASYNC_FD *delfd,
  31. size_t *numdelfds);
  32. int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
  33. int ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx,
  34. ASYNC_callback_fn callback,
  35. void *callback_arg);
  36. int ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx,
  37. ASYNC_callback_fn *callback,
  38. void **callback_arg);
  39. int ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status);
  40. int ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx);
  41. =head1 DESCRIPTION
  42. For an overview of how asynchronous operations are implemented in OpenSSL see
  43. L<ASYNC_start_job(3)>. An B<ASYNC_WAIT_CTX> object represents an asynchronous
  44. "session", i.e. a related set of crypto operations. For example in SSL terms
  45. this would have a one-to-one correspondence with an SSL connection.
  46. Application code must create an B<ASYNC_WAIT_CTX> using the ASYNC_WAIT_CTX_new()
  47. function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
  48. the job is started it is associated with the B<ASYNC_WAIT_CTX> for the duration
  49. of that job. An B<ASYNC_WAIT_CTX> should only be used for one B<ASYNC_JOB> at
  50. any one time, but can be reused after an B<ASYNC_JOB> has finished for a
  51. subsequent B<ASYNC_JOB>. When the session is complete (e.g. the SSL connection
  52. is closed), application code cleans up with ASYNC_WAIT_CTX_free().
  53. B<ASYNC_WAIT_CTX>s can have "wait" file descriptors associated with them.
  54. Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an
  55. B<ASYNC_WAIT_CTX> in the I<ctx> parameter will return the wait file descriptors
  56. associated with that job in I<*fd>. The number of file descriptors returned will
  57. be stored in I<*numfds>. It is the caller's responsibility to ensure that
  58. sufficient memory has been allocated in I<*fd> to receive all the file
  59. descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL I<fd> value will
  60. return no file descriptors but will still populate I<*numfds>. Therefore,
  61. application code is typically expected to call this function twice: once to get
  62. the number of fds, and then again when sufficient memory has been allocated. If
  63. only one asynchronous engine is being used then normally this call will only
  64. ever return one fd. If multiple asynchronous engines are being used then more
  65. could be returned.
  66. The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds
  67. have changed since the last call time ASYNC_start_job() returned B<ASYNC_PAUSE>
  68. (or since the B<ASYNC_WAIT_CTX> was created if no B<ASYNC_PAUSE> result has
  69. been received). The I<numaddfds> and I<numdelfds> parameters will be populated
  70. with the number of fds added or deleted respectively. I<*addfd> and I<*delfd>
  71. will be populated with the list of added and deleted fds respectively. Similarly
  72. to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
  73. NULL then the caller is responsible for ensuring sufficient memory is allocated.
  74. Implementors of async aware code (e.g. engines) are encouraged to return a
  75. stable fd for the lifetime of the B<ASYNC_WAIT_CTX> in order to reduce the
  76. "churn" of regularly changing fds - although no guarantees of this are provided
  77. to applications.
  78. Applications can wait for the file descriptor to be ready for "read" using a
  79. system function call such as select or poll (being ready for "read" indicates
  80. that the job should be resumed). If no file descriptor is made available then an
  81. application will have to periodically "poll" the job by attempting to restart it
  82. to see if it is ready to continue.
  83. Async aware code (e.g. engines) can get the current B<ASYNC_WAIT_CTX> from the
  84. job via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for
  85. waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done
  86. by an engine immediately prior to calling ASYNC_pause_job() and not by end user
  87. code. An existing association with a file descriptor can be obtained using
  88. ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
  89. these functions requires a I<key> value which is unique to the async aware
  90. code. This could be any unique value but a good candidate might be the
  91. B<ENGINE *> for the engine. The I<custom_data> parameter can be any value, and
  92. will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
  93. ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
  94. routine. This can be NULL but if provided will automatically get called when
  95. the B<ASYNC_WAIT_CTX> is freed, and gives the engine the opportunity to close
  96. the fd or any other resources. Note: The "cleanup" routine does not get called
  97. if the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
  98. An example of typical usage might be an async capable engine. User code would
  99. initiate cryptographic operations. The engine would initiate those operations
  100. asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
  101. ASYNC_pause_job() to return control to the user code. The user code can then
  102. perform other tasks or wait for the job to be ready by calling "select" or other
  103. similar function on the wait file descriptor. The engine can signal to the user
  104. code that the job should be resumed by making the wait file descriptor
  105. "readable". Once resumed the engine should clear the wake signal on the wait
  106. file descriptor.
  107. As well as a file descriptor, user code may also be notified via a callback. The
  108. callback and data pointers are stored within the B<ASYNC_WAIT_CTX> along with an
  109. additional status field that can be used for the notification of retries from an
  110. engine. This additional method can be used when the user thinks that a file
  111. descriptor is too costly in terms of CPU cycles or in some context where a file
  112. descriptor is not appropriate.
  113. ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The
  114. callback will be called to notify user code when an engine completes a
  115. cryptography operation. It is a requirement that the callback function is small
  116. and nonblocking as it will be run in the context of a polling mechanism or an
  117. interrupt.
  118. ASYNC_WAIT_CTX_get_callback() returns the callback set in the B<ASYNC_WAIT_CTX>
  119. structure.
  120. ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status.
  121. The possible status values are the following:
  122. =over 4
  123. =item B<ASYNC_STATUS_UNSUPPORTED>
  124. The engine does not support the callback mechanism. This is the default value.
  125. The engine must call ASYNC_WAIT_CTX_set_status() to set the status to some value
  126. other than B<ASYNC_STATUS_UNSUPPORTED> if it intends to enable the callback
  127. mechanism.
  128. =item B<ASYNC_STATUS_ERR>
  129. The engine has a fatal problem with this request. The user code should clean up
  130. this session.
  131. =item B<ASYNC_STATUS_OK>
  132. The request has been successfully submitted.
  133. =item B<ASYNC_STATUS_EAGAIN>
  134. The engine has some problem which will be recovered soon, such as a buffer is
  135. full, so user code should resume the job.
  136. =back
  137. ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value.
  138. If the status is any value other than B<ASYNC_STATUS_OK> then the user code
  139. should not expect to receive a callback from the engine even if one has been
  140. set.
  141. An example of the usage of the callback method might be the following. User
  142. code would initiate cryptographic operations, and the engine code would dispatch
  143. this operation to hardware, and if the dispatch is successful, then the engine
  144. code would call ASYNC_pause_job() to return control to the user code. After
  145. that, user code can perform other tasks. When the hardware completes the
  146. operation, normally it is detected by a polling function or an interrupt, as the
  147. user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously,
  148. then the registered callback will be called.
  149. =head1 RETURN VALUES
  150. ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated B<ASYNC_WAIT_CTX>
  151. or NULL on error.
  152. ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
  153. ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd,
  154. ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and
  155. ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error.
  156. ASYNC_WAIT_CTX_get_status() returns the engine status.
  157. =head1 NOTES
  158. On Windows platforms the openssl/async.h header is dependent on some
  159. of the types customarily made available by including windows.h. The
  160. application developer is likely to require control over when the latter
  161. is included, commonly as one of the first included headers. Therefore,
  162. it is defined as an application developer's responsibility to include
  163. windows.h prior to async.h.
  164. =head1 SEE ALSO
  165. L<crypto(7)>, L<ASYNC_start_job(3)>
  166. =head1 HISTORY
  167. ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(), ASYNC_WAIT_CTX_set_wait_fd(),
  168. ASYNC_WAIT_CTX_get_fd(), ASYNC_WAIT_CTX_get_all_fds(),
  169. ASYNC_WAIT_CTX_get_changed_fds() and ASYNC_WAIT_CTX_clear_fd()
  170. were added in OpenSSL 1.1.0.
  171. ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(),
  172. ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status()
  173. were added in OpenSSL 3.0.
  174. =head1 COPYRIGHT
  175. Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
  176. Licensed under the Apache License 2.0 (the "License"). You may not use
  177. this file except in compliance with the License. You can obtain a copy
  178. in the file LICENSE in the source distribution or at
  179. L<https://www.openssl.org/source/license.html>.
  180. =cut