Lines Matching +full:os +full:- +full:initiated
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
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.
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
172 | --------- | ------------- | --------- | ------------- |
178 | --------- | ------------- | --------- | ------------- |
188 | --------- | ------------- | --------- | ------------- |
194 | --------- | ------------- | --------- | ------------- |
202 | --------- | ------------- | --------- | ------------- |
210 | --------- | ------------- | --------- | ------------- |
221 | --------- | ------------- | --------- | ------------- |
230 If a stream has terminated in a non-normal fashion (for example because the
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
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
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
313 | --------- | ------------- | --------- | ------------- |
323 stream is automatically reset (non-normal termination) with an application error
329 However, the peer will be reliably notified of the non-normal termination of the
332 When freeing a QUIC stream SSL object which was terminated in a non-normal
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 | --------- | ------------- | --------- | ------------- |
467 operated in blocking or non-blocking mode automatically as an emergent
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.
571 If no QUIC connection attempt was ever initiated using the given SSL object, the
573 connection closure process is initiated if it has not already begun.
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
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
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
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
659 unidirectional streams. It is a no-op if it has already been called for a given
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
674 To perform non-normal termination of both the sending and receiving parts of a
682 | --------- | ------------- | --------- | ------------- |
687 uint64_t quic_error_code; /* [0, 2**62-1] */
695 Conducts a non-normal termination of a bidirectional or outgoing unidirectional
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
729 * terminated in a normal or non-normal manner.
735 * example, a remotely initiated unidirectional stream where
736 * SSL_get_stream_write_state is called, or a locally initiated unidirectional
804 | --------- | ------------- | --------- | ------------- |
820 If a stream has been terminated non-normally, returns 1 and writes the
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
861 locally initiated.
863 `info->flags` has `SSL_CONN_CLOSE_FLAG_TRANSPORT` if the connection closure was
864 initiated by QUIC, and 0 if it was initiated by the application. The namespace
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
879 application data, or perform other stream-specific operations, on a QUIC
882 #### Notes on Multi-Threaded Operation
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.
899 non-blocking mode concurrently.
901 #### Notes on Application-Level Polling
911 | --------- | ------------- | --------- | ------------- |
918 * If the SSL object represents a non-QUIC method or a QUIC connection, this
930 | --------- | ------------- | --------- | ------------- |
936 * non-QUIC methods, but returns 0 for SSL objects for QUIC streams which are
947 | --------- | ------------- | --------- | ------------- |
956 * This always returns SSL_STREAM_TYPE_BIDI for non-QUIC methods.
971 | --------- | ------------- | --------- | ------------- |
976 * QUIC: Returns the unique stream ID for the stream, an integer in range [0, 2**62-1],
989 | --------- | ------------- | --------- | ------------- |
994 * QUIC: Returns 1 if the stream was locally initiated, or 0 otherwise.
996 * TLS, DTLS: Returns -1.
1004 | --------- | ------------- | --------- | ------------- |
1012 * any such call is a no-op.
1019 * To be MSMT-safe.
1032 | --------- | ------------- | --------- | ------------- |
1041 * any such call is a no-op.
1055 * To be MSMT-safe (i.e., can be called from multiple threads).
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 | --------- | ------------- | --------- | ------------- |
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
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
1145 * remotely-initiated stream before the local application calls `SSL_write`
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
1158 * If the peer creates a remotely-initiated stream prior to the first call
1181 -----------
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
1225 from the OS using `BIO_CTRL_DGRAM_QUERY_MTU`.
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
1248 - Peer address support (setting the destination address of an outgoing
1255 - Iovecs (which have also been determined not to be necessary for a
1257 - Features such as `MSG_DONTWAIT`, etc.
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.
1321 packets) varies by OS. Thus, it may not be available in all circumstances. A
1330 or `BIO_recvmmsg` with a `BIO_MSG` with a non-NULL `local` field) fails.
1336 enabling support could fail due to lack of OS support, etc.
1365 union structure which represents an abstraction over some unspecified kind of OS
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.
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.
1436 A. No; this mode is only relevant to non-blocking mode. In blocking mode,
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
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
1536 Where connection closure is initiated remotely rather than locally, only the
1552 **Q. Can data be received on a locally initiated bidirectional stream before any
1577 >the sending part initiated by the endpoint (type 0 for a client, type 1 for
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
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.
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
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
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.
1627 Supporting locally-initiated streams (`SSL_write` called first) is simple;
1630 Supporting remotely-initiated streams (`SSL_read` called first) is a little
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
1645 - When a QUIC connection SSL object is created, default stream mode is
1650 - One of the following events happened — whichever happens first wins:
1652 - The local application calls `SSL_write()` (`len > 0`). A locally-initiated
1656 - The peer creates a stream. This stream is bound as the default stream.
1665 API-visible effect to the local application (unless the application explicitly