Skip to content

Commit

Permalink
Doc fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
hlandau committed Apr 29, 2024
1 parent 8555f1f commit d7ed50e
Show file tree
Hide file tree
Showing 3 changed files with 38 additions and 17 deletions.
8 changes: 7 additions & 1 deletion doc/man3/SSL_CTX_set_domain_flags.pod
Expand Up @@ -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>

Expand Down
3 changes: 2 additions & 1 deletion doc/man3/SSL_new_domain.pod
Expand Up @@ -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>.

Expand Down
44 changes: 29 additions & 15 deletions doc/man7/openssl-quic-concurrency.pod
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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 *
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit d7ed50e

Please sign in to comment.