QUIC Concurrency API Implementation

crypto/err/openssl.txt

@@ -1387,6 +1387,7 @@ SSL_R_DECRYPTION_FAILED_OR_BAD_RECORD_MAC:281:\
 SSL_R_DH_KEY_TOO_SMALL:394:dh key too small
 SSL_R_DH_PUBLIC_VALUE_LENGTH_IS_WRONG:148:dh public value length is wrong
 SSL_R_DIGEST_CHECK_FAILED:149:digest check failed
+SSL_R_DOMAIN_USE_ONLY:420:domain use only
 SSL_R_DTLS_MESSAGE_TOO_BIG:334:dtls message too big
 SSL_R_DUPLICATE_COMPRESSION_ID:309:duplicate compression id
 SSL_R_ECC_CERT_NOT_FOR_SIGNING:318:ecc cert not for signing

doc/build.info

@@ -2283,6 +2283,10 @@ DEPEND[html/man3/SSL_CTX_set_default_passwd_cb.html]=man3/SSL_CTX_set_default_pa
 GENERATE[html/man3/SSL_CTX_set_default_passwd_cb.html]=man3/SSL_CTX_set_default_passwd_cb.pod
 DEPEND[man/man3/SSL_CTX_set_default_passwd_cb.3]=man3/SSL_CTX_set_default_passwd_cb.pod
 GENERATE[man/man3/SSL_CTX_set_default_passwd_cb.3]=man3/SSL_CTX_set_default_passwd_cb.pod
+DEPEND[html/man3/SSL_CTX_set_domain_flags.html]=man3/SSL_CTX_set_domain_flags.pod
+GENERATE[html/man3/SSL_CTX_set_domain_flags.html]=man3/SSL_CTX_set_domain_flags.pod
+DEPEND[man/man3/SSL_CTX_set_domain_flags.3]=man3/SSL_CTX_set_domain_flags.pod
+GENERATE[man/man3/SSL_CTX_set_domain_flags.3]=man3/SSL_CTX_set_domain_flags.pod
 DEPEND[html/man3/SSL_CTX_set_generate_session_id.html]=man3/SSL_CTX_set_generate_session_id.pod
 GENERATE[html/man3/SSL_CTX_set_generate_session_id.html]=man3/SSL_CTX_set_generate_session_id.pod
 DEPEND[man/man3/SSL_CTX_set_generate_session_id.3]=man3/SSL_CTX_set_generate_session_id.pod
@@ -2659,6 +2663,10 @@ DEPEND[html/man3/SSL_new.html]=man3/SSL_new.pod
 GENERATE[html/man3/SSL_new.html]=man3/SSL_new.pod
 DEPEND[man/man3/SSL_new.3]=man3/SSL_new.pod
 GENERATE[man/man3/SSL_new.3]=man3/SSL_new.pod
+DEPEND[html/man3/SSL_new_domain.html]=man3/SSL_new_domain.pod
+GENERATE[html/man3/SSL_new_domain.html]=man3/SSL_new_domain.pod
+DEPEND[man/man3/SSL_new_domain.3]=man3/SSL_new_domain.pod
+GENERATE[man/man3/SSL_new_domain.3]=man3/SSL_new_domain.pod
 DEPEND[html/man3/SSL_new_listener.html]=man3/SSL_new_listener.pod
 GENERATE[html/man3/SSL_new_listener.html]=man3/SSL_new_listener.pod
 DEPEND[man/man3/SSL_new_listener.3]=man3/SSL_new_listener.pod
@@ -3506,6 +3514,7 @@ html/man3/SSL_CTX_set_client_hello_cb.html \
 html/man3/SSL_CTX_set_ct_validation_callback.html \
 html/man3/SSL_CTX_set_ctlog_list_file.html \
 html/man3/SSL_CTX_set_default_passwd_cb.html \
+html/man3/SSL_CTX_set_domain_flags.html \
 html/man3/SSL_CTX_set_generate_session_id.html \
 html/man3/SSL_CTX_set_info_callback.html \
 html/man3/SSL_CTX_set_keylog_callback.html \
@@ -3600,6 +3609,7 @@ html/man3/SSL_key_update.html \
 html/man3/SSL_library_init.html \
 html/man3/SSL_load_client_CA_file.html \
 html/man3/SSL_new.html \
