]>
Commit | Line | Data |
---|---|---|
9f5a87fd PY |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_async_callback, | |
6 | SSL_CTX_set_async_callback_arg, | |
7 | SSL_set_async_callback, | |
8 | SSL_set_async_callback_arg, | |
9 | SSL_get_async_status, | |
10 | SSL_async_callback_fn | |
11 | - manage asynchronous operations | |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
bb82531f | 15 | =for openssl multiple includes |
9f5a87fd PY |
16 | |
17 | #include <openssl/ssl.h> | |
18 | ||
19 | typedef int (*SSL_async_callback_fn)(SSL *s, void *arg); | |
20 | int SSL_CTX_set_async_callback(SSL_CTX *ctx, SSL_async_callback_fn callback); | |
21 | int SSL_CTX_set_async_callback_arg(SSL_CTX *ctx, void *arg); | |
22 | int SSL_set_async_callback(SSL *s, SSL_async_callback_fn callback); | |
23 | int SSL_set_async_callback_arg(SSL *s, void *arg); | |
24 | int SSL_get_async_status(SSL *s, int *status); | |
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
dfe1752c RL |
28 | SSL_CTX_set_async_callback() sets an asynchronous callback function. All B<SSL> |
29 | objects generated based on this B<SSL_CTX> will get this callback. If an engine | |
9f5a87fd | 30 | supports the callback mechanism, it will be automatically called if |
dfe1752c | 31 | B<SSL_MODE_ASYNC> has been set and an asynchronous capable engine completes a |
9f5a87fd PY |
32 | cryptography operation to notify the application to resume the paused work flow. |
33 | ||
34 | SSL_CTX_set_async_callback_arg() sets the callback argument. | |
35 | ||
36 | SSL_set_async_callback() allows an application to set a callback in an | |
dfe1752c | 37 | asynchronous B<SSL> object, so that when an engine completes a cryptography |
9f5a87fd PY |
38 | operation, the callback will be called to notify the application to resume the |
39 | paused work flow. | |
40 | ||
dfe1752c RL |
41 | SSL_set_async_callback_arg() sets an argument for the B<SSL> object when the |
42 | above callback is called. | |
9f5a87fd PY |
43 | |
44 | SSL_get_async_status() returns the engine status. This function facilitates the | |
45 | communication from the engine to the application. During an SSL session, | |
46 | cryptographic operations are dispatched to an engine. The engine status is very | |
47 | useful for an application to know if the operation has been successfully | |
48 | dispatched. If the engine does not support this additional callback method, | |
dfe1752c RL |
49 | B<ASYNC_STATUS_UNSUPPORTED> will be returned. See ASYNC_WAIT_CTX_set_status() |
50 | for a description of all of the status values. | |
9f5a87fd | 51 | |
dfe1752c RL |
52 | An example of the above functions would be the following: |
53 | ||
54 | =over 4 | |
55 | ||
56 | =item 1. | |
57 | ||
58 | Application sets the async callback and callback data on an SSL connection | |
9f5a87fd | 59 | by calling SSL_set_async_callback(). |
dfe1752c RL |
60 | |
61 | =item 2. | |
62 | ||
63 | Application sets B<SSL_MODE_ASYNC> and makes an asynchronous SSL call | |
64 | ||
65 | =item 3. | |
66 | ||
67 | OpenSSL submits the asynchronous request to the engine. If a retry occurs at | |
68 | this point then the status within the B<ASYNC_WAIT_CTX> would be set and the | |
69 | async callback function would be called (goto Step 7). | |
70 | ||
71 | =item 4. | |
72 | ||
73 | The OpenSSL engine pauses the current job and returns, so that the | |
9f5a87fd | 74 | application can continue processing other connections. |
dfe1752c RL |
75 | |
76 | =item 5. | |
77 | ||
78 | At a future point in time (probably via a polling mechanism or via an | |
9f5a87fd PY |
79 | interrupt) the engine will become aware that the asynchronous request has |
80 | finished processing. | |
dfe1752c RL |
81 | |
82 | =item 6. | |
83 | ||
84 | The engine will call the application's callback passing the callback data as | |
9f5a87fd | 85 | a parameter. |
dfe1752c RL |
86 | |
87 | =item 7. | |
88 | ||
89 | The callback function should then run. Note: it is a requirement that the | |
9f5a87fd PY |
90 | callback function is small and non-blocking as it will be run in the context of |
91 | a polling mechanism or an interrupt. | |
dfe1752c RL |
92 | |
93 | =item 8. | |
94 | ||
95 | It is the application's responsibility via the callback function to schedule | |
9f5a87fd | 96 | recalling the OpenSSL asynchronous function and to continue processing. |
dfe1752c RL |
97 | |
98 | =item 9. | |
99 | ||
100 | The callback function has the option to check the status returned via | |
9f5a87fd PY |
101 | SSL_get_async_status() to determine whether a retry happened instead of the |
102 | request being submitted, allowing different processing if required. | |
103 | ||
dfe1752c RL |
104 | =back |
105 | ||
9f5a87fd PY |
106 | =head1 RETURN VALUES |
107 | ||
108 | SSL_CTX_set_async_callback(), SSL_set_async_callback(), | |
109 | SSL_CTX_set_async_callback_arg(), SSL_CTX_set_async_callback_arg() and | |
110 | SSL_get_async_status() return 1 on success or 0 on error. | |
111 | ||
98ca37e4 RS |
112 | =head1 SEE ALSO |
113 | ||
114 | L<ssl(7)> | |
115 | ||
9f5a87fd PY |
116 | =head1 HISTORY |
117 | ||
118 | SSL_CTX_set_async_callback(), SSL_CTX_set_async_callback_arg(), | |
119 | SSL_set_async_callback(), SSL_set_async_callback_arg() and | |
4674aaf4 | 120 | SSL_get_async_status() were first added to OpenSSL 3.0. |
9f5a87fd PY |
121 | |
122 | =head1 COPYRIGHT | |
123 | ||
454afd98 | 124 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
9f5a87fd | 125 | |
a6ed19dc | 126 | Licensed under the Apache License 2.0 (the "License"). You may not use |
9f5a87fd PY |
127 | this file except in compliance with the License. You can obtain a copy |
128 | in the file LICENSE in the source distribution or at | |
129 | L<https://www.openssl.org/source/license.html>. | |
130 | ||
131 | =cut |