Lines Matching +full:stream +full:- +full:mode +full:- +full:support
8 - [QUIC API Overview](#quic-api-overview)
9 * [Overview and Implementation Status](#overview-and-implementation-status)
11 * [SSL Objects](#ssl-objects)
12 + [Structure of Documentation](#structure-of-documentation)
13 + [Existing APIs](#existing-apis)
14 - [`SSL_set_connect_state`](#-ssl-set-connect-state-)
15 - [`SSL_set_accept_state`](#-ssl-set-accept-state-)
16 - [`SSL_is_server`](#-ssl-is-server-)
17 - [`SSL_connect`](#-ssl-connect-)
18 - [`SSL_accept`](#-ssl-accept-)
19 - [`SSL_do_handshake`](#-ssl-do-handshake-)
20 …- [`SSL_read`, `SSL_read_ex`, `SSL_peek`, `SSL_peek_ex`](#-ssl-read----ssl-read-ex----ssl-peek----…
21 - [`SSL_write`, `SSL_write_ex`](#-ssl-write----ssl-write-ex-)
22 - [`SSL_pending`](#-ssl-pending-)
23 - [`SSL_has_pending`](#-ssl-has-pending-)
24 - [`SSL_shutdown`](#-ssl-shutdown-)
25 - [`SSL_clear`](#-ssl-clear-)
26 - [`SSL_free`](#-ssl-free-)
27 …- [`SSL_set0_rbio`, `SSL_set0_wbio`, `SSL_set_bio`](#-ssl-set0-rbio----ssl-set0-wbio----ssl-set-bi…
28 - [`SSL_set_[rw]fd`](#-ssl-set--rw-fd-)
29 - [`SSL_get_[rw]fd`](#-ssl-get--rw-fd-)
30 - [`SSL_CTRL_MODE`, `SSL_CTRL_CLEAR_MODE`](#-ssl-ctrl-mode----ssl-ctrl-clear-mode-)
31 - [SSL Modes](#ssl-modes)
32 + [New APIs for Single-Stream Operation](#new-apis-for-single-stream-operation)
33 - [`SSL_handle_events`](#-ssl-handle-events-)
34 - [`SSL_get_event_timeout`](#-ssl-get-event-timeout-)
35 …- [`SSL_set_blocking_mode`, `SSL_get_blocking_mode`](#-ssl-set-blocking-mode----ssl-get-blocking-m…
36 …- [`SSL_get_rpoll_descriptor`, `SSL_get_wpoll_descriptor`](#-ssl-get-rpoll-descriptor----ssl-get-w…
37 … - [`SSL_net_read_desired`, `SSL_net_write_desired`](#-ssl-want-net-read----ssl-want-net-write-)
38 … - [`SSL_want`, `SSL_want_read`, `SSL_want_write`](#-ssl-want----ssl-want-read----ssl-want-write-)
39 - [`SSL_set1_initial_peer_addr`](#-ssl-set-initial-peer-addr-)
40 - [`SSL_shutdown_ex`](#-ssl-shutdown-ex-)
41 - [`SSL_stream_conclude`](#-ssl-stream-conclude-)
42 - [`SSL_stream_reset`](#-ssl-stream-reset-)
43 - [`SSL_get_stream_state`](#-ssl-get-stream-state-)
44 …- [`SSL_get_stream_read_error_code`, `SSL_get_stream_write_error_code`](#-ssl-get-stream-read-erro…
45 - [`SSL_get_conn_close_info`](#-ssl-get-conn-close-info-)
46 + [New APIs for Multi-Stream Operation](#new-apis-for-multi-stream-operation)
47 - [Notes on Multi-Threaded Operation](#notes-on-multi-threaded-operation)
48 - [Notes on Blocking](#notes-on-blocking)
49 - [Notes on Application-Level Polling](#notes-on-application-level-polling)
50 - [`SSL_get0_connection`](#-ssl-get0-connection-)
51 - [`SSL_is_connection`](#-ssl-is-connection-)
52 - [`SSL_get_stream_type`](#-ssl-get-stream-type-)
53 - [`SSL_get_stream_id`](#-ssl-get-stream-id-)
54 - [`SSL_is_stream_local`](#-ssl-is-stream-local-)
55 - [`SSL_new_stream`](#-ssl-new-stream-)
56 - [`SSL_accept_stream`](#-ssl-accept-stream-)
57 - [`SSL_get_accept_stream_queue_len`](#-ssl-get-accept-stream-queue-len-)
58 - [`SSL_set_incoming_stream_policy`](#-ssl-set-incoming-stream-policy-)
59 - [`SSL_set_default_stream_mode`](#-ssl-set-default-stream-mode-)
60 + [Future APIs](#future-apis)
61 * [BIO Objects](#bio-objects)
62 + [Existing APIs](#existing-apis-1)
63 …- [`BIO_s_connect`, `BIO_new_ssl_connect`, `BIO_set_conn_hostname`](#-bio-s-connect----bio-new-ssl…
64 - [`BIO_new_bio_pair`](#-bio-new-bio-pair-)
65 - [Interactions with `BIO_f_buffer`](#interactions-with--bio-f-buffer-)
66 - [MTU Signalling](#mtu-signalling)
67 + [New APIs](#new-apis)
68 - [`BIO_sendmmsg` and `BIO_recvmmsg`](#-bio-sendmmsg--and--bio-recvmmsg-)
69 - [Truncation Mode](#truncation-mode)
70 - [Capability Negotiation](#capability-negotiation)
71 - [Local Address Support](#local-address-support)
72 - [`BIO_s_dgram_pair`](#-bio-s-dgram-pair-)
73 - [`BIO_POLL_DESCRIPTOR`](#-bio-poll-descriptor-)
74 - [`BIO_s_dgram_mem`](#-bio-s-dgram-mem-)
75 - [`BIO_err_is_non_fatal`](#-bio-err-is-non-fatal-)
76 * [Q & A](#q---a)
79 ----------------------------------
83 [quic-api-ssl-funcs.md](./quic-api-ssl-funcs.md).
85 Non-SSL object APIs which are new or changed, or otherwise discussed in this
87 APIs are not listed here; see [quic-api-ssl-funcs.md](./quic-api-ssl-funcs.md)
91 |-----------|---------------------------------|--------|
113 ----------
117 - to provide an API suitable for use with QUIC, now and in the future;
119 - to reuse the existing libssl APIs to the extent feasible;
121 - to enable existing applications to adapt to using QUIC with only
125 -----------
131 - **Semantics**: This can be one of:
133 - **Unchanged**: The semantics of this existing libssl API call are
135 - **Changed**: The semantics are changed for QUIC.
136 - **New**: The API is new for QUIC.
138 - `SSL_get_error`: Can this API, when used with QUIC, change the
141 - **Never**: Does not interact with `SSL_get_error`.
142 - **Error**: Non-`WANT_READ`/`WANT_WRITE` errors can be raised.
143 - **Want**: `WANT_READ`/`WANT_WRITE` can be raised.
145 - **Can Tick?**: Whether this function is allowed to perform event processing
148 - **CSHL:** Connection/Stream/Handshake Layer classification.
151 - **HL:** This is a handshake layer related call. It should be supported
153 SSL object. QUIC stream SSL objects do not allow these calls to be
156 - **HL-Forbidden:** This is a handshake layer related call, but it is
159 - **C:** Not handshake-layer related. QUIC connection SSL object usage only.
160 Fails on a QUIC stream SSL object.
162 - **CS:** Not handshake-layer related. Can be used on any QUIC SSL object.
164 - **S**: Requires a QUIC stream SSL object or a QUIC connection SSL object
165 with a default stream attached.
172 | --------- | ------------- | --------- | ------------- |
178 | --------- | ------------- | --------- | ------------- |
182 we do not implement server support at this time. However, the semantics of this
188 | --------- | ------------- | --------- | ------------- |
194 | --------- | ------------- | --------- | ------------- |
202 | --------- | ------------- | --------- | ------------- |
210 | --------- | ------------- | --------- | ------------- |
216 mode.
221 | --------- | ------------- | --------- | ------------- |
225 error occurs if in blocking mode (including the peek functions).
227 If the read part of the stream has been finished by the peer, calls to
230 If a stream has terminated in a non-normal fashion (for example because the
231 stream has been reset, or the connection has terminated), calls to `SSL_read`
234 `SSL_get_stream_read_state` can be used to clarify the stream state when an
240 | --------- | ------------- | --------- | ------------- |
245 - `SSL_MODE_ENABLE_PARTIAL_WRITE` on or off
246 - `SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER` on or off
247 - Blocking mode on or off
250 (i.e., copied) all data provided, or an error occurs, if in blocking mode. In
254 `SSL_get_stream_write_state` can be used to clarify the stream state when an
260 | --------- | ------------- | --------- | ------------- |
266 | --------- | ------------- | --------- | ------------- |
271 - Semantics unchanged or approximated (essentially, `SSL_pending() || any RXE
273 - Change semantics to only determine the return value based on if there is
274 data in the stream receive buffer.
279 | --------- | ------------- | --------- | ------------- |
290 | --------- | ------------- | --------- | ------------- |
303 - Modernised implementation which resets everything, handshake layer
304 re-instantiated (safer);
305 - Preserve `SSL_clear` semantics at the handshake layer, reset all QUIC state
308 **TBD:** Semantics of this on stream objects.
313 | --------- | ------------- | --------- | ------------- |
316 **QUIC stream SSL objects.** When used on a QUIC stream SSL object, parts of the
317 stream state may continue to exist internally, managed inside the QUIC
321 If a QUIC stream SSL object is freed for a stream which has not reached a
323 stream is automatically reset (non-normal termination) with an application error
324 code of 0. To explicitly reset a stream with a different application error code,
327 If the peer continues to send data on the stream before it processes the
328 notification of the stream's termination, that incoming data will be discarded.
329 However, the peer will be reliably notified of the non-normal termination of the
330 stream assuming that the connection remains healthy.
332 When freeing a QUIC stream SSL object which was terminated in a non-normal
334 any data which was appended to the stream via `SSL_write` may or may not have
338 When freeing a QUIC stream SSL object which was terminated normally (for example
339 via `SSL_stream_conclude`), data appended to the stream via `SSL_write` will
345 object being used in client mode, there is immediate termination of any QUIC
350 - Any data which was pending transmission or retransmission will not be
353 - The connection closure process will not function correctly or in an
354 RFC-compliant manner. Connection closure will not be signalled to the peer
364 | --------- | ------------- | --------- | ------------- |
367 Sets network-side BIO.
371 - The BIO MUST be a BIO with datagram semantics (this is a change relative to
374 - If the BIO is non-pollable (see below), application-level blocking mode will
380 | --------- | ------------- | --------- | ------------- |
383 Sets network-side socket FD.
390 - Instantiate a `BIO_s_dgram` instead for a QUIC connection SSL object.
391 - Fails (no-op) for a QUIC stream SSL object.
396 | --------- | ------------- | --------- | ------------- |
404 | --------- | ------------- | --------- | ------------- |
409 - `SSL_MODE_ENABLE_PARTIAL_WRITE`: Implemented. If this mode is set during a
410 non-partial-write `SSL_write` operation spanning multiple `SSL_write` calls,
411 this mode does not take effect until the non-partial write operation is
414 - `SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER`: Implemented.
416 - `SSL_MODE_AUTO_RETRY`: TBD.
418 - `SSL_MODE_RELEASE_BUFFERS`: Ignored. This is an optimization and if it has
421 - `SSL_MODE_SEND_FALLBACK_SCSV`: TBD: Either ignore or fail if the client
426 - `SSL_MODE_ASYNC`: TBD.
428 ### New APIs for Single-Stream Operation
433 | --------- | ------------- | --------- | ------------- |
443 | --------- | ------------- | --------- | ------------- |
451 protocol-agnostic API for this purpose, superseding `DTLSv1_get_timeout` for all
463 | --------- | ------------- | --------- | ------------- |
466 Turns blocking mode on or off. This is necessary because up until now libssl has
467 operated in blocking or non-blocking mode automatically as an emergent
472 Use on stream objects: It may be feasible to implement this such that different
473 QUIC stream SSL objects can have different settings for this option.
475 Not supported for non-QUIC SSL objects.
480 | --------- | ------------- | --------- | ------------- |
492 TODO: Support these for non-QUIC SSL objects
497 | --------- | ------------- | --------- | ------------- |
509 TODO: Support these for non-QUIC SSL objects, turning this into a unified
516 non-blocking mode due to a desire to read from or write to the underlying
526 | --------- | ------------- | --------- | ------------- |
541 | --------- | ------------- | --------- | ------------- |
547 uint64_t quic_error_code; /* [0, 2**62-1] */
566 process for an SSL object is complete, further calls are a no-op and return 1.
575 Any application stream data on a non-terminated or normally terminated stream
582 end-of-stream conditions) may not be transmitted to the peer. This flag may be
583 useful where a non-normal application condition has occurred and the delivery of
585 stream data on streams which were terminated non-normally (for example via
590 - **RFC compliant mode.** In this mode, which provides the most robust
595 In blocking mode, the function will return once the closure process is
596 complete. In non-blocking mode, `SSL_shutdown_ex` should be called until it
600 - **Rapid mode.** In this mode, a `CONNECTION_CLOSE` frame is sent in a
601 best-effort manner and the connection is terminated immediately. If the
609 In blocking mode, this blocks until at least one `CONNECTION_CLOSE` frame is
610 sent but does not otherwise block. In non-blocking mode, this should be called
611 until it returns a non-negative value. A negative value indicates failure or
612 an I/O would-block condition.
615 by initiating a rapid or non-blocking shutdown and continuing to call
619 performed, otherwise an RFC-compliant shutdown is performed. The principal
620 effect of this flag is to partially disable blocking behaviour in blocking mode,
627 Calling `SSL_shutdown_ex` on a QUIC stream SSL object is not valid; such a call
635 The `args->quic_error_code` and `args->reason` fields allow the application
637 specified. If `args` or `args->reason` is `NULL`, a zero-length string is used
639 `args->quic_error_code` must be in the range `[0, 2**62-1]`, else this function
646 | --------- | ------------- | --------- | ------------- |
653 `SSL_stream_conclude` signals the normal end-of-stream condition to the send
654 part of a QUIC stream. If called on a QUIC connection SSL object with a default
655 stream, it signals the end of that stream to the peer. If called on a QUIC
656 stream SSL object, it signals the end of that stream to the peer.
659 unidirectional streams. It is a no-op if it has already been called for a given
660 stream, or if either the stream or connection have entered an error state.
663 be written in a reliable manner before the end-of-stream is signalled, assuming
665 logical end-of-stream marker after any data which has previously been written to
666 the stream via calls to `SSL_write`. Further attempts to call `SSL_write` after
669 When calling this on a bidirectional stream, the receive part of the stream
671 also signals the end of the stream. Thus, `SSL_read()` can still be used.
673 This function is used to conclude the send part of a stream in a normal manner.
674 To perform non-normal termination of both the sending and receiving parts of a
675 stream, see `SSL_stream_reset`.
682 | --------- | ------------- | --------- | ------------- |
687 uint64_t quic_error_code; /* [0, 2**62-1] */
695 Conducts a non-normal termination of a bidirectional or outgoing unidirectional
696 stream. For QUIC, this corresponds to a stream reset using a `RESET_STREAM`
699 It may be called on either a QUIC stream SSL object or a QUIC connection SSL
700 object with a default stream; the given stream is reset. The QUIC connection is
704 the stream. It may not be called on an incoming unidirectional stream.
707 application error code to use is specified in `args->quic_error_code`, which
708 must be in the range `[0, 2**62-1]`. `args_len` must be set to `sizeof(*args)`
709 if `args` is non-NULL.
712 no-ops. This is considered a success case.
717 | --------- | ------------- | --------- | ------------- |
722 * e.g. Non-QUIC SSL object, or QUIC connection SSL object without a default
723 * stream.
728 * The read or write part of the stream is still available and has not been
729 * terminated in a normal or non-normal manner.
734 * The stream is a unidirectional stream and this direction cannot be used; for
735 * example, a remotely initiated unidirectional stream where
737 * stream where SSL_get_stream_read_state is
743 * The read or write part of the stream has been finished in a normal manner.
750 * already indicated the end of the stream by calling SSL_stream_conclude,
756 * The stream was reset by the local party.
758 * For SSL_get_stream_read_state, this means that the stream was aborted using a
759 * locally transmitted STOP_SENDING frame. Attempts to read from the stream via
763 * For SSL_get_stream_write_state, this means that the stream was aborted
765 * the stream will fail.
770 * The stream was reset by the remote party.
773 * frame for the stream.
776 * frame for the stream.
781 * The underlying connection supporting the stream has closed or otherwise
785 * stream via SSL_read will fail, though SSL_read may allow any residual
789 * stream will fail.
797 This API allows the current state of a stream to be queried. This allows an
798 application to determine whether a stream is still usable and why a stream has
804 | --------- | ------------- | --------- | ------------- |
813 stream.
816 the stream.
818 If a stream has been terminated normally, returns 0.
820 If a stream has been terminated non-normally, returns 1 and writes the
823 If a stream is still healthy, or was healthy at the time the connection was
824 closed, or the respective part of the stream does not exist (e.g. for a
825 unidirectional stream), returns -1.
830 | --------- | ------------- | --------- | ------------- |
851 `info_len` must be set to `sizeof(*info)`. Returns -1 if called on a non-QUIC
854 `info->reason` is set to point to a buffer containing a reason string. The
857 peer, may also contain zero bytes. `info->reason_len` is the true length of the
860 `info->flags` has `SSL_CONN_CLOSE_FLAG_LOCAL` set if the connection closure was
863 `info->flags` has `SSL_CONN_CLOSE_FLAG_TRANSPORT` if the connection closure was
865 of `info->error_code` is determined by this parameter.
867 ### New APIs for Multi-Stream Operation
869 The above new APIs are built on constructively to facilitate multi-stream
872 The concept of a QUIC stream SSL object is introduced. A QUIC SSL object is
873 either a QUIC connection SSL object or a QUIC stream SSL object. A QUIC stream
875 may or may not have an associated default stream. There may only be at most one
876 default stream for a QUIC connection SSL object. Reading or writing application
877 data to a QUIC connection SSL object with a default stream is equivalent to
878 reading or writing to that stream. It is an error to attempt to read or write
879 application data, or perform other stream-specific operations, on a QUIC
880 connection SSL object without a default stream associated.
882 #### Notes on Multi-Threaded Operation
885 the longer term we intend to support multiple threads using different QUIC
886 stream SSL objects on different threads over the same connection without the
887 application having to do any locking. This is referred to as multi-stream
888 multi-thread (MSMT) operation. Only APIs explicitly denoted below will
889 eventually be MSMT-safe.
893 The blocking mode can be configured on each SSL object individually. When a QUIC
894 stream SSL object is created it inherits its blocking state from the currently
896 stream is created. This can be changed independently. For example, a QUIC
897 connection SSL object can be in blocking mode to allow for blocking
898 `SSL_accept_stream` calls, yet have some or all QUIC stream SSL objects be in
899 non-blocking mode concurrently.
901 #### Notes on Application-Level Polling
904 connection SSL objects efficiently for new stream and stream readability events.
911 | --------- | ------------- | --------- | ------------- |
918 * If the SSL object represents a non-QUIC method or a QUIC connection, this
921 * If the SSL object represents a QUIC stream returns the QUIC connection
930 | --------- | ------------- | --------- | ------------- |
936 * non-QUIC methods, but returns 0 for SSL objects for QUIC streams which are
947 | --------- | ------------- | --------- | ------------- |
952 * If the object represents a stream, returns an SSL_STREAM_TYPE value
953 * designating whether the stream can be used for transmission, reception,
956 * This always returns SSL_STREAM_TYPE_BIDI for non-QUIC methods.
959 * does not have a default stream.
971 | --------- | ------------- | --------- | ------------- |
976 * QUIC: Returns the unique stream ID for the stream, an integer in range [0, 2**62-1],
977 * or UINT64_MAX if the stream ID is not available. If called on a QUIC
978 * connection, returns the unique stream ID for the default stream if there is
989 | --------- | ------------- | --------- | ------------- |
994 * QUIC: Returns 1 if the stream was locally initiated, or 0 otherwise.
996 * TLS, DTLS: Returns -1.
1004 | --------- | ------------- | --------- | ------------- |
1009 * Create a new SSL object representing a single additional stream.
1012 * any such call is a no-op.
1015 * Creates a new stream. Must be called only on a QUIC connection SSL object.
1017 * the created stream is unidirectional, otherwise it is bidirectional.
1019 * To be MSMT-safe.
1032 | --------- | ------------- | --------- | ------------- |
1037 * Create a new SSL object representing an additional stream which was created
1041 * any such call is a no-op.
1045 * stream object. Checks if a new stream has been created by the peer. If it
1048 * stream (that is, the stream with the lowest stream ID) is accepted.
1055 * To be MSMT-safe (i.e., can be called from multiple threads).
1057 * If the QUIC connection SSL object is configured in blocking mode, this
1060 * This function returns NULL if the effective incoming stream reject policy is
1071 | --------- | ------------- | --------- | ------------- |
1077 * to SSL_accept_stream. If this returns a non-zero value, the next call to
1079 * non-QUIC objects, or for QUIC stream objects.
1081 * To be MSMT-safe.
1089 | --------- | ------------- | --------- | ------------- |
1096 * - if the default stream mode is
1100 * - otherwise, this is equivalent to `ACCEPT`.
1106 * receiving and sending parts handled via non-normal termination. `aec` is an
1121 | --------- | ------------- | --------- | ------------- |
1126 * Used to control single stream operation. Calling this function determines the
1127 * nature of the default stream which will automatically be created on the QUIC
1130 * The default mode is `SSL_DEFAULT_STREAM_MODE_AUTO_BIDI`.
1134 * - `SSL_DEFAULT_STREAM_MODE_NONE`: No default stream will ever be created.
1135 * The application is assumed to understand multi-stream operation.
1136 * Remotely-initiated streams are placed in the accept queue for application
1138 * stream SSL object, not the QUIC connection SSL object, as no default
1139 * stream will be associated with it.
1141 * - `SSL_DEFAULT_STREAM_MODE_AUTO_BIDI`: "First stream wins" mode of
1142 * operation for single-stream usage. If `SSL_write` is called before the
1143 * peer opens a remotely-initiated stream, a locally-initiated bidirectional
1144 * stream is created and bound as the default stream. If the peer opens a
1145 * remotely-initiated stream before the local application calls `SSL_write`
1146 * (with `len > 0`) for the first time, that stream is bound as the default
1147 * stream, which may be bidirectional or unidirectional; if it is
1152 * - `SSL_DEFAULT_STREAM_MODE_AUTO_UNI`: "First stream wins" mode of
1153 * operation for single-stream usage, with a unidirectional stream. This
1156 * remotely-initiated stream, a unidirectional TX-only stream is created and
1157 * bound as the default stream. Thereafter, calls to `SSL_read` will fail.
1158 * If the peer creates a remotely-initiated stream prior to the first call
1159 * to `SSL_write` (with `len > 0`), that stream will be bound as the default
1160 * stream; note that a bidirectional stream may be bound in this case.
1164 * This function must be called before a default stream object is created, for
1172 __owur int SSL_set_default_stream_mode(SSL *ssl, uint32_t mode);
1181 -----------
1187 We are aiming to support use of the existing `BIO_new_ssl_connect` API with only
1210 - Require applications to be changed to not use QUIC with a `BIO_f_buffer`.
1211 - Detect when a `BIO_f_buffer` is part of a BIO stack and bypass it
1224 `BIO_s_dgram` also has pre-existing support for getting the correct MTU value
1234 The BIO interface features a new high-performance API for the execution of
1245 - Local address support (getting the destination address of an incoming
1246 packet; setting the source address of an outgoing packet), where support
1248 - Peer address support (setting the destination address of an outgoing
1249 packet; getting the source address of an incoming packet), where support
1253 not all OSes can provide support:
1255 - Iovecs (which have also been determined not to be necessary for a
1257 - Features such as `MSG_DONTWAIT`, etc.
1265 #### Truncation Mode
1294 - Whether source addresses the peer specifies will be processed.
1295 - Whether destination addresses the peer specifies will be processed.
1296 - Whether source addresses will be provided to the opposite BIO when it
1298 - Whether destination addresses will be provided to the opposite BIO
1303 - One side of a BIO pair calls `BIO_dgram_set_caps` with zero or
1305 - `BIO_DGRAM_CAP_HANDLES_SRC_ADDR`
1306 - `BIO_DGRAM_CAP_HANDLES_DST_ADDR`
1307 - `BIO_DGRAM_CAP_PROVIDES_SRC_ADDR`
1308 - `BIO_DGRAM_CAP_PROVIDES_DST_ADDR`
1309 - The other side of the BIO pair calls `BIO_dgram_get_effective_caps`
1312 - The above process can also be repeated in the opposite direction.
1314 #### Local Address Support
1319 Support for local addressing (the reception of destination addresses for
1326 platform. If it determines that support is available, local addressing support
1328 (`BIO_CTRL_DGRAM_SET_LOCAL_ADDR_ENABLE`). If local addressing support has not
1330 or `BIO_recvmmsg` with a `BIO_MSG` with a non-NULL `local` field) fails.
1333 support requires system calls on most operating systems prior to sending or
1336 enabling support could fail due to lack of OS support, etc.
1346 users of that BIO whether it is able to support local addressing (where
1355 the existing BIO pair but provides datagram semantics. It provides full support
1357 mechanism described above, local address support and the MTU signalling
1369 socket (i.e., on POSIX-like platforms, a file descriptor), however other kinds
1375 - Where `BIO_get_rpoll_descriptor` (`BIO_CTRL_GET_RPOLL_DESCRIPTOR`) is called,
1379 - Where
1386 memory-based BIOs such as `BIO_s_dgram_pair` do not correspond to any OS
1391 not is known as non-pollable. `BIO_s_dgram` supports these functions.
1399 `BIO_s_dgram_pair`, it is unidirectional and does not support peer addressing or
1405 an error code represents a non-fatal or transient error. For details, see
1409 -----
1419 meanings.](https://www.rfc-editor.org/rfc/rfc9001.html#name-handshake-complete)
1428 >receives an acknowledgment for a 1-RTT packet.
1430 This logically implies that it is OK for a client to start transmitting 1-RTT
1431 packets prior to handshake confirmation, otherwise there would be no in-flight
1432 1-RTT packets for the client to receive ACKs for.
1434 **Q. Does `ENABLE_PARTIAL_WRITE` interact with blocking mode?**
1436 A. No; this mode is only relevant to non-blocking mode. In blocking mode,
1472 server support is implemented in the future connection teardown could be handled
1476 optionally allow use of the server-style API to make multiple outgoing client
1477 connections with a non-zero-length client-side CID on the same underlying
1482 - **RFC conformant mode.** `SSL_shutdown` only indicates that shutdown is
1500 it receives a late-arriving packet. Endpoints that have some alternative
1501 means to ensure that late-arriving packets do not induce a response, such as
1506 Because our client mode implementation uses one socket per connection, it
1516 - **Rapid shutdown mode.** `SSL_shutdown` sends a `CONNECTION_CLOSE` frame once
1526 some long-running applications, but for others it poses a real issue. For
1527 example, a command-line tool which makes one connection, performs one
1528 application-specific transaction, and then tears down the connection. In this
1529 case an RFC-conformant connection termination would essentially require the
1550 QUIC stream SSL object.
1552 **Q. Can data be received on a locally initiated bidirectional stream before any
1553 data is sent on that stream?**
1560 >An implementation might choose to defer allocating a stream ID to a stream until
1561 >it sends the first STREAM frame and enters this state, which can allow for
1562 >better stream prioritization.
1564 If an ID has not been allocated to a stream, obviously incoming data cannot be
1567 stream locally, then receive data on it before sending anything:
1569 >The sending part of a stream that the endpoint initiates (types 0 and 2 for
1571 >state represents a newly created stream that is able to accept data from the
1576 >For a bidirectional stream, the receiving part enters the "Recv" state when
1580 A peer is not generally notified of the creation of a stream which has not sent
1581 any data yet, since the creation of a stream is signalled only implicitly via
1582 the transmission of data in `STREAM` frames. However, a zero-length STREAM frame
1585 order to receive data on a locally-initiated bidirectional stream before sending
1586 any data on that stream, it would be necessary to either
1588 - Use a QUIC implementation which signals a bidirectional stream which has
1589 not yet sent any data via a zero-length stream frame, or
1591 - Use an application protocol which can inform the peer of the stream ID
1592 of the created stream in some application protocol-specific way.
1595 that the peer has in fact created a stream with a given ID and to
1601 application would want to create a locally-initiated stream and then have the
1602 peer transmit on it first, rather than simply use a remotely-initiated stream.
1606 **Q. How should single-stream operation support locally and remotely-initiated
1609 Note that the ID of a stream depends on whether it is bidirectional and whether
1610 it is initiated by the client or server. Therefore, in single stream operation,
1611 it is necessary to know whether single-stream QUIC is being used with
1612 client-initiated or server-initiated stream initiation, and whether a
1613 bidirectional or unidirectional stream is being used; otherwise, we do not know
1614 which stream ID to bind to.
1616 The object of single stream operation is to support simple uses cases for simple
1617 applications. There seems no need to support esoteric usage of streams such as
1618 receiving first on a locally initiated stream here, thus we avoid supporting
1622 before it calls `SSL_read` by definition is using a locally-initiated stream,
1623 and an application which does the opposite is using a remotely-initiated stream.
1625 the desired stream type.
1627 Supporting locally-initiated streams (`SSL_write` called first) is simple;
1628 we automatically create the stream and queue data for transmission.
1630 Supporting remotely-initiated streams (`SSL_read` called first) is a little
1631 stranger. We could create the stream with the correct ID when cued to by the
1632 initial call to `SSL_read` implying use of a remotely-initiated stream. However,
1633 this would mean we are creating state tracking a remotely-initiated stream
1640 Ergo, creation of a default remotely-initiated stream needs to be deferred
1641 until the *peer* signals such a stream.
1643 This leads naturally to a "first stream wins" model of implementation:
1645 - When a QUIC connection SSL object is created, default stream mode is
1646 enabled, meaning that a default stream will be bound to the QUIC connection
1648 stream is bound yet.
1650 - One of the following events happened — whichever happens first wins:
1652 - The local application calls `SSL_write()` (`len > 0`). A locally-initiated
1653 stream with ordinal 0 is created. The stream is bidirectional by default but
1654 this can be changed. This stream is bound as the default stream.
1656 - The peer creates a stream. This stream is bound as the default stream.
1662 Once one of the above events occurs, any additional stream created by the peer
1665 API-visible effect to the local application (unless the application explicitly