diff options
author | Matt Caswell <matt@openssl.org> | 2015-10-06 13:48:43 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2015-11-20 23:34:35 +0000 |
commit | bc8857bf70f5428bc2f0d26162ed59e3abb11fb1 (patch) | |
tree | e6249d68707efd38cc5c74c669c7555dc928959c | |
parent | 636ca4ff64d0c512b5f9e01ddc644e5f7661849e (diff) |
More async documentation
Document the libssl and command line application aspects of async.
Reviewed-by: Rich Salz <rsalz@openssl.org>
-rw-r--r-- | doc/apps/s_client.pod | 8 | ||||
-rw-r--r-- | doc/apps/s_server.pod | 8 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_mode.pod | 13 | ||||
-rw-r--r-- | doc/ssl/SSL_get_async_wait_fd.pod | 45 | ||||
-rw-r--r-- | doc/ssl/SSL_get_error.pod | 15 |
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 |