From: Hugo Landau Date: Mon, 29 Apr 2024 09:52:32 +0000 (+0100) Subject: Doc fixes X-Git-Tag: openssl-3.5.0-alpha1~366 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=89fa427504b9c19e62fc101915a2df0d4b978dc2;p=thirdparty%2Fopenssl.git Doc fixes Reviewed-by: Matt Caswell Reviewed-by: Neil Horman (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 8535f958214..de8430a5231 100644 --- 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 is also specified). +If OpenSSL was built without thread support, this is identical to +B. + =item B Specifying this flag configures the Thread-Assisted Concurrency Modle (TACM). -It implies B. +It implies B and B. + +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 diff --git a/doc/man3/SSL_new_domain.pod b/doc/man3/SSL_new_domain.pod index 41c3f391b7e..5ffb561bb8d 100644 --- a/doc/man3/SSL_new_domain.pod +++ b/doc/man3/SSL_new_domain.pod @@ -26,7 +26,8 @@ The I argument to SSL_new_domain() accepts a set of domain flags. If the I argument to SSL_new_domain() does not specify one of the flags B, B or B, the domain flags configured on the -B are used as a default. Otherwise, the domain flags in I +B are inherited as a default and any other flags in I are added +to the set of inherited flags. Otherwise, the domain flags in I are used. See L for details of the available domain flags and how they can be configured on a B. diff --git a/doc/man7/openssl-quic-concurrency.pod b/doc/man7/openssl-quic-concurrency.pod index ef79eff8127..e590adaae7c 100644 --- a/doc/man7/openssl-quic-concurrency.pod +++ b/doc/man7/openssl-quic-concurrency.pod @@ -24,8 +24,9 @@ implicitly by calling L or L: =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 or L on a QUIC stream SSL object) block until the request can be serviced. This includes the use of L 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 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 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 or another -function which can accept the above flags, the default concurrency model set on -the B is used. This default can be set and get using -L and L. +If none of B, B or +B are provided to L or +another constructor function which can accept the above flags, the default +concurrency model set on the B is used. This default can be set and get +using L and L. Any +additional flags provided (for example, B) are added +to the set of inherited flags. The default concurrency model set on a newly created B is determined as follows: @@ -250,7 +256,7 @@ flag. =item * Otherwise, if an B of L is used, the -Contentive Concurrency Model (CCM) is used with th +Contentive Concurrency Model (CCM) is used with the B 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. + =head1 BEHAVIOUR OF SSL OBJECTS A QUIC SSL object has blocking mode enabled by default where B of the