Debian Codegraph @

upstream/debian-unstable/man3/SSL_new_domain.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_NEW_DOMAIN 3SSL"
58 .TH SSL_NEW_DOMAIN 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_new_domain,
65 SSL_is_domain,
66 SSL_get0_domain
67 \&\- SSL object interface for managing QUIC event domains
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/ssl.h>
72 \&
73 \& SSL *SSL_new_domain(SSL_CTX *ctx, uint64_t flags);
74 \&
75 \& int SSL_is_domain(SSL *ssl);
76 \& SSL *SSL_get0_domain(SSL *ssl);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 The \fBSSL_new_domain()\fR function creates a new QUIC event domain, represented as an
81 SSL object. This is known as a QUIC domain SSL object (QDSO). The concept of a
82 QUIC event domain is discussed in detail in \fBopenssl\-quic\-concurrency\fR\|(7).
83 .PP
84 The \fIflags\fR argument to \fBSSL_new_domain()\fR specifies a set of domain flags. If the
85 \&\fIflags\fR argument to \fBSSL_new_domain()\fR does not specify one of the flags
86 \&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR, \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR or
87 \&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR, the domain flags configured on the
88 \&\fBSSL_CTX\fR are inherited as a default and any other flags in \fIflags\fR are added
89 to the set of inherited flags. Otherwise, the domain flags in \fIflags\fR
90 are used. See \fBSSL_CTX_set_domain_flags\fR\|(3) for details of the available domain
91 flags and how they can be configured on a \fBSSL_CTX\fR.
92 .PP
93 A QUIC domain SSL object can be managed in the same way as any other SSL object,
94 in that it can be refcounted and freed normally. A QUIC domain SSL object is the
95 parent of a number of child objects such as QUIC listener SSL objects. Once a
96 QUIC domain SSL object has been created, a listener can be created under it
97 using \fBSSL_new_listener_from\fR\|(3).
98 .PP
99 \&\fBSSL_is_domain()\fR returns 1 if a SSL object is a QUIC domain SSL object.
100 .PP
101 \&\fBSSL_get0_domain()\fR obtains a pointer to the QUIC domain SSL object in a SSL
102 object hierarchy (if any).
103 .PP
104 All SSL objects in a QUIC event domain use the same domain flags, and the domain
105 flags for a QUIC domain cannot be changed after construction.
106 .SS "Supported Operations"
107 .IX Subsection "Supported Operations"
108 A QUIC domain SSL object exists to contain other QUIC SSL objects and provide
109 unified event handling. As such, it supports only the following operations:
110 .IP \(bu 4
111 Standard reference counting and free operations, such as \fBSSL_up_ref\fR\|(3) and
112 \&\fBSSL_free\fR\|(3);
113 .IP \(bu 4
114 Event processing and polling enablement APIs such as \fBSSL_handle_events\fR\|(3),
115 and \fBSSL_get_event_timeout\fR\|(3).
116 .IP \(bu 4
117 Creating listeners under the domain using \fBSSL_new_listener_from\fR\|(3).
118 .PP
119 The basic workflow of using a domain object is as follows:
120 .IP \(bu 4
121 Create a new domain object using \fBSSL_new_domain()\fR using a \fBSSL_CTX\fR which uses
122 a supported \fBSSL_METHOD\fR (such as \fBOSSL_QUIC_server_method\fR\|(3));
123 .IP \(bu 4
124 Create listeners under the domain using \fBSSL_new_listener_from\fR\|(3).
125 .PP
126 Refer to \fBSSL_new_listener_from\fR\|(3) for details on using listeners.
127 .PP
128 Currently, domain SSL objects are only supported for QUIC usage via any QUIC
129 \&\fBSSL_METHOD\fR.
130 .SH "RETURN VALUES"
131 .IX Header "RETURN VALUES"
132 \&\fBSSL_new_domain()\fR returns a new domain SSL object or NULL on failure.
133 .PP
134 \&\fBSSL_is_domain()\fR returns 0 or 1 depending on the type of the SSL object on
135 which it is called.
136 .PP
137 \&\fBSSL_get0_domain()\fR returns an SSL object pointer (potentially to the same object
138 on which it is called) or NULL.
139 .SH "SEE ALSO"
140 .IX Header "SEE ALSO"
141 \&\fBSSL_new_listener_from\fR\|(3) \fBSSL_handle_events\fR\|(3),
142 \&\fBSSL_CTX_set_domain_flags\fR\|(3), \fBopenssl\-quic\-concurrency\fR\|(7)
143 .SH HISTORY
144 .IX Header "HISTORY"
145 These functions were added in OpenSSL 3.5.
146 .SH COPYRIGHT
147 .IX Header "COPYRIGHT"
148 Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
149 .PP
150 Licensed under the Apache License 2.0 (the "License"). You may not use
151 this file except in compliance with the License. You can obtain a copy
152 in the file LICENSE in the source distribution or at
153 <https://www.openssl.org/source/license.html>.