+html/man3/SSL_new_domain.html \
 html/man3/SSL_new_listener.html \
 html/man3/SSL_new_stream.html \
 html/man3/SSL_pending.html \
@@ -4152,6 +4162,7 @@ man/man3/SSL_CTX_set_client_hello_cb.3 \
 man/man3/SSL_CTX_set_ct_validation_callback.3 \
 man/man3/SSL_CTX_set_ctlog_list_file.3 \
 man/man3/SSL_CTX_set_default_passwd_cb.3 \
+man/man3/SSL_CTX_set_domain_flags.3 \
 man/man3/SSL_CTX_set_generate_session_id.3 \
 man/man3/SSL_CTX_set_info_callback.3 \
 man/man3/SSL_CTX_set_keylog_callback.3 \
@@ -4246,6 +4257,7 @@ man/man3/SSL_key_update.3 \
 man/man3/SSL_library_init.3 \
 man/man3/SSL_load_client_CA_file.3 \
 man/man3/SSL_new.3 \
+man/man3/SSL_new_domain.3 \
 man/man3/SSL_new_listener.3 \
 man/man3/SSL_new_stream.3 \
 man/man3/SSL_pending.3 \
@@ -4787,6 +4799,10 @@ DEPEND[html/man7/openssl-qlog.html]=man7/openssl-qlog.pod
 GENERATE[html/man7/openssl-qlog.html]=man7/openssl-qlog.pod
 DEPEND[man/man7/openssl-qlog.7]=man7/openssl-qlog.pod
 GENERATE[man/man7/openssl-qlog.7]=man7/openssl-qlog.pod
+DEPEND[html/man7/openssl-quic-concurrency.html]=man7/openssl-quic-concurrency.pod
+GENERATE[html/man7/openssl-quic-concurrency.html]=man7/openssl-quic-concurrency.pod
+DEPEND[man/man7/openssl-quic-concurrency.7]=man7/openssl-quic-concurrency.pod
+GENERATE[man/man7/openssl-quic-concurrency.7]=man7/openssl-quic-concurrency.pod
 DEPEND[html/man7/openssl-quic.html]=man7/openssl-quic.pod
 GENERATE[html/man7/openssl-quic.html]=man7/openssl-quic.pod
 DEPEND[man/man7/openssl-quic.7]=man7/openssl-quic.pod
@@ -5049,6 +5065,7 @@ html/man7/openssl-core_names.h.html \
 html/man7/openssl-env.html \
 html/man7/openssl-glossary.html \
 html/man7/openssl-qlog.html \
+html/man7/openssl-quic-concurrency.html \
 html/man7/openssl-quic.html \
 html/man7/openssl-threads.html \
 html/man7/openssl_user_macros.html \
@@ -5192,6 +5209,7 @@ man/man7/openssl-core_names.h.7 \
 man/man7/openssl-env.7 \
 man/man7/openssl-glossary.7 \
 man/man7/openssl-qlog.7 \
+man/man7/openssl-quic-concurrency.7 \
 man/man7/openssl-quic.7 \
 man/man7/openssl-threads.7 \
 man/man7/openssl_user_macros.7 \

doc/man3/SSL_CTX_set_domain_flags.pod

@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_domain_flags, SSL_CTX_get_domain_flags, SSL_get_domain_flags,
+SSL_DOMAIN_FLAG_SINGLE_THREAD,
+SSL_DOMAIN_FLAG_MULTI_THREAD,
+SSL_DOMAIN_FLAG_THREAD_ASSISTED,
+SSL_DOMAIN_FLAG_BLOCKING,
+SSL_DOMAIN_FLAG_LEGACY_BLOCKING
+- control the concurrency model used by a QUIC domain
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_DOMAIN_FLAG_SINGLE_THREAD
+ #define SSL_DOMAIN_FLAG_MULTI_THREAD
+ #define SSL_DOMAIN_FLAG_LEGACY_BLOCKING
+ #define SSL_DOMAIN_FLAG_BLOCKING
+ #define SSL_DOMAIN_FLAG_THREAD_ASSISTED
+
+ int SSL_CTX_set_domain_flags(SSL_CTX *ctx, uint64_t flags);
+ int SSL_CTX_get_domain_flags(SSL_CTX *ctx, uint64_t *flags);
+
+ int SSL_get_domain_flags(SSL *ssl, uint64_t *flags);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_domain_flags() and SSL_CTX_get_domain_flags() set and get the QUIC
+domain flags on a B<SSL_CTX> using a QUIC B<SSL_METHOD>. These flags determine
+the concurrency model which is used for a QUIC domain. A detailed introduction
+to these concepts can be found in L<openssl-quic-concurrency(7)>.
+
+The flags comprise zero or more of the following flags:
+
+=over 4
+
+=item B<SSL_DOMAIN_FLAG_SINGLE_THREAD>
+
+Specifying this flag configures the Single-Threaded Concurrency Model (SCM).
+
+=item B<SSL_DOMAIN_FLAG_MULTI_THREAD>
+
+Speciyfing this flag configures the Contentive Concurrency Model (CCM) (unless
+B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> is also specified).
+
+=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>.
+
+=item B<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,
+B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING> is ignored.
+
+=item B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING>
+
+Enables legacy blocking compatibility mode. See
+L<openssl-quic-concurrency(7)/Legacy Blocking Support Compatibility>.
+
+=back
+
+Mutually exclusive flag combinations result in an error (for example, combining
+B<SSL_DOMAIN_FLAG_SINGLE_THREAD> and B<SSL_DOMAIN_FLAG_MULTI_THREADED>).
+
+Because exactly one concurrency model must be chosen, the domain flags cannot be
+set to 0 and attempting to do so will result in an error.
+
+Changing these flags using SSL_CTX_set_domain_flags() has no effect on QUIC
+domains which have already been created.
+
+The default set of domain flags set on a newly created B<SSL_CTX> may vary by
+OpenSSL version, chosen B<SSL_METHOD>, and operating environment. See
+L<openssl-quic-concurrency(7)> for details. An application can retrieve the
+default domain flags by calling SSL_CTX_get_domain_flags() immediately after
+constructing a B<SSL_CTX>.
+
+SSL_get_domain_flags() retrieves the domain flags which are effective for a QUIC
+domain when called on any QUIC SSL object under that domain.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_domain_flags(), SSL_CTX_get_domain_flags() and
+SSL_get_domain_flags() return 1 on success and 0 on failure.
+
+SSL_CTX_set_domain_flags() fails if called with a set of flags which are
+inconsistent or which cannot be supported given the current environment.
+
+SSL_CTX_set_domain_flags() and SSL_CTX_get_domain_flags() fail if called on a
+B<SSL_CTX> which is not using a QUIC B<SSL_METHOD>.
+
+SSL_get_domain_flags() fails if called on a non-QUIC SSL object.
+
+=head1 SEE ALSO
+
+L<SSL_new_domain(3)>, L<openssl-quic-concurrency(7)>
+
+=head1 HISTORY
+
+These functions were added in @QUIC_SERVER_VERSION@.
+
+=head1 COPYRIGHT
+
+Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
+
+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
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/man3/SSL_new_domain.pod

@@ -0,0 +1,118 @@
+=pod
+
+=head1 NAME
+
+SSL_new_domain,
+SSL_is_domain,
+SSL_get0_domain
+- SSL object interface for managing QUIC event domains
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL *SSL_new_domain(SSL_CTX *ctx, uint64_t flags);
+
+ int SSL_is_domain(SSL *ssl);
+ SSL *SSL_get0_domain(SSL *ssl);
+
+=head1 DESCRIPTION
+
+The SSL_new_domain() function creates a new QUIC event domain, represented as an
+SSL object. This is known as a QUIC domain SSL object (QDSO). The concept of a
+QUIC event domain is discussed in detail in L<openssl-quic-concurrency(7)>.
+
+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>
+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>.
+
+A QUIC domain SSL object can be managed in the same way as any other SSL object,
+in that it can be refcounted and freed normally. A QUIC domain SSL object is the
+parent of a number of child objects such as QUIC listener SSL objects. Once a
+QUIC domain SSL object has been created, a listener can be created under it
+using L<SSL_new_listener_from(3)>.
+
+SSL_is_domain() returns 1 if a SSL object is a QUIC domain SSL object.
+
+SSL_get0_domain() obtains a pointer to the QUIC domain SSL object in a SSL
+object hierarchy (if any).
+
+All SSL objects in a QUIC event domain use the same domain flags, and the domain
+flags for a QUIC domain cannot be changed after construction.
+
+=head2 Supported Operations
+
+A QUIC domain SSL object exists to contain other QUIC SSL objects and provide
+unified event handling. As such, it supports only the following operations:
+
+=over 4
+
+=item
+
+Standard reference counting and free operations, such as L<SSL_up_ref(3)> and
+L<SSL_free(3)>;
+
+=item
+
+Event processing and polling enablement APIs such as L<SSL_handle_events(3)>,
+and L<SSL_get_event_timeout(3)>.
+
+=item
+
+Creating listeners under the domain using L<SSL_new_listener_from(3)>.
+
+=back
+
+The basic workflow of using a domain object is as follows:
+
+=over 4
+
+=item
+
+Create a new domain object using SSL_new_domain() using a B<SSL_CTX> which uses
+a supported B<SSL_METHOD> (such as L<OSSL_QUIC_server_method(3)>);
+
+=item
+
+Create listeners under the domain using L<SSL_new_listener_from(3)>.
+
+=back
+
+Refer to L<SSL_new_listener_from(3)> for details on using listeners.
+
+Currently, domain SSL objects are only supported for QUIC usage via any QUIC
+B<SSL_METHOD>.
+
+=head1 RETURN VALUES
+
+SSL_new_domain() returns a new domain SSL object or NULL on failure.
+
+SSL_is_domain() returns 0 or 1 depending on the type of the SSL object on
+which it is called.
+
+SSL_get0_domain() returns an SSL object pointer (potentially to the same object
+on which it is called) or NULL.
+
+=head1 SEE ALSO
+
+L<SSL_new_listener_from(3)> L<SSL_handle_events(3)>,
+L<SSL_CTX_set_domain_flags(3)>, L<openssl-quic-concurrency(7)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL @VERSION_QUIC_SERVER@.
+
+=head1 COPYRIGHT
+
+Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
+
+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
+L<https://www.openssl.org/source/license.html>.
+
+=cut

doc/man3/SSL_new_listener.pod

@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-SSL_new_listener, SSL_is_listener, SSL_get0_listener, SSL_listen,
+SSL_new_listener, SSL_new_listener_from, SSL_is_listener, SSL_get0_listener,
+SSL_listen,
 SSL_accept_connection, SSL_get_accept_connection_queue_len,
 SSL_new_from_listener, SSL_LISTENER_FLAG_NO_ACCEPT,
 SSL_ACCEPT_CONNECTION_NO_BLOCK - SSL object interface for abstracted connection
@@ -14,6 +15,7 @@ acceptance
 
  #define SSL_LISTENER_FLAG_NO_ACCEPT
  SSL *SSL_new_listener(SSL_CTX *ctx, uint64_t flags);
+ SSL *SSL_new_listener_from(SSL *ssl, uint64_t flags);
 
  int SSL_is_listener(SSL *ssl);
  SSL *SSL_get0_listener(SSL *ssl);
@@ -36,6 +38,10 @@ manner. It cannot be used, for example, for sending or receiving data using
 L<SSL_write_ex(3)> or L<SSL_read_ex(3)>. In general, only those functions
 expressly documented as being supported on a listener SSL object are available.
 
+The SSL_new_listener_from() function creates a listener SSL object which is
+subordinate to a QUIC domain SSL object I<ssl>. See L<SSL_new_domain(3)> and
+L<openssl-quic-concurrency(7)> for details on QUIC domain SSL objects.
+
 A listener SSL object supports the following operations:
 
 =over 4
@@ -175,7 +181,8 @@ way of using the listener functionality in client-only mode.
 
 =head1 RETURN VALUES
 
-SSL_new_listener() returns a new listener SSL object or NULL on failure.
+SSL_new_listener() and SSL_new_listener_from() return a new listener SSL object
+or NULL on failure.
 
 SSL_is_listener() returns 0 or 1 depending on the type of the SSL object on
 which it is called.