SSL_NEW_DOMAIN(3ossl) OpenSSL SSL_NEW_DOMAIN(3ossl)
NAME
SSL_new_domain, SSL_is_domain, SSL_get0_domain - SSL object interface
for managing QUIC event domains
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);
DESCRIPTION
The SSL_new_domain(3) 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
openssl-quic-concurrency(7).
The flags argument to SSL_new_domain(3) specifies a set of domain flags.
If the flags argument to SSL_new_domain(3) does not specify one of the
flags SSL_DOMAIN_FLAG_SINGLE_THREAD, SSL_DOMAIN_FLAG_MULTI_THREAD or
SSL_DOMAIN_FLAG_THREAD_ASSISTED, the domain flags configured on the
SSL_CTX are inherited as a default and any other flags in flags are
added to the set of inherited flags. Otherwise, the domain flags in
flags are used. See SSL_CTX_set_domain_flags(3) for details of the
available domain flags and how they can be configured on a 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
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.
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:
o Standard reference counting and free operations, such as
SSL_up_ref(3) and SSL_free(3);
o Event processing and polling enablement APIs such as
SSL_handle_events(3), and SSL_get_event_timeout(3).
o Creating listeners under the domain using SSL_new_listener_from(3).
The basic workflow of using a domain object is as follows:
SSL_new_domain(3) using a SSL_CTX
which uses a supported SSL_METHOD (such as
OSSL_QUIC_server_method(3));
o Create listeners under the domain using SSL_new_listener_from(3).
Refer to SSL_new_listener_from(3) for details on using listeners.
Currently, domain SSL objects are only supported for QUIC usage via any
QUIC SSL_METHOD.
RETURN VALUES
SSL_new_domain(3) 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.
SEE ALSO
SSL_new_listener_from(3) SSL_handle_events(3),
SSL_CTX_set_domain_flags(3), openssl-quic-concurrency(7)
HISTORY
These functions were added in OpenSSL 3.5.
COPYRIGHT
Copyright 2024-2025 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
<https://www.openssl.org/source/license.html>.
3.5.0 2025-04-10 SSL_NEW_DOMAIN(3ossl)
openssl 3.5.0 - Generated Wed Apr 30 16:11:45 CDT 2025