.\" -*- 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 "SSL_NEW_DOMAIN 3ssl"
.TH SSL_NEW_DOMAIN 3ssl 2025-04-10 3.5.0 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
SSL_new_domain,
SSL_is_domain,
SSL_get0_domain
\&\- SSL object interface for managing QUIC event domains
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #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);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBSSL_new_domain()\fR 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 \fBopenssl\-quic\-concurrency\fR\|(7).
.PP
The \fIflags\fR argument to \fBSSL_new_domain()\fR specifies a set of domain flags. If the
\&\fIflags\fR argument to \fBSSL_new_domain()\fR does not specify one of the flags
\&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR, \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR or
\&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR, the domain flags configured on the
\&\fBSSL_CTX\fR are inherited as a default and any other flags in \fIflags\fR are added
to the set of inherited flags. Otherwise, the domain flags in \fIflags\fR
are used. See \fBSSL_CTX_set_domain_flags\fR\|(3) for details of the available domain
flags and how they can be configured on a \fBSSL_CTX\fR.
.PP
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 \fBSSL_new_listener_from\fR\|(3).
.PP
\&\fBSSL_is_domain()\fR returns 1 if a SSL object is a QUIC domain SSL object.
.PP
\&\fBSSL_get0_domain()\fR obtains a pointer to the QUIC domain SSL object in a SSL
object hierarchy (if any).
.PP
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.
.SS "Supported Operations"
.IX Subsection "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:
.IP \(bu 4
Standard reference counting and free operations, such as \fBSSL_up_ref\fR\|(3) and
\&\fBSSL_free\fR\|(3);
.IP \(bu 4
Event processing and polling enablement APIs such as \fBSSL_handle_events\fR\|(3),
and \fBSSL_get_event_timeout\fR\|(3).
.IP \(bu 4
Creating listeners under the domain using \fBSSL_new_listener_from\fR\|(3).
.PP
The basic workflow of using a domain object is as follows:
.IP \(bu 4
Create a new domain object using \fBSSL_new_domain()\fR using a \fBSSL_CTX\fR which uses
a supported \fBSSL_METHOD\fR (such as \fBOSSL_QUIC_server_method\fR\|(3));
.IP \(bu 4
Create listeners under the domain using \fBSSL_new_listener_from\fR\|(3).
.PP
Refer to \fBSSL_new_listener_from\fR\|(3) for details on using listeners.
.PP
Currently, domain SSL objects are only supported for QUIC usage via any QUIC
\&\fBSSL_METHOD\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_new_domain()\fR returns a new domain SSL object or NULL on failure.
.PP
\&\fBSSL_is_domain()\fR returns 0 or 1 depending on the type of the SSL object on
which it is called.
.PP
\&\fBSSL_get0_domain()\fR returns an SSL object pointer (potentially to the same object
on which it is called) or NULL.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_new_listener_from\fR\|(3) \fBSSL_handle_events\fR\|(3),
\&\fBSSL_CTX_set_domain_flags\fR\|(3), \fBopenssl\-quic\-concurrency\fR\|(7)
.SH HISTORY
.IX Header "HISTORY"
These functions were added in OpenSSL 3.5.
.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>.