openssl/doc/man3/SSL_new_domain.pod

=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