diff options
Diffstat (limited to 'upstream/archlinux/man7/openssl-quic.7ssl')
| -rw-r--r-- | upstream/archlinux/man7/openssl-quic.7ssl | 713 |
1 files changed, 713 insertions, 0 deletions
diff --git a/upstream/archlinux/man7/openssl-quic.7ssl b/upstream/archlinux/man7/openssl-quic.7ssl new file mode 100644 index 00000000..e9fa9759 --- /dev/null +++ b/upstream/archlinux/man7/openssl-quic.7ssl @@ -0,0 +1,713 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OPENSSL-QUIC 7ssl" +.TH OPENSSL-QUIC 7ssl 2024-01-30 3.2.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-quic \- OpenSSL QUIC +.SH DESCRIPTION +.IX Header "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. +.PP +QUIC functionality uses 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 +\&\fBOSSL_QUIC_client_method\fR\|(3) or \fBOSSL_QUIC_client_thread_method\fR\|(3) with +\&\fBSSL_CTX_new\fR\|(3). +.PP +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 \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 \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called +first. See the MODES OF OPERATION section for more information. +.PP +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. +.PP +The remainder of this man page discusses, in order: +.IP \(bu 4 +Default stream mode versus multi-stream mode; +.IP \(bu 4 +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, +including potential changes which may be needed. +.IP \(bu 4 +Recommended usage approaches for new applications. +.IP \(bu 4 +New, QUIC-specific APIs. +.SH "MODES OF OPERATION" +.IX Header "MODES OF OPERATION" +.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 +default stream mode. +.PP +In default stream mode, a stream is implicitly created and bound to the QUIC +connection SSL object; \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls to the QUIC +connection SSL object work by default and are mapped to that stream. +.PP +When default stream mode is used, any API function which can be called on a QUIC +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 +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 +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 +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, +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 +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" +.IX Subsection "Multi-Stream Mode" +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 +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 +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. +.SH "CHANGES TO EXISTING APIS" +.IX Header "CHANGES TO EXISTING APIS" +Most SSL APIs, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), function as they do +for TLS connections and do not have changed semantics, with some exceptions. The +changes to the semantics of existing APIs are as follows: +.IP \(bu 4 +Since QUIC uses UDP, \fBSSL_set_bio\fR\|(3), \fBSSL_set0_rbio\fR\|(3) and +\&\fBSSL_set0_wbio\fR\|(3) function as before, but must now receive a BIO with datagram +semantics. There are broadly four options for applications to use as a network +BIO: +.RS 4 +.IP \(bu 4 +\&\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 +semantics, and is recommended for existing applications which use a BIO pair or +memory BIO to manage libssl's communication with the network. +.IP \(bu 4 +\&\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 +\&\fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) APIs must be supported. +.RE +.RS 4 +.RE +.IP \(bu 4 +\&\fBSSL_set_fd\fR\|(3), \fBSSL_set_rfd\fR\|(3) and \fBSSL_set_wfd\fR\|(3) traditionally +instantiate a \fBBIO_s_socket\fR\|(3). For QUIC, these functions instead instantiate +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) +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 +\&\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 +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 +\&\fBSSL_set_blocking_mode\fR\|(3). +.IP \(bu 4 +\&\fBBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a +\&\fBBIO_s_datagram\fR\|(3) when used with QUIC, therefore applications which use this +do not need to change the BIO they use. +.IP \(bu 4 +\&\fBBIO_new_buffer_ssl_connect\fR\|(3) cannot be used with QUIC and applications must +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 +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 +\&\fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and \fBSSL_want_write\fR\|(3) no longer reflect +the I/O state of the network BIO passed to the QUIC SSL object, but instead +reflect the flow control state of the QUIC stream associated with the SSL +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 +is full. +.Sp +To determine if the QUIC implementation currently wishes to be informed of +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 +further discussion. +.IP \(bu 4 +The use of ALPN is mandatory when using QUIC. Attempts to connect without +configuring ALPN will fail. For information on how to configure ALPN, see +\&\fBSSL_set_alpn_protos\fR\|(3). +.IP \(bu 4 +Whether QUIC operates in a client or server mode is determined by the +\&\fBSSL_METHOD\fR used, rather than by calls to \fBSSL_set_connect_state\fR\|(3) or +\&\fBSSL_set_accept_state\fR\|(3). It is not necessary to call either of +\&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state\fR\|(3) before connecting, but +if either of these are called, the function called must be congruent with the +\&\fBSSL_METHOD\fR being used. Currently, only client mode is supported. +.IP \(bu 4 +The \fBSSL_set_min_proto_version\fR\|(3) and \fBSSL_set_max_proto_version\fR\|(3) APIs are +not used and the values passed to them are ignored, as OpenSSL QUIC currently +always uses TLS 1.3. +.IP \(bu 4 +The following libssl functionality is not available when used with QUIC. +.RS 4 +.IP \(bu 4 +Async functionality +.IP \(bu 4 +\&\fBSSL_MODE_AUTO_RETRY\fR +.IP \(bu 4 +Record Padding and Fragmentation (\fBSSL_set_block_padding\fR\|(3), etc.) +.IP \(bu 4 +\&\fBSSL_stateless\fR\|(3) support +.IP \(bu 4 +SRTP functionality +.IP \(bu 4 +TLSv1.3 Early Data +.IP \(bu 4 +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. +.IP \(bu 4 +QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant +to older TLS versions is not available. +.IP \(bu 4 +Some cipher suites which are generally available for TLSv1.3 are not available +for QUIC, such as \fBTLS_AES_128_CCM_8_SHA256\fR. Your application may need to +adjust the list of acceptable cipher suites it passes to libssl. +.IP \(bu 4 +CCM mode is not currently supported. +.RE +.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: +.IP \(bu 4 +Readahead (\fBSSL_set_read_ahead\fR\|(3), etc.) +.RE +.RS 4 +.RE +.SH "CONSIDERATIONS FOR EXISTING APPLICATIONS" +.IX Header "CONSIDERATIONS FOR EXISTING APPLICATIONS" +Existing applications seeking to adopt QUIC should apply the following list to +determine what changes they will need to make: +.IP \(bu 4 +An application wishing to use QUIC must use \fBOSSL_QUIC_client_method\fR\|(3) or +\&\fBOSSL_QUIC_client_thread_method\fR\|(3) as its SSL method. For more information +on the differences between these two methods, see \fBTHREAD ASSISTED MODE\fR. +.IP \(bu 4 +Determine how to provide QUIC with network access. Determine which of the below +apply for your application: +.RS 4 +.IP \(bu 4 +Your application uses \fBBIO_s_socket\fR\|(3) to construct a BIO which is passed to +the SSL object to provide it with network access. +.Sp +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. +.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 +access. +.Sp +Changes needed: No changes needed. Use of QUIC is detected automatically and a +datagram socket is created instead of a normal TCP socket. +.IP \(bu 4 +Your application uses any other I/O strategy in this list but combines it with a +\&\fBBIO_f_buffer\fR\|(3), for example using \fBBIO_push\fR\|(3). +.Sp +Changes needed: Disable the usage of \fBBIO_f_buffer\fR\|(3) when using QUIC. Usage +of such a buffer is incompatible with QUIC as QUIC requires datagram semantics +in its interaction with the network. +.IP \(bu 4 +Your application uses a BIO pair to cause the SSL object to read and write +network traffic to a memory buffer. Your application manages the transmission +and reception of buffered data itself in a way unknown to libssl. +.Sp +Changes needed: Switch from using a conventional BIO pair to using +\&\fBBIO_s_dgram_pair\fR\|(3) instead, which has the necessary datagram semantics. You +will need to modify your application to transmit and receive using a UDP socket +and to use datagram semantics when interacting with the \fBBIO_s_dgram_pair\fR\|(3) +instance. +.IP \(bu 4 +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 +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 +desired. Implementing these methods is required if blocking semantics at the SSL +API level are desired. +.RE +.RS 4 +.RE +.IP \(bu 4 +An application must explicitly configure whether it wishes to use the SSL APIs +in blocking mode or not. Traditionally, an SSL object has automatically operated +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 +\&\fBSSL_set_blocking_mode\fR\|(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 \fBSSL_set_blocking_mode\fR\|(3) to disable blocking mode. +.IP \(bu 4 +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, \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3)), or the new function \fBSSL_handle_events\fR\|(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. +.Sp +Most applications will service the SSL object by calling \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3) regularly. If an application does not do this, it should ensure +that \fBSSL_handle_events\fR\|(3) is called regularly. +.Sp +\&\fBSSL_get_event_timeout\fR\|(3) can be used to determine when +\&\fBSSL_handle_events\fR\|(3) must next be called. +.Sp +If the SSL object is being used with an underlying network BIO which is pollable +(such as \fBBIO_s_datagram\fR\|(3)), the application can use +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) to obtain +resources which can be used to determine when \fBSSL_handle_events\fR\|(3) should be +called due to network I/O. +.Sp +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 \fBTHREAD ASSISTED MODE\fR for details. +.IP \(bu 4 +Ensure that your usage of \fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and +\&\fBSSL_want_write\fR\|(3) reflects the API changes described in \fBCHANGES TO EXISTING +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 +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. +.SH "RECOMMENDED USAGE IN NEW APPLICATIONS" +.IX Header "RECOMMENDED USAGE IN NEW APPLICATIONS" +The recommended usage in new applications varies depending on three independent +design decisions: +.IP \(bu 4 +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. +.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 +transmitted and received datagrams via a \fBBIO_s_dgram_pair\fR\|(3) or custom BIO. +.Sp +The former is preferred where possible as it reduces latency to the network, +which enables QUIC to achieve higher performance and more accurate connection +round trip time (RTT) estimation. +.IP \(bu 4 +Whether thread assisted mode will be used (see \fBTHREAD ASSISTED MODE\fR). +.PP +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 +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 +by calling \fBSSL_set_default_stream_mode\fR\|(3); see the MODES OF OPERATION section +for details. +.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. +.PP +The following SSL APIs are new but relevant to both QUIC and DTLS: +.IP \fBSSL_get_event_timeout\fR\|(3) 4 +.IX Item "SSL_get_event_timeout" +Determines when the QUIC implementation should next be woken up via a call to +\&\fBSSL_handle_events\fR\|(3) (or another I/O function such as \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3)), if ever. +.Sp +This can also be used with DTLS and supersedes \fBDTLSv1_get_timeout\fR\|(3) for new +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 +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 \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(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. +.Sp +This can also be used with DTLS and supersedes \fBDTLSv1_handle_timeout\fR\|(3) for +new usage. +.PP +The following SSL APIs are specific to QUIC: +.IP "\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_get_blocking_mode\fR\|(3)" 4 +.IX Item "SSL_set_blocking_mode, SSL_get_blocking_mode" +Configures whether blocking semantics are used at the application level. This +determines whether calls to functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) +will block. +.IP "\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)" 4 +.IX Item "SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor" +These functions facilitate operation in nonblocking mode. +.Sp +When an SSL object is being used with an underlying network read BIO which +supports polling, \fBSSL_get_rpoll_descriptor\fR\|(3) outputs an OS resource which +can be used to synchronise on network readability events which should result in +a call to \fBSSL_handle_events\fR\|(3). \fBSSL_get_wpoll_descriptor\fR\|(3) works in an +analogous fashion for the underlying network write BIO. +.Sp +The poll descriptors provided by these functions need only be used when +\&\fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) return 1, respectively. +.IP "\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3)" 4 +.IX Item "SSL_net_read_desired, SSL_net_write_desired" +These functions facilitate operation in nonblocking mode and are used in +conjunction with \fBSSL_get_rpoll_descriptor\fR\|(3) and +\&\fBSSL_get_wpoll_descriptor\fR\|(3) respectively. They determine whether the +respective poll descriptor is currently relevant for the purposes of polling. +.IP \fBSSL_set1_initial_peer_addr\fR\|(3) 4 +.IX Item "SSL_set1_initial_peer_addr" +This function can be used to set the initial peer address for an outgoing QUIC +connection. This function must be used in the general case when creating an +outgoing QUIC connection; however, the correct initial peer address can be +autodetected in some cases. See \fBSSL_set1_initial_peer_addr\fR\|(3) for details. +.IP \fBSSL_shutdown_ex\fR\|(3) 4 +.IX Item "SSL_shutdown_ex" +This augments \fBSSL_shutdown\fR\|(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. +.IP \fBSSL_stream_conclude\fR\|(3) 4 +.IX Item "SSL_stream_conclude" +This allows an application to indicate the normal end of the sending part of a +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 +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" +This allows an application to determine the current stream states for the +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 +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" +This allows an application to determine the error code which was signalled when +the local or remote endpoint terminated the QUIC connection. +.IP \fBSSL_get0_connection\fR\|(3) 4 +.IX Item "SSL_get0_connection" +Gets the QUIC connection SSL object from a QUIC stream SSL object. +.IP \fBSSL_is_connection\fR\|(3) 4 +.IX Item "SSL_is_connection" +Returns 1 if a SSL object is not a QUIC stream SSL object. +.IP \fBSSL_get_stream_type\fR\|(3) 4 +.IX Item "SSL_get_stream_type" +Provides information on the kind of QUIC stream which is attached +to the SSL object. +.IP \fBSSL_get_stream_id\fR\|(3) 4 +.IX Item "SSL_get_stream_id" +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 +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 +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. +.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 +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 +.IX Item "SSL_set_default_stream_mode" +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: +.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 +provides datagram semantics. +.IP "\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3)" 4 +.IX Item "BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor" +This is a new BIO API which allows a BIO to expose a poll descriptor. This API +is used to implement the corresponding SSL APIs \fBSSL_get_rpoll_descriptor\fR\|(3) +and \fBSSL_get_wpoll_descriptor\fR\|(3). +.IP "\fBBIO_sendmmsg\fR\|(3), \fBBIO_recvmmsg\fR\|(3)" 4 +.IX Item "BIO_sendmmsg, BIO_recvmmsg" +This is a new BIO API which can be implemented by BIOs which implement datagram +semantics. It is implemented by \fBBIO_s_datagram\fR\|(3) and \fBBIO_s_dgram_pair\fR\|(3). +It is used by the QUIC implementation to send and receive UDP datagrams. +.IP "\fBBIO_dgram_set_no_trunc\fR\|(3), \fBBIO_dgram_get_no_trunc\fR\|(3)" 4 +.IX Item "BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc" +By default, \fBBIO_s_dgram_pair\fR\|(3) has semantics comparable to those of Berkeley +sockets being used with datagram semantics. This allows an alternative mode +to be enabled in which datagrams will not be silently truncated if they are +too large. +.IP "\fBBIO_dgram_set_caps\fR\|(3), \fBBIO_dgram_get_caps\fR\|(3)" 4 +.IX Item "BIO_dgram_set_caps, BIO_dgram_get_caps" +These functions are used to allow the user of one end of a +\&\fBBIO_s_dgram_pair\fR\|(3) to indicate its capabilities to the other end of a +\&\fBBIO_s_dgram_pair\fR\|(3). In particular, this allows an application to inform the +QUIC implementation of whether it is prepared to handle local and/or peer +addresses in transmitted datagrams and to provide the applicable information in +received datagrams. +.IP "\fBBIO_dgram_get_local_addr_cap\fR\|(3), \fBBIO_dgram_set_local_addr_enable\fR\|(3), \fBBIO_dgram_get_local_addr_enable\fR\|(3)" 4 +.IX Item "BIO_dgram_get_local_addr_cap, BIO_dgram_set_local_addr_enable, BIO_dgram_get_local_addr_enable" +Local addressing support refers to the ability of a BIO with datagram semantics +to allow a source address to be specified on transmission and to report the +destination address on reception. These functions can be used to determine if a +BIO can support local addressing and to enable local addressing support if it +can. +.IP \fBBIO_err_is_non_fatal\fR\|(3) 4 +.IX Item "BIO_err_is_non_fatal" +This is used to determine if an error while calling \fBBIO_sendmmsg\fR\|(3) or +\&\fBBIO_recvmmsg\fR\|(3) is ephemeral in nature, such as "would block" errors. +.SH "THREAD ASSISTED MODE" +.IX Header "THREAD ASSISTED MODE" +The optional thread assisted mode can be used with +\&\fBOSSL_QUIC_client_thread_method\fR\|(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 +I/O function such as \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called by the +application for a long time. +.PP +All necessary locking is handled automatically internally, but the thread safety +guarantees for the public SSL API are unchanged. Therefore, an application must +still do its own locking if it wishes to make concurrent use of the public SSL +APIs. +.PP +Because this method relies on threads, it is not available on platforms where +threading support is not available or not supported by OpenSSL. However, it +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" +.IX Header "APPLICATION-DRIVEN EVENT LOOPS" +OpenSSL's 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 +nonblocking I/O infrastructure. +.PP +This is supported via the concept of poll descriptors; see +\&\fBBIO_get_rpoll_descriptor\fR\|(3) for details. Broadly, a \fBBIO_POLL_DESCRIPTOR\fR is +a structure which expresses some kind of OS resource which can be used to +synchronise on I/O events. The QUIC implementation provides a +\&\fBBIO_POLL_DESCRIPTOR\fR based on the poll descriptor provided by the underlying +network BIO. This is typically an OS socket handle, though custom BIOs could +choose to implement their own custom poll descriptor format. +.PP +Broadly, an application which wishes to manage its own event loop should +interact with the SSL object as follows: +.IP \(bu 4 +It should provide read and write BIOs with nonblocking datagram semantics to +the SSL object using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). This could be +a BIO abstracting a network socket such as \fBBIO_s_datagram\fR\|(3), or a BIO +abstracting some kind of memory buffer such as \fBBIO_s_dgram_pair\fR\|(3). Use of a +custom BIO is also possible. +.IP \(bu 4 +It should configure the SSL object into nonblocking mode by calling +\&\fBSSL_set_blocking_mode\fR\|(3). +.IP \(bu 4 +It should configure the SSL object as desired, set an initial peer as needed +using \fBSSL_set1_initial_peer_addr\fR\|(3), and trigger the connection process by +calling \fBSSL_connect\fR\|(3). +.IP \(bu 4 +If the network read and write BIOs provided were pollable (for example, +a \fBBIO_s_datagram\fR\|(3), or a custom BIO which implements +\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3)), it should +perform the following steps repeatedly: +.RS 4 +.IP \(bu 4 +The application should call \fBSSL_get_rpoll_descriptor\fR\|(3) and +\&\fBSSL_get_wpoll_descriptor\fR\|(3) to identify OS resources which can be used for +synchronisation. +.IP \(bu 4 +It should call \fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) to determine +whether the QUIC implementation is currently interested in readability and +writability events on the underlying network BIO which was provided, and call +\&\fBSSL_get_event_timeout\fR\|(3) to determine if any timeout event will become +applicable in the future. +.IP \(bu 4 +It should wait until one of the following events occurs: +.RS 4 +.IP \(bu 4 +The poll descriptor returned by \fBSSL_get_rpoll_descriptor\fR\|(3) becomes readable +(if \fBSSL_net_read_desired\fR\|(3) returned 1); +.IP \(bu 4 +The poll descriptor returned by \fBSSL_get_wpoll_descriptor\fR\|(3) becomes writable +(if \fBSSL_net_write_desired\fR\|(3) returned 1); +.IP \(bu 4 +The timeout returned by \fBSSL_get_event_timeout\fR\|(3) (if any) expires. +.RE +.RS 4 +.Sp +Once any of these events occurs, \fBSSL_handle_events\fR\|(3) should be called. +.RE +.RE +.RS 4 +.RE +.IP \(bu 4 +If the network read and write BIOs provided were not pollable (for example, in +the case of \fBBIO_s_dgram_pair\fR\|(3)), the application is responsible for managing +and synchronising network I/O. It should call \fBSSL_handle_events\fR\|(3) after it +writes data to a \fBBIO_s_dgram_pair\fR\|(3) or otherwise takes action so that the +QUIC implementation can read new datagrams via a call to \fBBIO_recvmmsg\fR\|(3) on +the underlying network BIO. The QUIC implementation may output datagrams via a +call to \fBBIO_sendmmsg\fR\|(3) and the application is responsible for ensuring these +are transmitted. +.Sp +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 "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), +\&\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3), +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3), +\&\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_shutdown_ex\fR\|(3), +\&\fBSSL_set1_initial_peer_addr\fR\|(3), \fBSSL_stream_conclude\fR\|(3), +\&\fBSSL_stream_reset\fR\|(3), \fBSSL_get_stream_read_state\fR\|(3), +\&\fBSSL_get_stream_read_error_code\fR\|(3), \fBSSL_get_conn_close_info\fR\|(3), +\&\fBSSL_get0_connection\fR\|(3), \fBSSL_get_stream_type\fR\|(3), \fBSSL_get_stream_id\fR\|(3), +\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), +\&\fBSSL_set_incoming_stream_policy\fR\|(3), \fBSSL_set_default_stream_mode\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 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 +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |