Document the libssl and command line application aspects of async.
Reviewed-by: Rich Salz <rsalz@openssl.org>
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-fallback_scsv>]
+[B<-async>]
[B<-bugs>]
[B<-cipher cipherlist>]
[B<-serverpref>]
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
[B<-dtls1>]
[B<-dtls1_2>]
[B<-listen>]
+[B<-async>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_dhe>]
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
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
=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
--- /dev/null
+=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
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
L<ssl(3)>, L<err(3)>
+=head1 HISTORY
+
+SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
+
=cut