Lines Matching +full:3 +full:a

14 The QUIC protocol maps to the standard SSL API. A QUIC connection is represented
15 by an SSL object in the same way that a TLS connection is. Only minimal changes
17 support in. QUIC clients can use L<OSSL_QUIC_client_method(3)> or
18 L<OSSL_QUIC_client_thread_method(3)> with L<SSL_CTX_new(3)>. See below for more
20 option: SSL method L<OSSL_QUIC_server_method(3)> with L<SSL_CTX_new(3)>.
52 When a client creates a QUIC connection, by default, it operates in default
54 application usage patterns. In this mode, the connection has a single stream
55 associated with it. Calls to L<SSL_read(3)> and L<SSL_write(3)> on the QUIC
57 client-initiated or server-initiated from a QUIC perspective depends on whether
58 L<SSL_read(3)> or L<SSL_write(3)> is called first.
67 A QUIC client connection can be used in either default stream mode or
68 multi-stream mode. By default, a newly created QUIC connection SSL object uses
71 In default stream mode, a stream is implicitly created and bound to the QUIC
72 connection SSL object; L<SSL_read(3)> and L<SSL_write(3)> calls to the QUIC
75 When default stream mode is used, any API function which can be called on a QUIC
76 stream SSL object can also be called on a QUIC connection SSL object, in which
79 The identity of a QUIC stream, including its stream ID, varies depending on
80 whether a stream is client-initiated or server-initiated. In default stream
81 mode, if a client application calls L<SSL_read(3)> first before any call to
82 L<SSL_write(3)> on the connection, it is assumed that the application protocol
83 is using a server-initiated stream, and the L<SSL_read(3)> call will not
85 configured) until the server initiates a stream. Conversely, if the client
86 application calls L<SSL_write(3)> before any call to L<SSL_read(3)> on the
87 connection, it is assumed that a client-initiated stream is to be used
88 and such a stream is created automatically.
95 L<SSL_new_stream(3)> and L<SSL_accept_stream(3)>; note that the default incoming
96 stream policy will need to be changed using L<SSL_set_incoming_stream_policy(3)>
97 in order to use L<SSL_accept_stream(3)> in this case. However, applications
101 Calling L<SSL_new_stream(3)> or L<SSL_accept_stream(3)> before a default stream
103 creation of a default stream.
109 and attempts to call L<SSL_read(3)> and L<SSL_write(3)> on the QUIC connection
110 SSL object fail. Instead, an application calls L<SSL_new_stream(3)> or
111 L<SSL_accept_stream(3)> to create individual stream SSL objects for sending and
112 receiving application data using L<SSL_read(3)> and L<SSL_write(3)>.
114 To use multi-stream mode, call L<SSL_set_default_stream_mode(3)> with an
117 initiating a connection.
120 with the connection, calls to API functions which are defined as operating on a
122 such as L<SSL_write(3)> or L<SSL_get_stream_id(3)> will fail.
126 Most SSL APIs, such as L<SSL_read(3)> and L<SSL_write(3)>, function as they do
134 Since QUIC uses UDP, L<SSL_set_bio(3)>, L<SSL_set0_rbio(3)> and
135 L<SSL_set0_wbio(3)> function as before, but must now receive a BIO with datagram
136 semantics. There are broadly four options for applications to use as a network
143 L<BIO_s_datagram(3)>, recommended for most applications, replaces
144 L<BIO_s_socket(3)> and provides a UDP socket.
148 L<BIO_s_dgram_pair(3)> provides BIO pair-like functionality but with datagram
149 semantics, and is recommended for existing applications which use a BIO pair or
154 L<BIO_s_dgram_mem(3)> provides a simple memory BIO-like interface but with
155 datagram semantics. Unlike L<BIO_s_dgram_pair(3)>, it is unidirectional.
159 An application may also choose to implement a custom BIO. The new
160 L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> APIs must be supported.
166 L<SSL_set_fd(3)>, L<SSL_set_rfd(3)> and L<SSL_set_wfd(3)> traditionally
167 instantiate a L<BIO_s_socket(3)>. For QUIC, these functions instead instantiate
168 a L<BIO_s_datagram(3)>. This is equivalent to instantiating a
169 L<BIO_s_datagram(3)> and using L<SSL_set0_rbio(3)> and L<SSL_set0_wbio(3)>.
173 Traditionally, whether the application-level I/O APIs (such as L<SSL_read(3)>
174 and L<SSL_write(3)> operated in a blocking fashion was directly correlated with
175 whether the underlying network socket was configured in a blocking fashion. This
177 application-level blocking mode using L<SSL_set_blocking_mode(3)>. See
178 L<SSL_set_blocking_mode(3)> for details.
182 Network-level I/O must always be performed in a nonblocking manner. The
184 I/O functions such as L<SSL_read(3)> and L<SSL_write(3)>, but the underlying
185 network BIO provided to QUIC (such as a L<BIO_s_datagram(3)>) must be configured
187 L<SSL_set_blocking_mode(3)>.
191 L<BIO_new_ssl_connect(3)> has been changed to automatically use a
192 L<BIO_s_datagram(3)> when used with QUIC, therefore applications which use this
197 L<BIO_new_buffer_ssl_connect(3)> cannot be used with QUIC and applications must
198 change to use L<BIO_new_ssl_connect(3)> instead.
202 L<SSL_shutdown(3)> has significant changes in relation to how QUIC connections
206 after their usage of a QUIC connection is completed. A rapid shutdown mode
207 is available for such applications. For details, see L<SSL_shutdown(3)>.
211 L<SSL_want(3)>, L<SSL_want_read(3)> and L<SSL_want_write(3)> no longer reflect
217 receive part of a QUIC stream does not currently have any more data available to
222 incoming network datagrams, use the new function L<SSL_net_read_desired(3)>;
225 L<SSL_net_write_desired(3)>. Only applications which wish to manage their own event
233 L<SSL_set_alpn_protos(3)>.
237 Whether QUIC operates in a client or server mode is determined by the
238 B<SSL_METHOD> used, rather than by calls to L<SSL_set_connect_state(3)> or
239 L<SSL_set_accept_state(3)>. It is not necessary to call either of
240 L<SSL_set_connect_state(3)> or L<SSL_set_accept_state(3)> before connecting, but
246 The L<SSL_set_min_proto_version(3)> and L<SSL_set_max_proto_version(3)> APIs are
266 Record Padding and Fragmentation (L<SSL_set_block_padding(3)>, etc.)
270 L<SSL_stateless(3)> support
278 TLSv1.3 Early Data
291 QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant
296 Some cipher suites which are generally available for TLSv1.3 are not available
313 Readahead (L<SSL_set_read_ahead(3)>, etc.)
328 A client application wishing to use QUIC must use L<OSSL_QUIC_client_method(3)>
329 or L<OSSL_QUIC_client_thread_method(3)> as its SSL method. For more information
335 A server application wishing to use QUIC must use L<OSSL_QUIC_server_method(3)>. 
336 The server can then accept new connections with L<SSL_accept_connection(3)>.
347 Your application uses L<BIO_s_socket(3)> to construct a BIO which is passed to
350 Changes needed: Change your application to use L<BIO_s_datagram(3)> instead when
352 not need to use L<SSL_set1_initial_peer_addr(3)> to set the initial peer
357 Your application uses L<BIO_new_ssl_connect(3)> to
358 construct a BIO which is passed to the SSL object to provide it with network
361 Changes needed: No changes needed. Use of QUIC is detected automatically and a
362 datagram socket is created instead of a normal TCP socket.
366 Your application uses any other I/O strategy in this list but combines it with a
367 L<BIO_f_buffer(3)>, for example using L<BIO_push(3)>.
369 Changes needed: Disable the usage of L<BIO_f_buffer(3)> when using QUIC. Usage
370 of such a buffer is incompatible with QUIC as QUIC requires datagram semantics
375 Your application uses a BIO pair to cause the SSL object to read and write
376 network traffic to a memory buffer. Your application manages the transmission
377 and reception of buffered data itself in a way unknown to libssl.
379 Changes needed: Switch from using a conventional BIO pair to using
380 L<BIO_s_dgram_pair(3)> instead, which has the necessary datagram semantics. You
381 will need to modify your application to transmit and receive using a UDP socket
382 and to use datagram semantics when interacting with the L<BIO_s_dgram_pair(3)>
387 Your application uses a custom BIO method to provide the SSL object with network
391 semantics. L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> must be implemented. These
392 calls must operate in a nonblocking fashion. Optionally, implement the
393 L<BIO_get_rpoll_descriptor(3)> and L<BIO_get_wpoll_descriptor(3)> methods if
404 operates in blocking or nonblocking mode. QUIC requires the use of a
407 L<SSL_set_blocking_mode(3)> API. The default mode is blocking. If an application
408 wishes to use the SSL object APIs at application level in a nonblocking manner,
409 it must add a call to L<SSL_set_blocking_mode(3)> to disable blocking mode.
415 L<SSL_read(3)> or L<SSL_write(3)>), or the new function L<SSL_handle_events(3)>,
418 timer events required by QUIC are handled in a timely fashion.
420 Most applications will service the SSL object by calling L<SSL_read(3)> or
421 L<SSL_write(3)> regularly. If an application does not do this, it should ensure
422 that L<SSL_handle_events(3)> is called regularly.
424 L<SSL_get_event_timeout(3)> can be used to determine when
425 L<SSL_handle_events(3)> must next be called.
428 (such as L<BIO_s_datagram(3)>), the application can use
429 L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> to obtain
430 resources which can be used to determine when L<SSL_handle_events(3)> should be
435 are handled in a timely manner. See B<THREAD ASSISTED MODE> for details.
439 Ensure that your usage of L<SSL_want(3)>, L<SSL_want_read(3)> and
440 L<SSL_want_write(3)> reflects the API changes described in B<CHANGES TO EXISTING
441 APIS>. In particular, you should use these APIs to determine the ability of a
447 Evaluate your application's use of L<SSL_shutdown(3)> in light of the changes
450 L<SSL_shutdown_ex(3)> API instead. See B<QUIC-SPECIFIC APIS> for details.
464 level (configured using L<SSL_set_blocking_mode(3)>).
472 a network socket (e.g. via L<BIO_s_datagram(3)>) or whether it intends to buffer
473 transmitted and received datagrams via a L<BIO_s_dgram_pair(3)> or custom BIO.
490 QUIC-specific functionality. For example, L<SSL_stream_conclude(3)> can be used
491 to indicate the end of the sending part of a stream, and L<SSL_shutdown_ex(3)>
492 can be used to provide a QUIC application error code when closing a connection.
496 by calling L<SSL_set_default_stream_mode(3)>; see the MODES OF OPERATION section
508 =item L<SSL_get_event_timeout(3)>
510 Determines when the QUIC implementation should next be woken up via a call to
511 L<SSL_handle_events(3)> (or another I/O function such as L<SSL_read(3)> or
512 L<SSL_write(3)>), if ever.
514 This can also be used with DTLS and supersedes L<DTLSv1_get_timeout(3)> for new
517 =item L<SSL_handle_events(3)>
519 This is a non-specific I/O operation which makes a best effort attempt to
523 functions on an SSL object, such as L<SSL_read(3)> and L<SSL_write(3)>,
527 This can also be used with DTLS and supersedes L<DTLSv1_handle_timeout(3)> for
536 =item L<SSL_new_listener(3)>
538 Creates a listener SSL object, which differs from an ordinary SSL object in that
540 in a protocol-agnostic manner.
546 =item L<SSL_new_listener_from(3)>
548 Creates a listener SSL object which is subordinate to a QUIC domain SSL object
549 I<ssl>. See L<SSL_new_domain(3)> and L<openssl-quic-concurrency(7)> for details
552 =item L<SSL_is_listener(3)>
554 Returns 1 if and only if an SSL object is a listener SSL object.
556 =item L<SSL_get0_listener(3)>
561 =item L<SSL_listen(3)>
563 Begin listening after a listener has been created. It is ordinarily not needed
565 L<SSL_accept_connection(3)>. 
567 =item L<SSL_accept_connection(3)>
569 Accepts a new incoming connection for a listner SSL object. A new SSL object
574 =item L<SSL_get_accept_connection_queue_len(3)>
579 =item L<SSL_new_from_listener(3)>
581 Creates a client connection under a given listener SSL object. For QUIC, it is
582 also possible to use SSL_new_from_listener() in conjunction with a listener
584 B<SSL_LISTENER_FLAG_NO_ACCEPT>), leading to a UDP network endpoint which has
587 =item L<SSL_new_domain(3)>
589 Creates a new QUIC event domain, represented as an SSL object. This is known as
590 a QUIC domain SSL object. The concept of a QUIC event domain is discussed in
593 =item L<SSL_is_domain(3)>
595 Returns 1 if an SSL object is a QUIC domain SSL object.
597 =item L<SSL_get0_domain(3)>
599 SSL_get0_domain() obtains a pointer to the QUIC domain SSL object in an SSL
602 =item L<SSL_set_blocking_mode(3)>, L<SSL_get_blocking_mode(3)>
605 determines whether calls to functions such as L<SSL_read(3)> and L<SSL_write(3)>
608 =item L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>
613 supports polling, L<SSL_get_rpoll_descriptor(3)> outputs an OS resource which
615 a call to L<SSL_handle_events(3)>. L<SSL_get_wpoll_descriptor(3)> works in an
619 L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> return 1,
622 =item L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)>
625 conjunction with L<SSL_get_rpoll_descriptor(3)> and
626 L<SSL_get_wpoll_descriptor(3)> respectively. They determine whether the
629 =item L<SSL_set1_initial_peer_addr(3)>
634 autodetected in some cases. See L<SSL_set1_initial_peer_addr(3)> for details.
636 =item L<SSL_shutdown_ex(3)>
638 This augments L<SSL_shutdown(3)> by allowing an application error code to be
639 specified. It also allows an application to decide how quickly it wants a
642 =item L<SSL_stream_conclude(3)>
644 This allows an application to indicate the normal end of the sending part of a
646 part of a stream remains usable.
648 =item L<SSL_stream_reset(3)>
651 part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC.
653 =item L<SSL_get_stream_write_state(3)> and L<SSL_get_stream_read_state(3)>
656 sending and receiving parts of a stream respectively.
658 =item L<SSL_get_stream_write_error_code(3)> and L<SSL_get_stream_read_error_code(3)>
661 signalled by a peer which has performed a non-normal stream termination of the
662 respective sending or receiving part of a stream, if any.
664 =item L<SSL_get_conn_close_info(3)>
669 =item L<SSL_get0_connection(3)>
671 Gets the QUIC connection SSL object from a QUIC stream SSL object.
673 =item L<SSL_is_connection(3)>
675 Returns 1 if an SSL object is not a QUIC stream SSL object.
677 =item L<SSL_get_stream_type(3)>
682 =item L<SSL_get_stream_id(3)>
684 Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC
687 =item L<SSL_new_stream(3)>
689 Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC
692 =item L<SSL_accept_stream(3)>
694 Potentially yields a new QUIC stream SSL object representing a new
698 =item L<SSL_get_accept_stream_queue_len(3)>
702 =item L<SSL_set_incoming_stream_policy(3)>
706 or allow them to be handled using L<SSL_accept_stream(3)>.
708 =item L<SSL_set_default_stream_mode(3)>
720 =item L<BIO_s_dgram_pair(3)>
722 This is a new BIO method which is similar to a conventional BIO pair but
725 =item L<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)>
727 This is a new BIO API which allows a BIO to expose a poll descriptor. This API
728 is used to implement the corresponding SSL APIs L<SSL_get_rpoll_descriptor(3)>
729 and L<SSL_get_wpoll_descriptor(3)>.
731 =item L<BIO_sendmmsg(3)>, L<BIO_recvmmsg(3)>
733 This is a new BIO API which can be implemented by BIOs which implement datagram
734 semantics. It is implemented by L<BIO_s_datagram(3)> and L<BIO_s_dgram_pair(3)>.
737 =item L<BIO_dgram_set_no_trunc(3)>, L<BIO_dgram_get_no_trunc(3)>
739 By default, L<BIO_s_dgram_pair(3)> has semantics comparable to those of Berkeley
744 =item L<BIO_dgram_set_caps(3)>, L<BIO_dgram_get_caps(3)>
746 These functions are used to allow the user of one end of a
747 L<BIO_s_dgram_pair(3)> to indicate its capabilities to the other end of a
748 L<BIO_s_dgram_pair(3)>. In particular, this allows an application to inform the
753 =item L<BIO_dgram_get_local_addr_cap(3)>, L<BIO_dgram_set_local_addr_enable(3)>,
754 L<BIO_dgram_get_local_addr_enable(3)>
756 Local addressing support refers to the ability of a BIO with datagram semantics
757 to allow a source address to be specified on transmission and to report the
758 destination address on reception. These functions can be used to determine if a
762 =item L<BIO_err_is_non_fatal(3)>
764 This is used to determine if an error while calling L<BIO_sendmmsg(3)> or
765 L<BIO_recvmmsg(3)> is ephemeral in nature, such as "would block" errors.
772 L<OSSL_QUIC_client_thread_method(3)>. In this mode, a background thread is
774 for ensuring that timeout events are handled on a timely basis even if no SSL
775 I/O function such as L<SSL_read(3)> or L<SSL_write(3)> is called by the
776 application for a long time.
787 The implementation may or may not use a common thread or thread pool to service
793 to use the SSL APIs in a blocking fashion, but is also designed to facilitate
794 applications which wish to use the SSL APIs in a nonblocking fashion and manage
800 L<BIO_get_rpoll_descriptor(3)> for details. Broadly, a B<BIO_POLL_DESCRIPTOR> is
801 a structure which expresses some kind of OS resource which can be used to
802 synchronise on I/O events. The QUIC implementation provides a
815 the SSL object using L<SSL_set0_rbio(3)> and L<SSL_set0_wbio(3)>. This could be
816 a BIO abstracting a network socket such as L<BIO_s_datagram(3)>, or a BIO
817 abstracting some kind of memory buffer such as L<BIO_s_dgram_pair(3)>. Use of a
823 L<SSL_set_blocking_mode(3)>.
828 using L<SSL_set1_initial_peer_addr(3)>, and trigger the connection process by
829 calling L<SSL_connect(3)>.
834 a L<BIO_s_datagram(3)>, or a custom BIO which implements
835 L<BIO_get_rpoll_descriptor(3)> and L<BIO_get_wpoll_descriptor(3)>), it should
842 The application should call L<SSL_get_rpoll_descriptor(3)> and
843 L<SSL_get_wpoll_descriptor(3)> to identify OS resources which can be used for
848 It should call L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> to determine
851 L<SSL_get_event_timeout(3)> to determine if any timeout event will become
862 The poll descriptor returned by L<SSL_get_rpoll_descriptor(3)> becomes readable
863 (if L<SSL_net_read_desired(3)> returned 1);
867 The poll descriptor returned by L<SSL_get_wpoll_descriptor(3)> becomes writable
868 (if L<SSL_net_write_desired(3)> returned 1);
872 The timeout returned by L<SSL_get_event_timeout(3)> (if any) expires.
876 Once any of these events occurs, L<SSL_handle_events(3)> should be called.
883 the case of L<BIO_s_dgram_pair(3)>), the application is responsible for managing
884 and synchronising network I/O. It should call L<SSL_handle_events(3)> after it
885 writes data to a L<BIO_s_dgram_pair(3)> or otherwise takes action so that the
886 QUIC implementation can read new datagrams via a call to L<BIO_recvmmsg(3)> on
887 the underlying network BIO. The QUIC implementation may output datagrams via a
888 call to L<BIO_sendmmsg(3)> and the application is responsible for ensuring these
891 The application must call L<SSL_get_event_timeout(3)> after every call to
892 L<SSL_handle_events(3)> (or another I/O function on the SSL object), and ensure
893 that a call to L<SSL_handle_events(3)> is performed after the specified timeout
900 L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>,
901 L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)>,
902 L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>,
903 L<SSL_set_blocking_mode(3)>, L<SSL_shutdown_ex(3)>,
904 L<SSL_set1_initial_peer_addr(3)>, L<SSL_stream_conclude(3)>,
905 L<SSL_stream_reset(3)>, L<SSL_get_stream_read_state(3)>,
906 L<SSL_get_stream_read_error_code(3)>, L<SSL_get_conn_close_info(3)>,
907 L<SSL_get0_connection(3)>, L<SSL_get_stream_type(3)>, L<SSL_get_stream_id(3)>,
908 L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>,
909 L<SSL_set_incoming_stream_policy(3)>, L<SSL_set_default_stream_mode(3)>,
910 L<SSL_new_listener(3)>, L<SSL_new_listener_from(3)>, L<SSL_is_listener(3)>,
911 L<SSL_get0_listener(3)>, L<SSL_listen(3)>, L<SSL_accept_connection(3)>,
912 L<SSL_get_accept_connection_queue_len(3)>, L<SSL_new_domain(3)>,
913 L<SSL_is_domain(3)>, L<SSL_get0_domain(3)>
920 this file except in compliance with the License.  You can obtain a copy