Commit bc8857bf authored by Matt Caswell's avatar Matt Caswell
Browse files

More async documentation 



Document the libssl and command line application aspects of async.

Reviewed-by: default avatarRich Salz <rsalz@openssl.org>
parent 636ca4ff

doc/apps/s_client.pod

+8 −0
Original line number Diff line number Diff line
@@ -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

doc/apps/s_server.pod

+8 −0
Original line number Diff line number Diff line
@@ -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

doc/ssl/SSL_CTX_set_mode.pod

+12 −1
Original line number Diff line number Diff line
@@ -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

doc/ssl/SSL_get_async_wait_fd.pod

0 → 100644
+45 −0
Original line number Diff line number Diff line 
=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

doc/ssl/SSL_get_error.pod

+15 −0
Original line number Diff line number Diff line
@@ -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