1=pod 2 3=head1 NAME 4 5SSL_new_domain, 6SSL_is_domain, 7SSL_get0_domain 8- SSL object interface for managing QUIC event domains 9 10=head1 SYNOPSIS 11 12 #include <openssl/ssl.h> 13 14 SSL *SSL_new_domain(SSL_CTX *ctx, uint64_t flags); 15 16 int SSL_is_domain(SSL *ssl); 17 SSL *SSL_get0_domain(SSL *ssl); 18 19=head1 DESCRIPTION 20 21The SSL_new_domain() function creates a new QUIC event domain, represented as an 22SSL object. This is known as a QUIC domain SSL object (QDSO). The concept of a 23QUIC event domain is discussed in detail in L<openssl-quic-concurrency(7)>. 24 25The I<flags> argument to SSL_new_domain() specifies a set of domain flags. If the 26I<flags> argument to SSL_new_domain() does not specify one of the flags 27B<SSL_DOMAIN_FLAG_SINGLE_THREAD>, B<SSL_DOMAIN_FLAG_MULTI_THREAD> or 28B<SSL_DOMAIN_FLAG_THREAD_ASSISTED>, the domain flags configured on the 29B<SSL_CTX> are inherited as a default and any other flags in I<flags> are added 30to the set of inherited flags. Otherwise, the domain flags in I<flags> 31are used. See L<SSL_CTX_set_domain_flags(3)> for details of the available domain 32flags and how they can be configured on a B<SSL_CTX>. 33 34A QUIC domain SSL object can be managed in the same way as any other SSL object, 35in that it can be refcounted and freed normally. A QUIC domain SSL object is the 36parent of a number of child objects such as QUIC listener SSL objects. Once a 37QUIC domain SSL object has been created, a listener can be created under it 38using L<SSL_new_listener_from(3)>. 39 40SSL_is_domain() returns 1 if a SSL object is a QUIC domain SSL object. 41 42SSL_get0_domain() obtains a pointer to the QUIC domain SSL object in a SSL 43object hierarchy (if any). 44 45All SSL objects in a QUIC event domain use the same domain flags, and the domain 46flags for a QUIC domain cannot be changed after construction. 47 48=head2 Supported Operations 49 50A QUIC domain SSL object exists to contain other QUIC SSL objects and provide 51unified event handling. As such, it supports only the following operations: 52 53=over 4 54 55=item 56 57Standard reference counting and free operations, such as L<SSL_up_ref(3)> and 58L<SSL_free(3)>; 59 60=item 61 62Event processing and polling enablement APIs such as L<SSL_handle_events(3)>, 63and L<SSL_get_event_timeout(3)>. 64 65=item 66 67Creating listeners under the domain using L<SSL_new_listener_from(3)>. 68 69=back 70 71The basic workflow of using a domain object is as follows: 72 73=over 4 74 75=item 76 77Create a new domain object using SSL_new_domain() using a B<SSL_CTX> which uses 78a supported B<SSL_METHOD> (such as L<OSSL_QUIC_server_method(3)>); 79 80=item 81 82Create listeners under the domain using L<SSL_new_listener_from(3)>. 83 84=back 85 86Refer to L<SSL_new_listener_from(3)> for details on using listeners. 87 88Currently, domain SSL objects are only supported for QUIC usage via any QUIC 89B<SSL_METHOD>. 90 91=head1 RETURN VALUES 92 93SSL_new_domain() returns a new domain SSL object or NULL on failure. 94 95SSL_is_domain() returns 0 or 1 depending on the type of the SSL object on 96which it is called. 97 98SSL_get0_domain() returns an SSL object pointer (potentially to the same object 99on which it is called) or NULL. 100 101=head1 SEE ALSO 102 103L<SSL_new_listener_from(3)> L<SSL_handle_events(3)>, 104L<SSL_CTX_set_domain_flags(3)>, L<openssl-quic-concurrency(7)> 105 106=head1 HISTORY 107 108These functions were added in OpenSSL 3.5. 109 110=head1 COPYRIGHT 111 112Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 113 114Licensed under the Apache License 2.0 (the "License"). You may not use 115this file except in compliance with the License. You can obtain a copy 116in the file LICENSE in the source distribution or at 117L<https://www.openssl.org/source/license.html>. 118 119=cut 120