From bc8857bf70f5428bc2f0d26162ed59e3abb11fb1 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 6 Oct 2015 13:48:43 +0100 Subject: [PATCH] More async documentation Document the libssl and command line application aspects of async. Reviewed-by: Rich Salz --- doc/apps/s_client.pod | 8 ++++++ doc/apps/s_server.pod | 8 ++++++ doc/ssl/SSL_CTX_set_mode.pod | 13 ++++++++- doc/ssl/SSL_get_async_wait_fd.pod | 45 +++++++++++++++++++++++++++++++ doc/ssl/SSL_get_error.pod | 15 +++++++++++ 5 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 doc/ssl/SSL_get_async_wait_fd.pod 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 B [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 B [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. + =back =head1 RETURN VALUES @@ -90,6 +96,11 @@ SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. =head1 SEE ALSO -L, L, L +L, L, L, L + +======= +=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 + + 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_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). + +=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, L + +=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 or L 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. 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, L +=head1 HISTORY + +SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0. + =cut -- 2.40.0