diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/openssl-quic-concurrency.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/openssl-quic-concurrency.7 | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man7/openssl-quic-concurrency.7 b/secure/lib/libcrypto/man/man7/openssl-quic-concurrency.7 new file mode 100644 index 000000000000..723d31ec19e8 --- /dev/null +++ b/secure/lib/libcrypto/man/man7/openssl-quic-concurrency.7 @@ -0,0 +1,316 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OPENSSL-QUIC-CONCURRENCY 7ossl" +.TH OPENSSL-QUIC-CONCURRENCY 7ossl 2025-07-01 3.5.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-quic\-concurrency \- OpenSSL QUIC Concurrency Model +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A QUIC domain is a group of QUIC resources such as listeners (see +\&\fBSSL_new_listener\fR\|(3)) and connections which share common event processing +resources, such as internal pollers, timers and locks. All usage of OpenSSL QUIC +happens inside a QUIC domain. +.PP +These resources can be accessed and used concurrently depending on the +circumstances. This man page discusses the available concurrency models and how +they can be used. +.SH "EXPLICIT AND IMPLICIT QUIC DOMAINS" +.IX Header "EXPLICIT AND IMPLICIT QUIC DOMAINS" +A QUIC domain is instantiated either explicitly (\fBSSL_new_domain\fR\|(3)) or +implicitly by calling \fBSSL_new\fR\|(3) or \fBSSL_new_listener\fR\|(3): +.IP \(bu 4 +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. +.IP \(bu 4 +An implicit QUIC domain is one which is created internally due to the direct +creation of a QUIC connection or listener SSL object; the application does not +explicitly create a QUIC domain SSL object and never directly references the +domain. +.PP +Explicit creation of a QUIC domain provides the greatest level of control for an +application. Applications can use an implicit QUIC domain for ease of use and to +avoid needing to create a separate QUIC domain SSL object. +.PP +Regardless of whether a QUIC domain is explicitly created, the internal +processing model is the same and the application must choose an appropriate +concurrency model as discussed below. +.SH "CONCURRENCY MODELS" +.IX Header "CONCURRENCY MODELS" +The OpenSSL QUIC implementation supports multiple concurrency models to support +a wide variety of usage scenarios. +.PP +The available concurrency models are as follows: +.IP \(bu 4 +The \fBSingle-Threaded Concurrency Model (SCM)\fR, which supports only +application-synchronised single-threaded usage. +.IP \(bu 4 +The \fBContentive Concurrency Model (CCM)\fR, which supports multi-threaded usage. +.IP \(bu 4 +The \fBThread-Assisted Concurrency Model (TACM)\fR, which also supports +multi-threaded usage and provides assistance to an application for handling QUIC +timer events. +.PP +The merits of these models are as follows: +.IP \(bu 4 +The \fBSingle-Threaded Concurrency Model (SCM)\fR performs no locking or +synchronisation. It is entirely up to the application to synchronise access to +the QUIC domain and its subsidiary SSL objects. +.Sp +This concurrency model is also useful for an application which wants to use the +OpenSSL QUIC implementation as a pure state machine. +.IP \(bu 4 +The \fBContentive Concurrency Model (CCM)\fR performs automatic locking when making +API calls to SSL objects in a QUIC domain. This provides automatic +synchronisation for multi-threaded usage of QUIC objects. For example, different +QUIC stream SSL objects in the same QUIC connection can be safely accessed from +different threads. +.Sp +This concurrency model adds the overhead of locking over the Single-Threaded +Concurrency Model in order to support multi-threaded usage, but provides limited +performance in highly contended multi-threaded usage due to its simple approach. +However, it may still prove a good solution for a broad class of applications +which spend the majority of their time in application logic and not in QUIC I/O +processing. +.Sp +An advantage of this model relative to the more sophisticated concurrency models +below is that it does not create any OS threads. +.IP \(bu 4 +The \fBThread-Assisted Concurrency Model (TACM)\fR is identical to the Contentive +Concurrency Model except that a thread is spun up in the background to ensure +that QUIC timer events are handled in a timely fashion. This ensures that QUIC +timeout events are handled even if an application does not periodically call +into the QUIC domain to ensure that any outstanding QUIC-related timer or +network I/O events are handled. The assist thread contends for the same +resources like any other thread. However, handshake layer events (TLS) are never +processed by the assist thread. +.PP +The default concurrency model is CCM or TACM, depending on the \fBSSL_METHOD\fR +used with a \fBSSL_CTX\fR. Using \fBOSSL_QUIC_client_method\fR\|(3) results in a default +concurrency model of CCM, whereas using \fBOSSL_QUIC_client_thread_method\fR\|(3) +results in a default concurrency model of TACM. +.PP +Additional concurrency models may be offered in future releases of OpenSSL. +.SH "BLOCKING I/O CAPABILITIES" +.IX Header "BLOCKING I/O CAPABILITIES" +All of the supported concurrency models are capable of supporting blocking I/O +calls, where application-level I/O calls (for example, to \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(3) on a QUIC stream SSL object) block until the request can be +serviced. This includes the use of \fBSSL_poll\fR\|(3) in a blocking fashion. +.PP +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 \fBSSL_set_blocking_mode\fR\|(3) attempting to enable blocking mode may fail, +notwithstanding the following section. +.SS "Legacy Blocking Support Compatibility" +.IX Subsection "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 (SCM), where it works +reliably. +.PP +For compatibility reasons, this functionality is also available under the +default concurrency model if the application does not explicitly specify a +concurrency model or disable it. This is known as Legacy Blocking Compatibility +Mode, and its usage is not recommended for multi-threaded applications. +.SH "RECOMMENDED USAGE" +.IX Header "RECOMMENDED USAGE" +New applications are advised to choose a concurrency model as follows: +.IP \(bu 4 +A purely single-threaded application, or an application which wishes to use +OpenSSL QUIC as a state machine and manage synchronisation itself, should +explicitly select the SCM concurrency model. +.IP \(bu 4 +An application which wants to engage in multi-threaded usage of different QUIC +connections or streams in the same QUIC domain should a) select the CCM or TACM +concurrency model and b) explicitly opt in or out of blocking I/O support +(depending on whether the application wishes to make blocking I/O calls), +disabling Legacy Blocking Compatibility Mode. +.Sp +An application should select the CCM concurrency model if the application can +guarantee that a QUIC domain will be serviced regularly (for example, because +the application can guarantee that the timeout returned by +\&\fBSSL_get_event_timeout\fR\|(3) will be handled). If an application is unable to do +this, it should select the TACM concurrency model. +.IP \(bu 4 +Applications should explicitly configure a concurrency model during +initialisation. +.SH "CONFIGURING A CONCURRENCY MODEL" +.IX Header "CONFIGURING A CONCURRENCY MODEL" +If using an explicit QUIC domain, a concurrency model is chosen when calling +\&\fBSSL_new_domain\fR\|(3) by specifying zero or more of the following flags: +.IP \fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR 4 +.IX Item "SSL_DOMAIN_FLAG_SINGLE_THREAD" +Specifying this flag configures the Single-Threaded Concurrency Model (SCM). +.IP \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR 4 +.IX Item "SSL_DOMAIN_FLAG_MULTI_THREAD" +Speciyfing this flag configures the Contentive Concurrency Model (CCM) (unless +\&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR is also specified). +.IP \fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR 4 +.IX Item "SSL_DOMAIN_FLAG_THREAD_ASSISTED" +Specifying this flag configures the Thread-Assisted Concurrency Model (TACM). +It implies \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR. +.IP \fBSSL_DOMAIN_FLAG_BLOCKING\fR 4 +.IX Item "SSL_DOMAIN_FLAG_BLOCKING" +Enable reliable support for blocking I/O calls, allocating whatever OS resources +are necessary to realise this. If this flag is specified, +\&\fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR is ignored. +.Sp +Details on the allocated OS resources can be found under "CONSUMPTION OF OS +RESOURCES" below. +.IP \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR 4 +.IX Item "SSL_DOMAIN_FLAG_LEGACY_BLOCKING" +Enables legacy blocking compatibility mode. See "Legacy Blocking Support +Compatibility". +.PP +Mutually exclusive flag combinations result in an error (for example, combining +\&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR and \fBSSL_DOMAIN_FLAG_MULTI_THREADED\fR). +.PP +The concurrency model for a domain cannot be changed after the domain is +created. +.SS "Default Behaviour" +.IX Subsection "Default Behaviour" +If none of \fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR, \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR or +\&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR are provided to \fBSSL_new_domain\fR\|(3) or +another constructor function which can accept the above flags, the default +concurrency model set on the \fBSSL_CTX\fR is used. This default can be set and get +using \fBSSL_CTX_set_domain_flags\fR\|(3) and \fBSSL_CTX_get_domain_flags\fR\|(3). Any +additional flags provided (for example, \fBSSL_DOMAIN_FLAG_BLOCCKING\fR) are added +to the set of inherited flags. +.PP +The default concurrency model set on a newly created \fBSSL_CTX\fR is determined as +follows: +.IP \(bu 4 +If an \fBSSL_METHOD\fR of \fBOSSL_QUIC_client_thread_method\fR\|(3) is used, the +Thread-Assisted Concurrency Model (TACM) is used with the +\&\fBSSL_DOMAIN_FLAG_BLOCKING\fR flag. This provides reliable blocking functionality. +.IP \(bu 4 +Otherwise, if OpenSSL was built without threading support, the Single-Threaded +Concurrency Model (SCM) is used, with the \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR +flag. +.IP \(bu 4 +Otherwise, if an \fBSSL_METHOD\fR of \fBOSSL_QUIC_client_method\fR\|(3) is used, the +Contentive Concurrency Model (CCM) is used with the +\&\fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR flag. +.IP \(bu 4 +Otherwise, the Contentive Concurrency Model (CCM) is used. +.PP +The default concurrency model may vary between releases of OpenSSL. An +application may specify one or more of the domain flags above to ensure +consistent usage of a specific concurrency model between releases. +.SS "Configuration of Concurrency Models with Implicit QUIC Domains" +.IX Subsection "Configuration of Concurrency Models with Implicit QUIC Domains" +If an explicit QUIC domain is not explicitly created using \fBSSL_new_domain\fR\|(3), +an implicit QUIC domain is created when calling \fBSSL_new_listener\fR\|(3) or +\&\fBSSL_new\fR\|(3). Such a domain will use the default domain flags configured on the +\&\fBSSL_CTX\fR as described above. +.SH "CONSUMPTION OF OS RESOURCES" +.IX Header "CONSUMPTION OF OS RESOURCES" +If full blocking I/O support is selected using \fBSSL_DOMAIN_FLAG_BLOCKING\fR, at +least one socket, socket-like OS handle or file descriptor must be allocated to +allow one thread to wake other threads which may be blocking in calls to OS +socket polling interfaces such as \fBselect\fR\|(2) or \fBpoll\fR\|(2). This is allocated +automatically internally by OpenSSL. +.PP +If the Thread-Assisted Concurrency Model (TACM) is selected, a background thread +is spawned. This also implies \fBSSL_DOMAIN_FLAG_BLOCKING\fR and the above. +.PP +The internal consumption by OpenSSL of mutexes, condition variables, spin locks +or other similar thread synchronisation primitives is unspecified under all +concurrency models. +.PP +The internal consumption by OpenSSL of threads is unspecified under the +Thread-Assisted Concurrency Model. +.PP +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 +\&\fBSSL_DOMAIN_FLAG_BLOCKING\fR. +.SH "BEHAVIOUR OF SSL OBJECTS" +.IX Header "BEHAVIOUR OF SSL OBJECTS" +A QUIC SSL object has blocking mode enabled by default where \fBall\fR of the +following criteria are met: +.IP \(bu 4 +\&\fBSSL_DOMAIN_FLAG_BLOCKING\fR or \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR is enabled; +and +.IP \(bu 4 +The QUIC connection is being used with network read and write BIOs which expose +supported poll descriptors. See \fBopenssl\-quic\fR\|(7) for details. +.PP +In all other cases, a QUIC SSL object has blocking mode disabled by default. The +blocking mode can be changed explicitly using \fBSSL_set_blocking_mode\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-quic\fR\|(7), \fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), +\&\fBOSSL_QUIC_client_thread_method\fR\|(3), \fBSSL_CTX_set_domain_flags\fR\|(3), +\&\fBSSL_new_domain\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |