QUIC: Document SSL_new_domain, etc.

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_new_domain.pod b/doc/man3/SSL_new_domain.pod
new file mode 100644 (file)
index 0000000..7a2233b
--- /dev/null
+++ b/doc/man3/SSL_new_domain.pod
@@ -0,0 +1,156 @@
+=pod
+
+=head1 NAME
+
+SSL_new_domain,
+SSL_is_domain,
+SSL_get0_domain,
+SSL_get_domain_flags,
+SSL_CTX_set_domain_flags,
+SSL_CTX_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 - SSL object interface for managing QUIC event domains
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_domain_flags(SSL_CTX *ctx, uint64_t domain_flags);
+ int SSL_CTX_get_domain_flags(SSL_CTX *ctx, uint64_t *domain_flags);
+
+ SSL *SSL_new_domain(SSL_CTX *ctx, uint64_t flags);
+
+ int SSL_is_domain(SSL *ssl);
+ SSL *SSL_get0_domain(SSL *ssl);
+
+ int SSL_get_domain_flags(SSL *ssl, uint64_t *domain_flags);
+
+ #define SSL_DOMAIN_FLAG_SINGLE_THREAD
+ #define SSL_DOMAIN_FLAG_MULTI_THREAD
+ #define SSL_DOMAIN_FLAG_THREAD_ASSISTED
+ #define SSL_DOMAIN_FLAG_BLOCKING
+ #define SSL_DOMAIN_FLAG_LEGACY_BLOCKING
+
+=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)>.
+
+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).
+
+=head2 Domain Flags
+
+Domain flags are a set of flags which configure the concurrency model used by
+the OpenSSL QUIC implementation. For more information, including the meanings of
+the B<SSL_DOMAIN_FLAG> values, see L<openssl-quic-concurrency(7)>.
+
+SSL_CTX_set_domain_flags() and SSL_CTX_get_domain_flags() can be used to set and
+get the domain flags configured on a B<SSL_CTX> which is using a QUIC
+B<SSL_METHOD>.
+
+A default set of domain flags are configured on a B<SSL_CTX> when it is
+constructed, and these can be determined by calling SSL_CTX_get_domain_flags()
+immediately after constructing a B<SSL_CTX>.
+
+The flags configured on a B<SSL_CTX> are used when an SSL object (such as a QUIC
+domain SSL object) is created from an B<SSL_CTX>. Subsequent to the domain flags
+on a B<SSL_CTX> do not affect SSL objects which have already been created.
+
+When calling SSL_new_domain(), if the I<domain_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.
+
+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.
+
+SSL_get_domain_flags() outputs the effective domain flags being used on any
+given QUIC SSL object.
+
+=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<openssl-quic-concurrency(7)>,
+L<SSL_handle_events(3)>
+
+=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