diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/openssl-quic.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/openssl-quic.7 | 134 |
1 files changed, 75 insertions, 59 deletions
diff --git a/secure/lib/libcrypto/man/man7/openssl-quic.7 b/secure/lib/libcrypto/man/man7/openssl-quic.7 index d50b06cd1b87..ce5014ca0328 100644 --- a/secure/lib/libcrypto/man/man7/openssl-quic.7 +++ b/secure/lib/libcrypto/man/man7/openssl-quic.7 @@ -1,5 +1,5 @@ .\" -*- mode: troff; coding: utf-8 -*- -.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -52,10 +52,13 @@ . \} .\} .rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l .\" ======================================================================== .\" .IX Title "OPENSSL-QUIC 7ossl" -.TH OPENSSL-QUIC 7ossl 2025-09-30 3.5.4 OpenSSL +.TH OPENSSL-QUIC 7ossl 2026-04-07 3.5.6 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -65,7 +68,7 @@ openssl\-quic \- OpenSSL QUIC .SH DESCRIPTION .IX Header "DESCRIPTION" OpenSSL 3.2 and later features support for the QUIC transport protocol. -You can use OpenSSL's QUIC capabilities for both client and server applications. +You can use OpenSSL\*(Aqs QUIC capabilities for both client and server applications. This man page describes how to let applications use the QUIC protocol using the libssl API. .PP @@ -79,9 +82,9 @@ option: SSL method \fBOSSL_QUIC_server_method\fR\|(3) with \fBSSL_CTX_new\fR\|(3 .PP The remainder of this man page discusses, in order: .IP \(bu 4 -Default stream mode versus multi-stream mode for clients; +Default stream mode versus multi\-stream mode for clients; .IP \(bu 4 -The changes to existing libssl APIs which are driven by QUIC-related +The changes to existing libssl APIs which are driven by QUIC\-related implementation requirements, which existing applications should bear in mind; .IP \(bu 4 Aspects which must be considered by existing applications when adopting QUIC, @@ -89,25 +92,25 @@ including potential changes which may be needed. .IP \(bu 4 Recommended usage approaches for new applications. .IP \(bu 4 -New, QUIC-specific APIs. +New, QUIC\-specific APIs. .SH "CLIENT MODES OF OPERATION" .IX Header "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 +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 \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(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 +client\-initiated or server\-initiated from a QUIC perspective depends on whether \&\fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called first. .PP 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 +For new applications utilizing QUIC, it\*(Aqs recommended to disable this mode and +instead adopt the multi\-stream API. See the RECOMMENDATIONS FOR NEW APPLICATIONS section for more details. .SS "Default Stream Mode" .IX Subsection "Default Stream Mode" A QUIC client connection can be used in either default stream mode or -multi-stream mode. By default, a newly created QUIC connection SSL object uses +multi\-stream mode. By default, a newly created QUIC connection SSL object uses default stream mode. .PP In default stream mode, a stream is implicitly created and bound to the QUIC @@ -119,45 +122,45 @@ stream SSL object can also be called on a QUIC connection SSL object, in which case it affects the default stream bound to the connection. .PP The identity of a QUIC stream, including its stream ID, varies depending on -whether a stream is client-initiated or server-initiated. In default stream +whether a stream is client\-initiated or server\-initiated. In default stream mode, if a client application calls \fBSSL_read\fR\|(3) first before any call to \&\fBSSL_write\fR\|(3) on the connection, it is assumed that the application protocol -is using a server-initiated stream, and the \fBSSL_read\fR\|(3) call will not +is using a server\-initiated stream, and the \fBSSL_read\fR\|(3) call will not complete (either blocking, or failing appropriately if nonblocking mode is configured) until the server initiates a stream. Conversely, if the client application calls \fBSSL_write\fR\|(3) before any call to \fBSSL_read\fR\|(3) on the -connection, it is assumed that a client-initiated stream is to be used +connection, it is assumed that a client\-initiated stream is to be used and such a stream is created automatically. .PP Default stream mode is intended to aid compatibility with legacy applications. -New applications adopting QUIC should use multi-stream mode, described below, +New applications adopting QUIC should use multi\-stream mode, described below, and avoid use of the default stream functionality. .PP It is possible to use additional streams in default stream mode using \&\fBSSL_new_stream\fR\|(3) and \fBSSL_accept_stream\fR\|(3); note that the default incoming stream policy will need to be changed using \fBSSL_set_incoming_stream_policy\fR\|(3) in order to use \fBSSL_accept_stream\fR\|(3) in this case. However, applications -using additional streams are strongly recommended to use multi-stream mode +using additional streams are strongly recommended to use multi\-stream mode instead. .PP Calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) before a default stream has been associated with the QUIC connection SSL object will inhibit future creation of a default stream. -.SS "Multi-Stream Mode" +.SS "Multi\-Stream Mode" .IX Subsection "Multi-Stream Mode" -The recommended usage mode for new applications adopting QUIC is multi-stream +The recommended usage mode for new applications adopting QUIC is multi\-stream mode, in which no default stream is attached to the QUIC connection SSL object and attempts to call \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) on the QUIC connection SSL object fail. Instead, an application calls \fBSSL_new_stream\fR\|(3) or \&\fBSSL_accept_stream\fR\|(3) to create individual stream SSL objects for sending and receiving application data using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3). .PP -To use multi-stream mode, call \fBSSL_set_default_stream_mode\fR\|(3) with an +To use multi\-stream mode, call \fBSSL_set_default_stream_mode\fR\|(3) with an argument of \fBSSL_DEFAULT_STREAM_MODE_NONE\fR; this function must be called prior to initiating the connection. The default stream mode cannot be changed after initiating a connection. .PP -When multi-stream mode is used, meaning that no default stream is associated +When multi\-stream mode is used, meaning that no default stream is associated with the connection, calls to API functions which are defined as operating on a QUIC stream fail if called on the QUIC connection SSL object. For example, calls such as \fBSSL_write\fR\|(3) or \fBSSL_get_stream_id\fR\|(3) will fail. @@ -176,11 +179,11 @@ BIO: \&\fBBIO_s_datagram\fR\|(3), recommended for most applications, replaces \&\fBBIO_s_socket\fR\|(3) and provides a UDP socket. .IP \(bu 4 -\&\fBBIO_s_dgram_pair\fR\|(3) provides BIO pair-like functionality but with datagram +\&\fBBIO_s_dgram_pair\fR\|(3) provides BIO pair\-like functionality but with datagram semantics, and is recommended for existing applications which use a BIO pair or -memory BIO to manage libssl's communication with the network. +memory BIO to manage libssl\*(Aqs communication with the network. .IP \(bu 4 -\&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO-like interface but with +\&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO\-like interface but with datagram semantics. Unlike \fBBIO_s_dgram_pair\fR\|(3), it is unidirectional. .IP \(bu 4 An application may also choose to implement a custom BIO. The new @@ -194,18 +197,18 @@ instantiate a \fBBIO_s_socket\fR\|(3). For QUIC, these functions instead instant a \fBBIO_s_datagram\fR\|(3). This is equivalent to instantiating a \&\fBBIO_s_datagram\fR\|(3) and using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). .IP \(bu 4 -Traditionally, whether the application-level I/O APIs (such as \fBSSL_read\fR\|(3) +Traditionally, whether the application\-level I/O APIs (such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) operated in a blocking fashion was directly correlated with whether the underlying network socket was configured in a blocking fashion. This is no longer the case; applications must explicitly configure the desired -application-level blocking mode using \fBSSL_set_blocking_mode\fR\|(3). See +application\-level blocking mode using \fBSSL_set_blocking_mode\fR\|(3). See \&\fBSSL_set_blocking_mode\fR\|(3) for details. .IP \(bu 4 -Network-level I/O must always be performed in a nonblocking manner. The -application can still enjoy blocking semantics for calls to application-level +Network\-level I/O must always be performed in a nonblocking manner. The +application can still enjoy blocking semantics for calls to application\-level I/O functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), but the underlying network BIO provided to QUIC (such as a \fBBIO_s_datagram\fR\|(3)) must be configured -in nonblocking mode. For application-level blocking functionality, see +in nonblocking mode. For application\-level blocking functionality, see \&\fBSSL_set_blocking_mode\fR\|(3). .IP \(bu 4 \&\fBBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a @@ -217,8 +220,8 @@ change to use \fBBIO_new_ssl_connect\fR\|(3) instead. .IP \(bu 4 \&\fBSSL_shutdown\fR\|(3) has significant changes in relation to how QUIC connections must be shut down. In particular, applications should be advised that the full -RFC-conformant QUIC shutdown process may take an extended amount of time. This -may not be suitable for short-lived processes which should exit immediately +RFC\-conformant QUIC shutdown process may take an extended amount of time. This +may not be suitable for short\-lived processes which should exit immediately after their usage of a QUIC connection is completed. A rapid shutdown mode is available for such applications. For details, see \fBSSL_shutdown\fR\|(3). .IP \(bu 4 @@ -229,7 +232,7 @@ object. .Sp When used in nonblocking mode, \fBSSL_ERROR_WANT_READ\fR indicates that the receive part of a QUIC stream does not currently have any more data available to -be read, and \fBSSL_ERROR_WANT_WRITE\fR indicates that the stream's internal buffer +be read, and \fBSSL_ERROR_WANT_WRITE\fR indicates that the stream\*(Aqs internal buffer is full. .Sp To determine if the QUIC implementation currently wishes to be informed of @@ -237,7 +240,7 @@ incoming network datagrams, use the new function \fBSSL_net_read_desired\fR\|(3) likewise, to determine if the QUIC implementation currently wishes to be informed when it is possible to transmit network datagrams, use the new function \&\fBSSL_net_write_desired\fR\|(3). Only applications which wish to manage their own event -loops need to use these functions; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR for +loops need to use these functions; see \fBAPPLICATION\-DRIVEN EVENT LOOPS\fR for further discussion. .IP \(bu 4 The use of ALPN is mandatory when using QUIC. Attempts to connect without @@ -273,7 +276,7 @@ TLSv1.3 Early Data TLS Next Protocol Negotiation cannot be used and is superseded by ALPN, which must be used instead. The use of ALPN is mandatory with QUIC. .IP \(bu 4 -Post-Handshake Client Authentication is not available as QUIC prohibits its use. +Post\-Handshake Client Authentication is not available as QUIC prohibits its use. .IP \(bu 4 QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant to older TLS versions is not available. @@ -287,7 +290,7 @@ CCM mode is not currently supported. .RS 4 .Sp The following libssl functionality is also not available when used with QUIC, -but calls to the relevant functions are treated as no-ops: +but calls to the relevant functions are treated as no\-ops: .IP \(bu 4 Readahead (\fBSSL_set_read_ahead\fR\|(3), etc.) .RE @@ -316,7 +319,7 @@ the SSL object to provide it with network access. Changes needed: Change your application to use \fBBIO_s_datagram\fR\|(3) instead when using QUIC. The socket must be configured in nonblocking mode. You may or may not need to use \fBSSL_set1_initial_peer_addr\fR\|(3) to set the initial peer -address; see the \fBQUIC-SPECIFIC APIS\fR section for details. +address; see the \fBQUIC\-SPECIFIC APIS\fR section for details. .IP \(bu 4 Your application uses \fBBIO_new_ssl_connect\fR\|(3) to construct a BIO which is passed to the SSL object to provide it with network @@ -345,7 +348,7 @@ instance. Your application uses a custom BIO method to provide the SSL object with network access. .Sp -Changes needed: The custom BIO must be re-architected to have datagram +Changes needed: The custom BIO must be re\-architected to have datagram semantics. \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) must be implemented. These calls must operate in a nonblocking fashion. Optionally, implement the \&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3) methods if @@ -395,10 +398,10 @@ APIS\fR. In particular, you should use these APIs to determine the ability of a QUIC stream to receive or provide application data, not to to determine if network I/O is required. .IP \(bu 4 -Evaluate your application's use of \fBSSL_shutdown\fR\|(3) in light of the changes +Evaluate your application\*(Aqs use of \fBSSL_shutdown\fR\|(3) in light of the changes discussed in \fBCHANGES TO EXISTING APIS\fR. Depending on whether your application wishes to prioritise RFC conformance or rapid shutdown, consider using the new -\&\fBSSL_shutdown_ex\fR\|(3) API instead. See \fBQUIC-SPECIFIC APIS\fR for details. +\&\fBSSL_shutdown_ex\fR\|(3) API instead. See \fBQUIC\-SPECIFIC APIS\fR for details. .SH "RECOMMENDED USAGE IN NEW APPLICATIONS" .IX Header "RECOMMENDED USAGE IN NEW APPLICATIONS" The recommended usage in new applications varies depending on three independent @@ -408,7 +411,7 @@ Whether the application will use blocking or nonblocking I/O at the application level (configured using \fBSSL_set_blocking_mode\fR\|(3)). .Sp If the application does nonblocking I/O at the application level it can choose -to manage its own polling and event loop; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR. +to manage its own polling and event loop; see \fBAPPLICATION\-DRIVEN EVENT LOOPS\fR. .IP \(bu 4 Whether the application intends to give the QUIC implementation direct access to a network socket (e.g. via \fBBIO_s_datagram\fR\|(3)) or whether it intends to buffer @@ -423,17 +426,17 @@ Whether thread assisted mode will be used (see \fBTHREAD ASSISTED MODE\fR). Simple demos for QUIC usage under these various scenarios can be found at <https://github.com/openssl/openssl/tree/master/doc/designs/ddd>. .PP -Applications which wish to implement QUIC-specific protocols should be aware of -the APIs listed under \fBQUIC-SPECIFIC APIS\fR which provide access to -QUIC-specific functionality. For example, \fBSSL_stream_conclude\fR\|(3) can be used +Applications which wish to implement QUIC\-specific protocols should be aware of +the APIs listed under \fBQUIC\-SPECIFIC APIS\fR which provide access to +QUIC\-specific functionality. For example, \fBSSL_stream_conclude\fR\|(3) can be used to indicate the end of the sending part of a stream, and \fBSSL_shutdown_ex\fR\|(3) can be used to provide a QUIC application error code when closing a connection. .PP Regardless of the design decisions chosen above, it is recommended that new -applications avoid use of the default stream mode and use the multi-stream API +applications avoid use of the default stream mode and use the multi\-stream API by calling \fBSSL_set_default_stream_mode\fR\|(3); see the MODES OF OPERATION section for details. -.SH "QUIC-SPECIFIC APIS" +.SH "QUIC\-SPECIFIC APIS" .IX Header "QUIC-SPECIFIC APIS" This section details new APIs which are directly or indirectly related to QUIC. For details on the operation of each API, see the referenced man pages. @@ -449,7 +452,7 @@ This can also be used with DTLS and supersedes \fBDTLSv1_get_timeout\fR\|(3) for usage. .IP \fBSSL_handle_events\fR\|(3) 4 .IX Item "SSL_handle_events" -This is a non-specific I/O operation which makes a best effort attempt to +This is a non\-specific I/O operation which makes a best effort attempt to 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 @@ -465,10 +468,10 @@ The following SSL APIs are specific to QUIC: .IX Item "SSL_new_listener" 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. +in a protocol\-agnostic manner. .Sp Currently, listener SSL objects are only supported for QUIC server usage or -client-only usage. The listener interface may expand to support additional +client\-only usage. The listener interface may expand to support additional protocols in the future. .IP \fBSSL_new_listener_from\fR\|(3) 4 .IX Item "SSL_new_listener_from" @@ -489,7 +492,7 @@ to call this because it will be called automatically on the first call to \&\fBSSL_accept_connection\fR\|(3). .IP \fBSSL_accept_connection\fR\|(3) 4 .IX Item "SSL_accept_connection" -Accepts a new incoming connection for a listner SSL object. A new SSL object +Accepts a new incoming connection for a listener 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. @@ -558,7 +561,7 @@ QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving part of a stream remains usable. .IP \fBSSL_stream_reset\fR\|(3) 4 .IX Item "SSL_stream_reset" -This allows an application to indicate the non-normal termination of the sending +This allows an application to indicate the non\-normal termination of the sending part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC. .IP "\fBSSL_get_stream_write_state\fR\|(3) and \fBSSL_get_stream_read_state\fR\|(3)" 4 .IX Item "SSL_get_stream_write_state and SSL_get_stream_read_state" @@ -567,7 +570,7 @@ sending and receiving parts of a stream respectively. .IP "\fBSSL_get_stream_write_error_code\fR\|(3) and \fBSSL_get_stream_read_error_code\fR\|(3)" 4 .IX Item "SSL_get_stream_write_error_code and SSL_get_stream_read_error_code" This allows an application to determine the application error code which was -signalled by a peer which has performed a non-normal stream termination of the +signalled by a peer which has performed a non\-normal stream termination of the respective sending or receiving part of a stream, if any. .IP \fBSSL_get_conn_close_info\fR\|(3) 4 .IX Item "SSL_get_conn_close_info" @@ -589,19 +592,19 @@ Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC stream. .IP \fBSSL_new_stream\fR\|(3) 4 .IX Item "SSL_new_stream" -Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC +Creates a new QUIC stream SSL object representing a new, locally\-initiated QUIC stream. .IP \fBSSL_accept_stream\fR\|(3) 4 .IX Item "SSL_accept_stream" Potentially yields a new QUIC stream SSL object representing a new -remotely-initiated QUIC stream, blocking until one is available if the +remotely\-initiated QUIC stream, blocking until one is available if the connection is configured to do so. .IP \fBSSL_get_accept_stream_queue_len\fR\|(3) 4 .IX Item "SSL_get_accept_stream_queue_len" -Provides information on the number of pending remotely-initiated streams. +Provides information on the number of pending remotely\-initiated streams. .IP \fBSSL_set_incoming_stream_policy\fR\|(3) 4 .IX Item "SSL_set_incoming_stream_policy" -Configures how incoming, remotely-initiated streams are handled. The incoming +Configures how incoming, remotely\-initiated streams are handled. The incoming stream policy can be used to automatically reject streams created by the peer, or allow them to be handled using \fBSSL_accept_stream\fR\|(3). .IP \fBSSL_set_default_stream_mode\fR\|(3) 4 @@ -610,7 +613,7 @@ Used to configure or disable default stream mode; see the MODES OF OPERATION section for details. .PP The following BIO APIs are not specific to QUIC but have been added to -facilitate QUIC-specific requirements and are closely associated with its use: +facilitate QUIC\-specific requirements and are closely associated with its use: .IP \fBBIO_s_dgram_pair\fR\|(3) 4 .IX Item "BIO_s_dgram_pair" This is a new BIO method which is similar to a conventional BIO pair but @@ -670,13 +673,13 @@ does provide the simplest mode of usage for an application. .PP The implementation may or may not use a common thread or thread pool to service multiple SSL objects in the same \fBSSL_CTX\fR. -.SH "APPLICATION-DRIVEN EVENT LOOPS" +.SH "APPLICATION\-DRIVEN EVENT LOOPS" .IX Header "APPLICATION-DRIVEN EVENT LOOPS" -OpenSSL's QUIC implementation is designed to facilitate applications which wish +OpenSSL\*(Aqs QUIC implementation is designed to facilitate applications which wish to use the SSL APIs in a blocking fashion, but is also designed to facilitate applications which wish to use the SSL APIs in a nonblocking fashion and manage their own event loops and polling directly. This is useful when it is desirable -to host OpenSSL's QUIC implementation on top of an application's existing +to host OpenSSL\*(Aqs QUIC implementation on top of an application\*(Aqs existing nonblocking I/O infrastructure. .PP This is supported via the concept of poll descriptors; see @@ -751,6 +754,19 @@ The application must call \fBSSL_get_event_timeout\fR\|(3) after every call to \&\fBSSL_handle_events\fR\|(3) (or another I/O function on the SSL object), and ensure that a call to \fBSSL_handle_events\fR\|(3) is performed after the specified timeout (if any). +.SH "WINDOWS APPLICATION NOTES" +.IX Header "WINDOWS APPLICATION NOTES" +QUIC protocol uses UDP sockets. The \fBrecvfrom()\fR function on Windows may fail +with \f(CW\*(C`WSAECONNRESET\*(C'\fR error causing OpenSSL QUIC stack to enter permanent +error, which prevents further communication over QUIC protocol. Applications +should disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET error notification +on UDP sockets they pass to OpenSSL QUIC stack. More details can be found here: +https://learn.microsoft.com/en\-us/windows/win32/winsock/winsock\-ioctls#sio_udp_connreset\-opcode\-setting\-i\-t3 +.PP +OpenSSL attempts to always disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET +on UDP sockets it receives from application, but no error is reported back +if the respective \f(CWWSAIoctl()\fR calls fail. Robust application should set those +options itself so it can handle error notifications from \f(CWWSAIoctl()\fR properly. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), @@ -769,7 +785,7 @@ that a call to \fBSSL_handle_events\fR\|(3) is performed after the specified tim \&\fBSSL_is_domain\fR\|(3), \fBSSL_get0_domain\fR\|(3) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2022\-2026 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 |