Lines Matching +full:in +full:- +full:application

1 .\" -*- mode: troff; coding: utf-8 -*-
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
35 .\" entries marked with X<> in POD.  Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
57 .IX Title "OPENSSL-QUIC 7ossl"
58 .TH OPENSSL-QUIC 7ossl 2025-09-30 3.5.4 OpenSSL
60 .\" way too many mistakes in technical documents.
64 openssl\-quic \- OpenSSL QUIC
73 by an SSL object in the same way that a TLS connection is. Only minimal changes
75 support in. QUIC clients can use \fBOSSL_QUIC_client_method\fR\|(3) or
80 The remainder of this man page discusses, in order:
82 Default stream mode versus multi-stream mode for clients;
84 The changes to existing libssl APIs which are driven by QUIC-related
85 implementation requirements, which existing applications should bear in mind;
92 New, QUIC-specific APIs.
95 When a client creates a QUIC connection, by default, it operates in default
96 stream mode, which is intended to provide compatibility with existing non-QUIC
97 application usage patterns. In this mode, the connection has a single stream
100 client-initiated or server-initiated from a QUIC perspective depends on whether
105 instead adopt the multi-stream API. See the RECOMMENDATIONS FOR NEW APPLICATIONS
109 A QUIC client connection can be used in either default stream mode or
110 multi-stream mode. By default, a newly created QUIC connection SSL object uses
118 stream SSL object can also be called on a QUIC connection SSL object, in which
122 whether a stream is client-initiated or server-initiated. In default stream
123 mode, if a client application calls \fBSSL_read\fR\|(3) first before any call to
124 \&\fBSSL_write\fR\|(3) on the connection, it is assumed that the application protocol
125 is using a server-initiated stream, and the \fBSSL_read\fR\|(3) call will not
128 application calls \fBSSL_write\fR\|(3) before any call to \fBSSL_read\fR\|(3) on the
129 connection, it is assumed that a client-initiated stream is to be used
133 New applications adopting QUIC should use multi-stream mode, described below,
136 It is possible to use additional streams in default stream mode using
139 in order to use \fBSSL_accept_stream\fR\|(3) in this case. However, applications
140 using additional streams are strongly recommended to use multi-stream mode
146 .SS "Multi-Stream Mode"
147 .IX Subsection "Multi-Stream Mode"
148 The recommended usage mode for new applications adopting QUIC is multi-stream
149 mode, in which no default stream is attached to the QUIC connection SSL object
151 SSL object fail. Instead, an application calls \fBSSL_new_stream\fR\|(3) or
153 receiving application data using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3).
155 To use multi-stream mode, call \fBSSL_set_default_stream_mode\fR\|(3) with an
160 When multi-stream mode is used, meaning that no default stream is associated
179 \&\fBBIO_s_dgram_pair\fR\|(3) provides BIO pair-like functionality but with datagram
183 \&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO-like interface but with
186 An application may also choose to implement a custom BIO. The new
197 Traditionally, whether the application-level I/O APIs (such as \fBSSL_read\fR\|(3)
198 and \fBSSL_write\fR\|(3) operated in a blocking fashion was directly correlated with
199 whether the underlying network socket was configured in a blocking fashion. This
201 application-level blocking mode using \fBSSL_set_blocking_mode\fR\|(3). See
204 Network-level I/O must always be performed in a nonblocking manner. The
205 application can still enjoy blocking semantics for calls to application-level
208 in nonblocking mode. For application-level blocking functionality, see
218 \&\fBSSL_shutdown\fR\|(3) has significant changes in relation to how QUIC connections
219 must be shut down. In particular, applications should be advised that the full
220 RFC-conformant QUIC shutdown process may take an extended amount of time. This
221 may not be suitable for short-lived processes which should exit immediately
230 When used in nonblocking mode, \fBSSL_ERROR_WANT_READ\fR indicates that the
240 loops need to use these functions; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR for
247 Whether QUIC operates in a client or server mode is determined by the
276 Post-Handshake Client Authentication is not available as QUIC prohibits its use.
282 for QUIC, such as \fBTLS_AES_128_CCM_8_SHA256\fR. Your application may need to
290 but calls to the relevant functions are treated as no-ops:
301 A client application wishing to use QUIC must use \fBOSSL_QUIC_client_method\fR\|(3)
306 A server application wishing to use QUIC must use \fBOSSL_QUIC_server_method\fR\|(3). 
310 apply for your application:
313 Your application uses \fBBIO_s_socket\fR\|(3) to construct a BIO which is passed to
316 Changes needed: Change your application to use \fBBIO_s_datagram\fR\|(3) instead when
317 using QUIC. The socket must be configured in nonblocking mode. You may or may
319 address; see the \fBQUIC-SPECIFIC APIS\fR section for details.
321 Your application uses \fBBIO_new_ssl_connect\fR\|(3) to
328 Your application uses any other I/O strategy in this list but combines it with a
335 Your application uses a BIO pair to cause the SSL object to read and write
336 network traffic to a memory buffer. Your application manages the transmission
337 and reception of buffered data itself in a way unknown to libssl.
341 will need to modify your application to transmit and receive using a UDP socket
345 Your application uses a custom BIO method to provide the SSL object with network
348 Changes needed: The custom BIO must be re-architected to have datagram
350 calls must operate in a nonblocking fashion. Optionally, implement the
358 An application must explicitly configure whether it wishes to use the SSL APIs
361 operates in blocking or nonblocking mode. QUIC requires the use of a
362 nonblocking network BIO, therefore the blocking mode at the application level
363 can be explicitly configured by the application using the new
364 \&\fBSSL_set_blocking_mode\fR\|(3) API. The default mode is blocking. If an application
365 wishes to use the SSL object APIs at application level in a nonblocking manner,
368 If your client application does not choose to use thread assisted mode, it must
371 regularly. If the SSL object is used in blocking mode, an ongoing blocking call
373 timer events required by QUIC are handled in a timely fashion.
376 \&\fBSSL_write\fR\|(3) regularly. If an application does not do this, it should ensure
383 (such as \fBBIO_s_datagram\fR\|(3)), the application can use
390 are handled in a timely manner. See \fBTHREAD ASSISTED MODE\fR for details.
393 \&\fBSSL_want_write\fR\|(3) reflects the API changes described in \fBCHANGES TO EXISTING
394 APIS\fR. In particular, you should use these APIs to determine the ability of a
395 QUIC stream to receive or provide application data, not to to determine if
398 Evaluate your application's use of \fBSSL_shutdown\fR\|(3) in light of the changes
399 discussed in \fBCHANGES TO EXISTING APIS\fR. Depending on whether your application
401 \&\fBSSL_shutdown_ex\fR\|(3) API instead. See \fBQUIC-SPECIFIC APIS\fR for details.
402 .SH "RECOMMENDED USAGE IN NEW APPLICATIONS"
403 .IX Header "RECOMMENDED USAGE IN NEW APPLICATIONS"
404 The recommended usage in new applications varies depending on three independent
407 Whether the application will use blocking or nonblocking I/O at the application
410 If the application does nonblocking I/O at the application level it can choose
411 to manage its own polling and event loop; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR.
413 Whether the application intends to give the QUIC implementation direct access to
426 Applications which wish to implement QUIC-specific protocols should be aware of
427 the APIs listed under \fBQUIC-SPECIFIC APIS\fR which provide access to
428 QUIC-specific functionality. For example, \fBSSL_stream_conclude\fR\|(3) can be used
430 can be used to provide a QUIC application error code when closing a connection.
433 applications avoid use of the default stream mode and use the multi-stream API
436 .SH "QUIC-SPECIFIC APIS"
437 .IX Header "QUIC-SPECIFIC APIS"
452 This is a non-specific I/O operation which makes a best effort attempt to
466 Creates a listener SSL object, which differs from an ordinary SSL object in that
468 in a protocol-agnostic manner.
471 client-only usage. The listener interface may expand to support additional
472 protocols in the future.
476 \&\fIssl\fR. See \fBSSL_new_domain\fR\|(3) and \fBopenssl\-quic\-concurrency\fR\|(7) for details
494 incoming connection is available and the listener SSL object is configured in
503 also possible to use \fBSSL_new_from_listener()\fR in conjunction with a listener
510 a QUIC domain SSL object. The concept of a QUIC event domain is discussed in
511 detail in \fBopenssl\-quic\-concurrency\fR\|(7).
517 \&\fBSSL_get0_domain()\fR obtains a pointer to the QUIC domain SSL object in an SSL
521 Configures whether blocking semantics are used at the application level. This
526 These functions facilitate operation in nonblocking mode.
530 can be used to synchronise on network readability events which should result in
531 a call to \fBSSL_handle_events\fR\|(3). \fBSSL_get_wpoll_descriptor\fR\|(3) works in an
539 These functions facilitate operation in nonblocking mode and are used in
546 connection. This function must be used in the general case when creating an
548 autodetected in some cases. See \fBSSL_set1_initial_peer_addr\fR\|(3) for details.
551 This augments \fBSSL_shutdown\fR\|(3) by allowing an application error code to be
552 specified. It also allows an application to decide how quickly it wants a
556 This allows an application to indicate the normal end of the sending part of a
557 QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving
561 This allows an application to indicate the non-normal termination of the sending
562 part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC.
565 This allows an application to determine the current stream states for the
569 This allows an application to determine the application error code which was
570 signalled by a peer which has performed a non-normal stream termination of the
574 This allows an application to determine the error code which was signalled when
592 Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC
597 remotely-initiated QUIC stream, blocking until one is available if the
601 Provides information on the number of pending remotely-initiated streams.
604 Configures how incoming, remotely-initiated streams are handled. The incoming
613 facilitate QUIC-specific requirements and are closely associated with its use:
632 to be enabled in which datagrams will not be silently truncated if they are
638 \&\fBBIO_s_dgram_pair\fR\|(3). In particular, this allows an application to inform the
640 addresses in transmitted datagrams and to provide the applicable information in
652 \&\fBBIO_recvmmsg\fR\|(3) is ephemeral in nature, such as "would block" errors.
656 \&\fBOSSL_QUIC_client_thread_method\fR\|(3). In this mode, a background thread is
660 application for a long time.
663 guarantees for the public SSL API are unchanged. Therefore, an application must
669 does provide the simplest mode of usage for an application.
672 multiple SSL objects in the same \fBSSL_CTX\fR.
673 .SH "APPLICATION-DRIVEN EVENT LOOPS"
674 .IX Header "APPLICATION-DRIVEN EVENT LOOPS"
676 to use the SSL APIs in a blocking fashion, but is also designed to facilitate
677 applications which wish to use the SSL APIs in a nonblocking fashion and manage
679 to host OpenSSL's QUIC implementation on top of an application's existing
690 Broadly, an application which wishes to manage its own event loop should
712 The application should call \fBSSL_get_rpoll_descriptor\fR\|(3) and
717 whether the QUIC implementation is currently interested in readability and
720 applicable in the future.
741 If the network read and write BIOs provided were not pollable (for example, in
742 the case of \fBBIO_s_dgram_pair\fR\|(3)), the application is responsible for managing
747 call to \fBBIO_sendmmsg\fR\|(3) and the application is responsible for ensuring these
750 The application must call \fBSSL_get_event_timeout\fR\|(3) after every call to
772 Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved.
775 this file except in compliance with the License.  You can obtain a copy
776 in the file LICENSE in the source distribution or at