Lines Matching +full:4 +full:a

58 .TH OPENSSL-QUIC 7ossl 2025-09-30 3.5.4 OpenSSL
72 The QUIC protocol maps to the standard SSL API. A QUIC connection is represented
73 by an SSL object in the same way that a TLS connection is. Only minimal changes
81 .IP \(bu 4
83 .IP \(bu 4
86 .IP \(bu 4
89 .IP \(bu 4
91 .IP \(bu 4
95 When a client creates a QUIC connection, by default, it operates in default
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
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
113 In default stream mode, a stream is implicitly created and bound to the QUIC
117 When default stream mode is used, any API function which can be called on a QUIC
118 stream SSL object can also be called on a QUIC connection SSL object, in which
121 The identity of a QUIC stream, including its stream ID, varies depending on
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
125 is using a server-initiated stream, and the \fBSSL_read\fR\|(3) call will not
127 configured) until the server initiates a stream. Conversely, if the client
129 connection, it is assumed that a client-initiated stream is to be used
130 and such a stream is created automatically.
143 Calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) before a default stream
145 creation of a default stream.
158 initiating a connection.
161 with the connection, calls to API functions which are defined as operating on a
169 .IP \(bu 4
171 \&\fBSSL_set0_wbio\fR\|(3) function as before, but must now receive a BIO with datagram
172 semantics. There are broadly four options for applications to use as a network
174 .RS 4
175 .IP \(bu 4
177 \&\fBBIO_s_socket\fR\|(3) and provides a UDP socket.
178 .IP \(bu 4
180 semantics, and is recommended for existing applications which use a BIO pair or
182 .IP \(bu 4
183 \&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO-like interface but with
185 .IP \(bu 4
186 An application may also choose to implement a custom BIO. The new
189 .RS 4
191 .IP \(bu 4
193 instantiate a \fBBIO_s_socket\fR\|(3). For QUIC, these functions instead instantiate
194 a \fBBIO_s_datagram\fR\|(3). This is equivalent to instantiating a
196 .IP \(bu 4
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
203 .IP \(bu 4
204 Network-level I/O must always be performed in a nonblocking manner. The
207 network BIO provided to QUIC (such as a \fBBIO_s_datagram\fR\|(3)) must be configured
210 .IP \(bu 4
211 \&\fBBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a
214 .IP \(bu 4
217 .IP \(bu 4
222 after their usage of a QUIC connection is completed. A rapid shutdown mode
224 .IP \(bu 4
231 receive part of a QUIC stream does not currently have any more data available to
242 .IP \(bu 4
246 .IP \(bu 4
247 Whether QUIC operates in a client or server mode is determined by the
253 .IP \(bu 4
257 .IP \(bu 4
259 .RS 4
260 .IP \(bu 4
262 .IP \(bu 4
264 .IP \(bu 4
266 .IP \(bu 4
268 .IP \(bu 4
270 .IP \(bu 4
272 .IP \(bu 4
275 .IP \(bu 4
277 .IP \(bu 4
280 .IP \(bu 4
284 .IP \(bu 4
287 .RS 4
291 .IP \(bu 4
294 .RS 4
300 .IP \(bu 4
301 A client application wishing to use QUIC must use \fBOSSL_QUIC_client_method\fR\|(3)
305 .IP \(bu 4
306 A server application wishing to use QUIC must use \fBOSSL_QUIC_server_method\fR\|(3). 
308 .IP \(bu 4
311 .RS 4
312 .IP \(bu 4
313 Your application uses \fBBIO_s_socket\fR\|(3) to construct a BIO which is passed to
320 .IP \(bu 4
322 construct a BIO which is passed to the SSL object to provide it with network
325 Changes needed: No changes needed. Use of QUIC is detected automatically and a
326 datagram socket is created instead of a normal TCP socket.
327 .IP \(bu 4
328 Your application uses any other I/O strategy in this list but combines it with a
332 of such a buffer is incompatible with QUIC as QUIC requires datagram semantics
334 .IP \(bu 4
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.
339 Changes needed: Switch from using a conventional BIO pair to using
341 will need to modify your application to transmit and receive using a UDP socket
344 .IP \(bu 4
345 Your application uses a custom BIO method to provide the SSL object with network
350 calls must operate in a nonblocking fashion. Optionally, implement the
355 .RS 4
357 .IP \(bu 4
361 operates in blocking or nonblocking mode. QUIC requires the use of a
365 wishes to use the SSL object APIs at application level in a nonblocking manner,
366 it must add a call to \fBSSL_set_blocking_mode\fR\|(3) to disable blocking mode.
367 .IP \(bu 4
373 timer events required by QUIC are handled in a timely fashion.
390 are handled in a timely manner. See \fBTHREAD ASSISTED MODE\fR for details.
391 .IP \(bu 4
394 APIS\fR. In particular, you should use these APIs to determine the ability of a
397 .IP \(bu 4
406 .IP \(bu 4
412 .IP \(bu 4
414 a network socket (e.g. via \fBBIO_s_datagram\fR\|(3)) or whether it intends to buffer
415 transmitted and received datagrams via a \fBBIO_s_dgram_pair\fR\|(3) or custom BIO.
420 .IP \(bu 4
429 to indicate the end of the sending part of a stream, and \fBSSL_shutdown_ex\fR\|(3)
430 can be used to provide a QUIC application error code when closing a connection.
442 .IP \fBSSL_get_event_timeout\fR\|(3) 4
444 Determines when the QUIC implementation should next be woken up via a call to
450 .IP \fBSSL_handle_events\fR\|(3) 4
452 This is a non-specific I/O operation which makes a best effort attempt to
464 .IP \fBSSL_new_listener\fR\|(3) 4
466 Creates a listener SSL object, which differs from an ordinary SSL object in that
468 in a protocol-agnostic manner.
473 .IP \fBSSL_new_listener_from\fR\|(3) 4
475 Creates a listener SSL object which is subordinate to a QUIC domain SSL object
478 .IP \fBSSL_is_listener\fR\|(3) 4
480 Returns 1 if and only if an SSL object is a listener SSL object.
481 .IP \fBSSL_get0_listener\fR\|(3) 4
485 .IP \fBSSL_listen\fR\|(3) 4
487 Begin listening after a listener has been created. It is ordinarily not needed
490 .IP \fBSSL_accept_connection\fR\|(3) 4
492 Accepts a new incoming connection for a listner SSL object. A new SSL object
496 .IP \fBSSL_get_accept_connection_queue_len\fR\|(3) 4
500 .IP \fBSSL_new_from_listener\fR\|(3) 4
502 Creates a client connection under a given listener SSL object. For QUIC, it is
503 also possible to use \fBSSL_new_from_listener()\fR in conjunction with a listener
505 \&\fBSSL_LISTENER_FLAG_NO_ACCEPT\fR), leading to a UDP network endpoint which has
507 .IP \fBSSL_new_domain\fR\|(3) 4
509 Creates a new QUIC event domain, represented as an SSL object. This is known as
510 a QUIC domain SSL object. The concept of a QUIC event domain is discussed in
512 .IP \fBSSL_is_domain\fR\|(3) 4
514 Returns 1 if an SSL object is a QUIC domain SSL object.
515 .IP \fBSSL_get0_domain\fR\|(3) 4
517 \&\fBSSL_get0_domain()\fR obtains a pointer to the QUIC domain SSL object in an SSL
519 .IP "\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_get_blocking_mode\fR\|(3)" 4
524 .IP "\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)" 4
531 a call to \fBSSL_handle_events\fR\|(3). \fBSSL_get_wpoll_descriptor\fR\|(3) works in an
537 .IP "\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3)" 4
543 .IP \fBSSL_set1_initial_peer_addr\fR\|(3) 4
549 .IP \fBSSL_shutdown_ex\fR\|(3) 4
552 specified. It also allows an application to decide how quickly it wants a
554 .IP \fBSSL_stream_conclude\fR\|(3) 4
556 This allows an application to indicate the normal end of the sending part of a
558 part of a stream remains usable.
559 .IP \fBSSL_stream_reset\fR\|(3) 4
562 part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC.
563 .IP "\fBSSL_get_stream_write_state\fR\|(3) and \fBSSL_get_stream_read_state\fR\|(3)" 4
566 sending and receiving parts of a stream respectively.
567 .IP "\fBSSL_get_stream_write_error_code\fR\|(3) and \fBSSL_get_stream_read_error_code\fR\|(3)" 4
570 signalled by a peer which has performed a non-normal stream termination of the
571 respective sending or receiving part of a stream, if any.
572 .IP \fBSSL_get_conn_close_info\fR\|(3) 4
576 .IP \fBSSL_get0_connection\fR\|(3) 4
578 Gets the QUIC connection SSL object from a QUIC stream SSL object.
579 .IP \fBSSL_is_connection\fR\|(3) 4
581 Returns 1 if an SSL object is not a QUIC stream SSL object.
582 .IP \fBSSL_get_stream_type\fR\|(3) 4
586 .IP \fBSSL_get_stream_id\fR\|(3) 4
588 Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC
590 .IP \fBSSL_new_stream\fR\|(3) 4
592 Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC
594 .IP \fBSSL_accept_stream\fR\|(3) 4
596 Potentially yields a new QUIC stream SSL object representing a new
599 .IP \fBSSL_get_accept_stream_queue_len\fR\|(3) 4
602 .IP \fBSSL_set_incoming_stream_policy\fR\|(3) 4
607 .IP \fBSSL_set_default_stream_mode\fR\|(3) 4
614 .IP \fBBIO_s_dgram_pair\fR\|(3) 4
616 This is a new BIO method which is similar to a conventional BIO pair but
618 .IP "\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3)" 4
620 This is a new BIO API which allows a BIO to expose a poll descriptor. This API
623 .IP "\fBBIO_sendmmsg\fR\|(3), \fBBIO_recvmmsg\fR\|(3)" 4
625 This is a new BIO API which can be implemented by BIOs which implement datagram
628 .IP "\fBBIO_dgram_set_no_trunc\fR\|(3), \fBBIO_dgram_get_no_trunc\fR\|(3)" 4
634 .IP "\fBBIO_dgram_set_caps\fR\|(3), \fBBIO_dgram_get_caps\fR\|(3)" 4
636 These functions are used to allow the user of one end of a
637 \&\fBBIO_s_dgram_pair\fR\|(3) to indicate its capabilities to the other end of a
642 …\fR\|(3), \fBBIO_dgram_set_local_addr_enable\fR\|(3), \fBBIO_dgram_get_local_addr_enable\fR\|(3)" 4
644 Local addressing support refers to the ability of a BIO with datagram semantics
645 to allow a source address to be specified on transmission and to report the
646 destination address on reception. These functions can be used to determine if a
649 .IP \fBBIO_err_is_non_fatal\fR\|(3) 4
656 \&\fBOSSL_QUIC_client_thread_method\fR\|(3). In this mode, a background thread is
658 for ensuring that timeout events are handled on a timely basis even if no SSL
660 application for a long time.
671 The implementation may or may not use a common thread or thread pool to service
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
683 \&\fBBIO_get_rpoll_descriptor\fR\|(3) for details. Broadly, a \fBBIO_POLL_DESCRIPTOR\fR is
684 a structure which expresses some kind of OS resource which can be used to
685 synchronise on I/O events. The QUIC implementation provides a
692 .IP \(bu 4
695 a BIO abstracting a network socket such as \fBBIO_s_datagram\fR\|(3), or a BIO
696 abstracting some kind of memory buffer such as \fBBIO_s_dgram_pair\fR\|(3). Use of a
698 .IP \(bu 4
701 .IP \(bu 4
705 .IP \(bu 4
707 a \fBBIO_s_datagram\fR\|(3), or a custom BIO which implements
710 .RS 4
711 .IP \(bu 4
715 .IP \(bu 4
721 .IP \(bu 4
723 .RS 4
724 .IP \(bu 4
727 .IP \(bu 4
730 .IP \(bu 4
733 .RS 4
738 .RS 4
740 .IP \(bu 4
744 writes data to a \fBBIO_s_dgram_pair\fR\|(3) or otherwise takes action so that the
745 QUIC implementation can read new datagrams via a call to \fBBIO_recvmmsg\fR\|(3) on
746 the underlying network BIO. The QUIC implementation may output datagrams via a
752 that a call to \fBSSL_handle_events\fR\|(3) is performed after the specified timeout
775 this file except in compliance with the License.  You can obtain a copy