mirror of
https://github.com/openssl/openssl.git
synced 2025-03-31 20:10:45 +08:00
0c679f5566
Reviewed-by: Neil Horman <nhorman@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> Release: yes
120 lines
3.5 KiB
Plaintext
120 lines
3.5 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_new_domain,
|
|
SSL_is_domain,
|
|
SSL_get0_domain
|
|
- SSL object interface for managing QUIC event domains
|
|
|
|
=head1 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);
|
|
|
|
=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)>.
|
|
|
|
The I<flags> argument to SSL_new_domain() specifies a set of domain flags. If the
|
|
I<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 inherited as a default and any other flags in I<flags> are added
|
|
to the set of inherited flags. Otherwise, the domain flags in I<flags>
|
|
are used. See L<SSL_CTX_set_domain_flags(3)> for details of the available domain
|
|
flags and how they can be configured on a B<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 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).
|
|
|
|
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.
|
|
|
|
=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<SSL_handle_events(3)>,
|
|
L<SSL_CTX_set_domain_flags(3)>, L<openssl-quic-concurrency(7)>
|
|
|
|
=head1 HISTORY
|
|
|
|
These functions were added in OpenSSL 3.5.
|
|
|
|
=head1 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
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|