More async documentation

Document the libssl and command line application aspects of async.

Reviewed-by: Rich Salz <rsalz@openssl.org>

5 files changed, 88 insertions, 1 deletions

diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod
index 6468999b25..afcba281e6 100644
--- a/doc/apps/s_client.pod
+++ b/doc/apps/s_client.pod
@@ -68,6 +68,7 @@ B<openssl> B<s_client>
 [B<-no_tls1_1>]
 [B<-no_tls1_2>]
 [B<-fallback_scsv>]
+[B<-async>]
 [B<-bugs>]
 [B<-cipher cipherlist>]
 [B<-serverpref>]
@@ -277,6 +278,13 @@ work if TLS is turned off.
 
 Send TLS_FALLBACK_SCSV in the ClientHello.
 
+=item B<-async>
+
+switch on asynchronous mode. Cryptographic operations will be performed
+asynchronously. This will only have an effect if an asynchronous capable engine
+is also used via the B<-engine> option. For test purposes the dummy async engine
+(dasync) can be used (if available).
+
 =item B<-bugs>
 
 there are several known bug in SSL and TLS implementations. Adding this
diff --git a/doc/apps/s_server.pod b/doc/apps/s_server.pod
index cd8a3ef747..706e039b5a 100644
--- a/doc/apps/s_server.pod
+++ b/doc/apps/s_server.pod
@@ -73,6 +73,7 @@ B<openssl> B<s_server>
 [B<-dtls1>]
 [B<-dtls1_2>]
 [B<-listen>]
+[B<-async>]
 [B<-no_ssl3>]
 [B<-no_tls1>]
 [B<-no_dhe>]
@@ -312,6 +313,13 @@ them or not. Any without a cookie will be responded to with a
 HelloVerifyRequest. If a ClientHello with a cookie is received then s_server
 will connect to that peer and complete the handshake.
 
+=item B<-async>
+
+switch on asynchronous mode. Cryptographic operations will be performed
+asynchronously. This will only have an effect if an asynchronous capable engine
+is also used via the B<-engine> option. For test purposes the dummy async engine
+(dasync) can be used (if available).
+
 =item B<-bugs>
 
 there are several known bug in SSL and TLS implementations. Adding this
diff --git a/doc/ssl/SSL_CTX_set_mode.pod b/doc/ssl/SSL_CTX_set_mode.pod
index 56f732faad..341da16fb9 100644
--- a/doc/ssl/SSL_CTX_set_mode.pod
+++ b/doc/ssl/SSL_CTX_set_mode.pod
@@ -79,6 +79,12 @@ DO NOT ENABLE THIS if your application attempts a normal handshake.
 Only use this in explicit fallback retries, following the guidance
 in draft-ietf-tls-downgrade-scsv-00.
 
+=item SSL_MODE_ASYNC
+
+Enable asynchronous processing. TLS I/O operations may indicate a retry with
+SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is
+used to perform cryptographic operations. See L<SSL_get_error(3)>.
+
 =back
 
 =head1 RETURN VALUES
@@ -90,6 +96,11 @@ SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
 
 =head1 SEE ALSO
 
-L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>
+L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)>
+
+=======
+=head1 HISTORY
+
+SSL_MODE_ASYNC was first added to OpenSSL 1.1.0.
 
 =cut
diff --git a/doc/ssl/SSL_get_async_wait_fd.pod b/doc/ssl/SSL_get_async_wait_fd.pod
new file mode 100644
index 0000000000..da7617b2de
--- /dev/null
+++ b/doc/ssl/SSL_get_async_wait_fd.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+SSL_waiting_for_async, SSL_get_async_wait_fd - manage asynchronous operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_waiting_for_async(SSL *s);
+ int SSL_get_async_wait_fd(SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_waiting_for_async() determines whether an SSL connection is currently
+waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in
+L<SSL_CTX_set_mode(3)>).
+
+SSL_get_async_wait_fd() returns a file descriptor which can be used in a call to
+select() or poll() to determine whether the current asynchronous operation has
+completed or not. A completed operation will result in data appearing as
+available on the file descriptor (no actual data should be read from the file
+descriptor). This function should only be called if the SSL object is currently
+waiting for asynchronous work to complete (i.e. SSL_ERROR_WANT_ASYNC has been
+received - see L<SSL_get_error(3)>).
+
+=head1 RETURN VALUES
+
+SSL_waiting_for_async() will return 1 if the current SSL operation is waiting
+for an async operation to complete and 0 otherwise.
+
+SSL_get_async_wait_fd() will return a file descriptor that can be used in a call
+to select() or poll() to wait for asynchronous work to complete, or -1 on error.
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)>
+
+=head1 HISTORY
+
+SSL_waiting_for_async() and SSL_get_async_wait_fd() were first added to
+OpenSSL 1.1.0
+
+=cut
diff --git a/doc/ssl/SSL_get_error.pod b/doc/ssl/SSL_get_error.pod
index d52c27d8fe..d950fa3ed9 100644
--- a/doc/ssl/SSL_get_error.pod
+++ b/doc/ssl/SSL_get_error.pod
@@ -87,6 +87,17 @@ SSL_CTX_set_client_cert_cb() has asked to be called again.
 The TLS/SSL I/O function should be called again later.
 Details depend on the application.
 
+=item SSL_ERROR_WANT_ASYNC
+
+The operation did not complete because an asynchronous engine is still
+processing data. This will only occur if the mode has been set to SSL_MODE_ASYNC
+using L<SSL_CTX_set_mode(3)> or L<SSL_set_mode(3)> and an asynchronous capable
+engine is being used. An application can determine whether the engine has
+completed its processing using select() or poll() on the asynchronous wait file
+descriptor. This file descriptor is available by calling
+L<SSL_get_async_wait_fd(3)>. The TLS/SSL I/O function should be called again
+later.
+
 =item SSL_ERROR_SYSCALL
 
 Some I/O error occurred.  The OpenSSL error queue may contain more
@@ -107,4 +118,8 @@ OpenSSL error queue contains more information on the error.
 
 L<ssl(3)>, L<err(3)>
 
+=head1 HISTORY
+
+SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
+
 =cut