Doc fixes

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24971)

diff --git a/doc/man3/SSL_CTX_set_domain_flags.pod b/doc/man3/SSL_CTX_set_domain_flags.pod
index 8535f9582144ffce92872391eef2a16d47bffa13..de8430a52315de8b126b307c875abfda8d53ea4c 100644 (file)
--- a/doc/man3/SSL_CTX_set_domain_flags.pod
+++ b/doc/man3/SSL_CTX_set_domain_flags.pod
@@ -45,10 +45,16 @@ Specifying this flag configures the Single-Threaded Concurrency Model (SCM).
 Speciyfing this flag configures the Contentive Concurrency Model (CCM) (unless
 B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> is also specified).
 
+If OpenSSL was built without thread support, this is identical to
+B<SSL_DOMAIN_FLAG_SINGLE_THREAD>.
+
 =item B<SSL_DOMAIN_FLAG_THREAD_ASSISTED>
 
 Specifying this flag configures the Thread-Assisted Concurrency Modle (TACM).
-It implies B<SSL_DOMAIN_FLAG_MULTI_THREAD>.
+It implies B<SSL_DOMAIN_FLAG_MULTI_THREAD> and B<SSL_DOMAIN_FLAG_BLOCKING>.
+
+This concurrency model is not available if OpenSSL was built without thread
+support, in which case attempting to configure it will result in an error.
 
 =item B<SSL_DOMAIN_FLAG_BLOCKING>
 

diff --git a/doc/man3/SSL_new_domain.pod b/doc/man3/SSL_new_domain.pod
index 41c3f391b7ec13ce71ac6926dd1e856aa31f19e0..5ffb561bb8d50291cc8d159451e65afc6e713d77 100644 (file)
--- a/doc/man3/SSL_new_domain.pod
+++ b/doc/man3/SSL_new_domain.pod
@@ -26,7 +26,8 @@ The I<flags> argument to SSL_new_domain() accepts a set of domain flags. If the
 I<flags> argument to SSL_new_domain() does not specify one of the flags
 B<SSL_DOMAIN_FLAG_SINGLE_THREAD>, B<SSL_DOMAIN_FLAG_MULTI_THREAD> or
 B<SSL_DOMAIN_FLAG_THREAD_ASSISTED>, the domain flags configured on the
-B<SSL_CTX> are used as a default. Otherwise, the domain flags in I<domain_flags>
+B<SSL_CTX> are inherited as a default and any other flags in I<flags> are added
+to the set of inherited flags. Otherwise, the domain flags in I<flags>
 are used. See L<SSL_CTX_set_domain_flags(3)> for details of the available domain
 flags and how they can be configured on a B<SSL_CTX>.
 

diff --git a/doc/man7/openssl-quic-concurrency.pod b/doc/man7/openssl-quic-concurrency.pod
index ef79eff812790916caa3a01027d9fd1dc8cc3a03..e590adaae7c13a26fab1cdb1f065f391e3ebf126 100644 (file)
--- a/doc/man7/openssl-quic-concurrency.pod
+++ b/doc/man7/openssl-quic-concurrency.pod
@@ -24,8 +24,9 @@ implicitly by calling L<SSL_new(3)> or L<SSL_new_listener(3)>:
 
 =item
 
-An explicit QUIC domain is created by and visible to the application and has
-other QUIC SSL objects created underneath it, such as listeners or connections.
+An explicit QUIC domain is created by and visible to the application as a QUIC
+domain SSL object and has other QUIC SSL objects created underneath it, such as
+listeners or connections.
 
 =item
 
@@ -128,19 +129,21 @@ calls, where application-level I/O calls (for example, to L<SSL_read_ex(3)> or
 L<SSL_write_ex(3)> on a QUIC stream SSL object) block until the request can be
 serviced. This includes the use of L<SSL_poll(3)> in a blocking fashion.
 
-Supporting blocking API calls reliably requires the creation of additional OS
-resources such as internal file descriptors to allow threads to be woken when
-necessary. This creation of internal OS resources is optional and may need to be
-explicitly requested by an application depending on the chosen concurrency
-model. If this functionality is disabled, depending on the chosen concurrency
-model, blocking API calls may not be available and calls to
-L<SSL_set_blocking_mode(3)> attempting to enable blocking mode will fail.
+Supporting blocking API calls reliably with multi-threaded usage requires the
+creation of additional OS resources such as internal file descriptors to allow
+threads to be woken when necessary. This creation of internal OS resources is
+optional and may need to be explicitly requested by an application depending on
+the chosen concurrency model. If this functionality is disabled, depending on
+the chosen concurrency model, blocking API calls may not be available and calls
+to L<SSL_set_blocking_mode(3)> attempting to enable blocking mode may fail,
+notwithstanding the following section.
 
 =head2 Legacy Blocking Support Compatibility
 
 OpenSSL 3.2 and 3.3 contained a buggy implementation of blocking QUIC I/O calls
 which is only reliable under single-threaded usage. This functionality is always
-available in the Single-Threaded Concurrency Model, where it works reliably.
+available in the Single-Threaded Concurrency Model (SCM), where it works
+reliably.
 
 For compatibility reasons, this functionality is also available under the
 default concurrency model if the application does not explicitly specify a
@@ -225,10 +228,13 @@ created.
 
 =head2 Default Behaviour
 
-If none of the above flags are provided to L<SSL_new_domain(3)> or another
-function which can accept the above flags, the default concurrency model set on
-the B<SSL_CTX> is used. This default can be set and get using
-L<SSL_CTX_set_domain_flags(3)> and L<SSL_CTX_get_domain_flags(3)>.
+If none of B<SSL_DOMAIN_FLAG_SINGLE_THREAD>, B<SSL_DOMAIN_FLAG_MULTI_THREAD> or
+B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> are provided to L<SSL_new_domain(3)> or
+another constructor function which can accept the above flags, the default
+concurrency model set on the B<SSL_CTX> is used. This default can be set and get
+using L<SSL_CTX_set_domain_flags(3)> and L<SSL_CTX_get_domain_flags(3)>. Any
+additional flags provided (for example, B<SSL_DOMAIN_FLAG_BLOCCKING>) are added
+to the set of inherited flags.
 
 The default concurrency model set on a newly created B<SSL_CTX> is determined as
 follows:
@@ -250,7 +256,7 @@ flag.
 =item *
 
 Otherwise, if an B<SSL_METHOD> of L<OSSL_QUIC_client_method(3)> is used, the
-Contentive Concurrency Model (CCM) is used with th
+Contentive Concurrency Model (CCM) is used with the
 B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING> flag.
 
 =item *
@@ -285,6 +291,14 @@ The internal consumption by OpenSSL of mutexes, condition variables, spin locks
 or other similar thread synchronisation primitives is unspecified under all
 concurrency models.
 
+The internal consumption by OpenSSL of threads is unspecified under the
+Thread-Assisted Concurrency Model.
+
+The internal consumption by OpenSSL of sockets, socket-like OS handles or file
+descriptors, or other resources as needed to support inter-thread notification,
+is unspecified under the Thread-Assisted Concurrency Model or when using
+B<SSL_DOMAIN_FLAG_BLOCKING>.
+
 =head1 BEHAVIOUR OF SSL OBJECTS
 
 A QUIC SSL object has blocking mode enabled by default where B<all> of the