[openssl-dev] Adding async support

[Matt Caswell]

On 07/10/15 21:44, Dmitry Belyavsky wrote:
> Dear Matt, 
> 
> On Wed, Oct 7, 2015 at 4:43 PM, Matt Caswell <matt at openssl.org
> <mailto:matt at openssl.org>> wrote:
> 
> 
> 
>     On 07/10/15 14:29, Viktor Dukhovni wrote:
>     >
>     > Should applications generally enable async mode because that might
>     > be beneficial down the road?  Or is this just for exotic hardware
>     > not likely to be seen in most environments?
> 
>     It will only be helpful if you have an engine capable of supporting
>     async. I can't really answer the question because I don't know how
>     common this will be. My hope is that this will become relatively common.
>     I have been toying with the idea of creating a multi-threaded async
>     engine where the engine manages a pool of threads to offload async work
>     to which would then offer true async support even if you don't have
>     specialist hardware.
> 
> 
> If we have an engine executing long crypto operations, how can we adopt
> the engine and software using this engine to process them asynchronously? 

The engine needs to have a way of offloading the work to "something
else" so that it can come back and pick up the results later. Typically
for an engine this would mean some external hardware, but as I suggested
above it could be done using threads.

>From an engine perspective the work would be:
- Receive a request to do some crypto work in the normal way via the
engine API.
- Offload the work to "something else"
- Call the new API function ASYNC_pause_job(). This will return control
back to the calling application.
- At sometime later, preferably when the application knows the work has
completed (* see below), the application will resume the async job. From
an engine perspective this just appears as the ASYNC_pause_job()
function call returning - so it just continues where it left off
- The engine should verify that the work offloaded to "something else"
has completed.
- If not it just calls ASYNC_pause_job() again as before.
- If it has completed then it collects the results and returns them back
in the normal way for an engine

>From an application perspective it depends whether it is using libcrypto
directly, or whether it is using libssl.

If libssl then:
- the application essentially operates as normal
- additionally it must call either SSL_CTX_set_mode() or SSL_set_mode to
set the SSL_ASYNC_MODE
- In any call to SSL_read/SSL_write/SSL_accept/SSL_connect etc, it must
be prepared to handle an SSL_ERROR_WANT_ASYNC response. This works in
essentially the same way as SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE,
i.e sometime later (* see below) it recalls
SSL_read/SSL_write/SSL_accept/SSL_connect and the async job is resumed.

If using libcrypto then:
- the application must determine which crypto operations it wants to
perform asynchronously. Those operations should be wrapped in an
application defined function.
- the application initiates the async job by calling ASYNC_start_job and
passing in a pointer to the function to be started as a job.
- from an engine perspective it will work in exactly the same way as for
libssl initiated crypto work.
- ASYNC_start_job may return with an ASYNC_PAUSE response. The
application can go off and do other work, and then resume the job at a
later time by recalling ASYNC_start_job.


So the next question is how does the application know when it is ok to
resume a job? There are two basic models:

- Event based...essentially the engine signals to the application that
the results are ready for collection
- Polling...in this model the application will have to periodically
restart the job to see if it is ready to be continued or not

There are API calls available for the event based model. See
ASYNC_wake(), ASYNC_clear_wake(), ASYNC_get_wait_fd(), and
SSL_get_async_wait_fd() in the documentation links I sent out previously.

There is some example code in the ASYNC_start_job() documentation. You
can also look at the source code for the dummy async engine.

Matt