=head1 DESCRIPTION
OpenSSL 3.2 and later features support for the QUIC transport protocol.
-Currently, only client connectivity is supported. This man page describes the
-usage of QUIC client functionality for both existing and new applications.
+You can use OpenSSL's QUIC capabilities for both client and server applications.
+This man page describes how to let applications use the QUIC protocol using the
+libssl API.
-QUIC functionality uses the standard SSL API. A QUIC connection is represented
+The QUIC protocol maps to the standard SSL API. A QUIC connection is represented
by an SSL object in the same way that a TLS connection is. Only minimal changes
-are needed to existing applications making use of the libssl APIs to make use of
-QUIC client functionality. To make use of QUIC, use the SSL method
-L<OSSL_QUIC_client_method(3)> or L<OSSL_QUIC_client_thread_method(3)> with
-L<SSL_CTX_new(3)>.
-
-When a QUIC connection is created, by default, it operates in default stream
-mode, which is intended to provide compatibility with existing non-QUIC
-application usage patterns. In this mode, the connection has a single
-stream associated with it. Calls to L<SSL_read(3)> and
-L<SSL_write(3)> on the QUIC connection SSL object read and write from that
-stream. Whether the stream is client-initiated or server-initiated from a QUIC
-perspective depends on whether L<SSL_read(3)> or L<SSL_write(3)> is called
-first. See the MODES OF OPERATION section for more information.
-
-The default stream mode is intended for compatibility with existing
-applications. New applications using QUIC are recommended to disable default
-stream mode and use the multi-stream API; see the MODES OF OPERATION section and
-the RECOMMENDATIONS FOR NEW APPLICATIONS section for more information.
+are needed to existing applications which use libssl API to bring QUIC protocol
+support in. QUIC clients can use L<OSSL_QUIC_client_method(3)> or
+L<OSSL_QUIC_client_thread_method(3)> with L<SSL_CTX_new(3)>. See below for more
+details about the difference between the two. For servers, there is only one
+option: SSL method L<OSSL_QUIC_server_method(3)> with L<SSL_CTX_new(3)>.
The remainder of this man page discusses, in order:
=item
-Default stream mode versus multi-stream mode;
+Default stream mode versus multi-stream mode for clients;
=item
-The changes to existing libssl APIs which are driven by QUIC-related implementation
-requirements, which existing applications should bear in mind;
+The changes to existing libssl APIs which are driven by QUIC-related
+implementation requirements, which existing applications should bear in mind;
=item
=back
-=head1 MODES OF OPERATION
+=head1 CLIENT MODES OF OPERATION
+
+When a client creates a QUIC connection, by default, it operates in default
+stream mode, which is intended to provide compatibility with existing non-QUIC
+application usage patterns. In this mode, the connection has a single stream
+associated with it. Calls to L<SSL_read(3)> and L<SSL_write(3)> on the QUIC
+connection SSL object read and write from that stream. Whether the stream is
+client-initiated or server-initiated from a QUIC perspective depends on whether
+L<SSL_read(3)> or L<SSL_write(3)> is called first.
+
+Default stream mode is primarily for compatibility with existing applications.
+For new applications utilizing QUIC, it's recommended to disable this mode and
+instead adopt the multi-stream API. See the RECOMMENDATIONS FOR NEW APPLICATIONS
+section for more details.
=head2 Default Stream Mode
L<SSL_set_accept_state(3)>. It is not necessary to call either of
L<SSL_set_connect_state(3)> or L<SSL_set_accept_state(3)> before connecting, but
if either of these are called, the function called must be congruent with the
-B<SSL_METHOD> being used. Currently, only client mode is supported.
+B<SSL_METHOD> being used.
=item
=item
-An application wishing to use QUIC must use L<OSSL_QUIC_client_method(3)> or
-L<OSSL_QUIC_client_thread_method(3)> as its SSL method. For more information
-on the differences between these two methods, see B<THREAD ASSISTED MODE>.
+A client application wishing to use QUIC must use L<OSSL_QUIC_client_method(3)>
+or L<OSSL_QUIC_client_thread_method(3)> as its SSL method. For more information
+on the differences between these two methods, see
+B<THREAD ASSISTED MODE>.
+
+=item
+
+A server application wishing to use QUIC must use L<OSSL_QUIC_server_method(3)>.
+The server can then accept new connections with L<SSL_accept_connection(3)>.
=item
in blocking or nonblocking mode based on whether the underlying network BIO
operates in blocking or nonblocking mode. QUIC requires the use of a
nonblocking network BIO, therefore the blocking mode at the application level
-must be explicitly configured by the application using the new
+can be explicitly configured by the application using the new
L<SSL_set_blocking_mode(3)> API. The default mode is blocking. If an application
wishes to use the SSL object APIs at application level in a nonblocking manner,
it must add a call to L<SSL_set_blocking_mode(3)> to disable blocking mode.
=item
-If your application does not choose to use thread assisted mode, it must ensure
-that it calls an I/O function on the SSL object (for example, L<SSL_read(3)> or
-L<SSL_write(3)>), or the new function L<SSL_handle_events(3)>, regularly. If the
-SSL object is used in blocking mode, an ongoing blocking call to an I/O function
-satisfies this requirement. This is required to ensure that timer events
-required by QUIC are handled in a timely fashion.
+If your client application does not choose to use thread assisted mode, it must
+ensure that it calls an I/O function on the SSL object (for example,
+L<SSL_read(3)> or L<SSL_write(3)>), or the new function L<SSL_handle_events(3)>,
+regularly. If the SSL object is used in blocking mode, an ongoing blocking call
+to an I/O function satisfies this requirement. This is required to ensure that
+timer events required by QUIC are handled in a timely fashion.
Most applications will service the SSL object by calling L<SSL_read(3)> or
L<SSL_write(3)> regularly. If an application does not do this, it should ensure
resources which can be used to determine when L<SSL_handle_events(3)> should be
called due to network I/O.
-Applications which use thread assisted mode do not need to be concerned
+Client applications which use thread assisted mode do not need to be concerned
with this requirement, as the QUIC implementation ensures timeout events
are handled in a timely manner. See B<THREAD ASSISTED MODE> for details.
perform any pending I/O or timeout processing. It can be used to advance the
QUIC state machine by processing incoming network traffic, generating outgoing
network traffic and handling any expired timeout events. Most other I/O
-functions on an SSL object, such as L<SSL_read(3)> and L<SSL_write(3)>
+functions on an SSL object, such as L<SSL_read(3)> and L<SSL_write(3)>,
implicitly perform event handling on the SSL object, so calling this function is
only needed if no other I/O function is to be called.
=over 4
+=item L<SSL_new_listener(3)>
+
+Creates a listener SSL object, which differs from an ordinary SSL object in that
+it is used to provide an abstraction for the acceptance of network connections
+in a protocol-agnostic manner.
+
+Currently, listener SSL objects are only supported for QUIC server usage or
+client-only usage. The listener interface may expand to support additional
+protocols in the future.
+
+=item L<SSL_new_listener_from(3)>
+
+Creates a listener SSL object which is subordinate to a QUIC domain SSL object
+I<ssl>. See L<SSL_new_domain(3)> and L<openssl-quic-concurrency(7)> for details
+on QUIC domain SSL objects.
+
+=item L<SSL_is_listener(3)>
+
+Returns 1 if and only if an SSL object is a listener SSL object.
+
+=item L<SSL_get0_listener(3)>
+
+Returns an SSL object pointer (potentially to the same object on which it is
+called) or NULL.
+
+=item L<SSL_listen(3)>
+
+Begin listening after a listener has been created. It is ordinarily not needed
+to call this because it will be called automatically on the first call to
+L<SSL_accept_connection(3)>.
+
+=item L<SSL_accept_connection(3)>
+
+Accepts a new incoming connection for a listner SSL object. A new SSL object
+representing the accepted connection is created and returned on success. If no
+incoming connection is available and the listener SSL object is configured in
+nonblocking mode, NULL is returned.
+
+=item L<SSL_get_accept_connection_queue_len(3)>
+
+Returns an informational value listing the number of connections waiting to be
+popped from the queue via calls to SSL_accept_connection().
+
+=item L<SSL_new_from_listener(3)>
+
+Creates a client connection under a given listener SSL object. For QUIC, it is
+also possible to use SSL_new_from_listener() in conjunction with a listener
+which does accept incoming connections (i.e., which was not created using
+B<SSL_LISTENER_FLAG_NO_ACCEPT>), leading to a UDP network endpoint which has
+both incoming and outgoing connections.
+
+=item L<SSL_new_domain(3)>
+
+Creates a new QUIC event domain, represented as an SSL object. This is known as
+a QUIC domain SSL object. The concept of a QUIC event domain is discussed in
+detail in L<openssl-quic-concurrency(7)>.
+
+=item L<SSL_is_domain(3)>
+
+Returns 1 if an SSL object is a QUIC domain SSL object.
+
+=item L<SSL_get0_domain(3)>
+
+SSL_get0_domain() obtains a pointer to the QUIC domain SSL object in an SSL
+object hierarchy (if any).
+
=item L<SSL_set_blocking_mode(3)>, L<SSL_get_blocking_mode(3)>
Configures whether blocking semantics are used at the application level. This
a call to L<SSL_handle_events(3)>. L<SSL_get_wpoll_descriptor(3)> works in an
analogous fashion for the underlying network write BIO.
-The poll descriptors provided by these functions need only be used when
-L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> return 1, respectively.
+The poll descriptors provided by these functions should be used only when
+L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> return 1,
+respectively.
=item L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)>
=item L<SSL_shutdown_ex(3)>
This augments L<SSL_shutdown(3)> by allowing an application error code to be
-specified. It also allows a client to decide how quickly it wants a shutdown to
-be performed, potentially by trading off strict RFC compliance.
+specified. It also allows an application to decide how quickly it wants a
+shutdown to be performed, potentially by trading off strict RFC compliance.
=item L<SSL_stream_conclude(3)>
=head1 THREAD ASSISTED MODE
-The optional thread assisted mode can be used with
+The optional thread assisted mode for clients can be used with
L<OSSL_QUIC_client_thread_method(3)>. In this mode, a background thread is
created automatically. The OpenSSL QUIC implementation then takes responsibility
for ensuring that timeout events are handled on a timely basis even if no SSL
L<SSL_get_stream_read_error_code(3)>, L<SSL_get_conn_close_info(3)>,
L<SSL_get0_connection(3)>, L<SSL_get_stream_type(3)>, L<SSL_get_stream_id(3)>,
L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>,
-L<SSL_set_incoming_stream_policy(3)>, L<SSL_set_default_stream_mode(3)>
+L<SSL_set_incoming_stream_policy(3)>, L<SSL_set_default_stream_mode(3)>,
+L<SSL_new_listener(3)>, L<SSL_new_listener_from(3)>, L<SSL_is_listener(3)>,
+L<SSL_get0_listener(3)>, L<SSL_listen(3)>, L<SSL_accept_connection(3)>,
+L<SSL_get_accept_connection_queue_len(3)>, L<SSL_new_domain(3)>,
+L<SSL_is_domain(3)>, L<SSL_get0_domain(3)>
=head1 COPYRIGHT
-Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2022-2024 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
projects / thirdparty / openssl.git / commitdiff
