4 This document sets out the objectives of the QUIC API design process, describes
5 the new and changed APIs, and the design constraints motivating those API
6 designs and the relevant design decisions.
8 - [QUIC API Overview](#quic-api-overview)
9 * [Overview and Implementation Status](#overview-and-implementation-status)
10 * [Objectives](#objectives)
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----ssl-peek-ex-)
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-bio-)
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-mode-)
36 - [`SSL_get_rpoll_descriptor`, `SSL_get_wpoll_descriptor`](#-ssl-get-rpoll-descriptor----ssl-get-wpoll-descriptor-)
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-error-code----ssl-get-stream-write-error-code-)
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_new_stream`](#-ssl-new-stream-)
55 - [`SSL_accept_stream`](#-ssl-accept-stream-)
56 - [`SSL_get_accept_stream_queue_len`](#-ssl-get-accept-stream-queue-len-)
57 - [`SSL_set_incoming_stream_policy`](#-ssl-set-incoming-stream-policy-)
58 - [`SSL_set_default_stream_mode`](#-ssl-set-default-stream-mode-)
59 + [Future APIs](#future-apis)
60 * [BIO Objects](#bio-objects)
61 + [Existing APIs](#existing-apis-1)
62 - [`BIO_s_connect`, `BIO_new_ssl_connect`, `BIO_set_conn_hostname`](#-bio-s-connect----bio-new-ssl-connect----bio-set-conn-hostname-)
63 - [`BIO_new_bio_pair`](#-bio-new-bio-pair-)
64 - [Interactions with `BIO_f_buffer`](#interactions-with--bio-f-buffer-)
65 - [MTU Signalling](#mtu-signalling)
66 + [New APIs](#new-apis)
67 - [`BIO_sendmmsg` and `BIO_recvmmsg`](#-bio-sendmmsg--and--bio-recvmmsg-)
68 - [Truncation Mode](#truncation-mode)
69 - [Capability Negotiation](#capability-negotiation)
70 - [Local Address Support](#local-address-support)
71 - [`BIO_s_dgram_pair`](#-bio-s-dgram-pair-)
72 - [`BIO_POLL_DESCRIPTOR`](#-bio-poll-descriptor-)
73 - [`BIO_s_dgram_mem`](#-bio-s-dgram-mem-)
74 - [`BIO_err_is_non_fatal`](#-bio-err-is-non-fatal-)
77 Overview and Implementation Status
78 ----------------------------------
80 A listing of all SSL object APIs and their implications for QUIC, including
81 current implementation status, can be found in
82 [quic-api-ssl-funcs.md](./quic-api-ssl-funcs.md).
84 Non-SSL object APIs which are new or changed, or otherwise discussed in this
85 document are listed below, along with their implementation status. SSL object
86 APIs are not listed here; see [quic-api-ssl-funcs.md](./quic-api-ssl-funcs.md)
87 for details on SSL object APIs.
89 | Semantics | API | Status |
90 |-----------|---------------------------------|--------|
91 | TBD | `BIO_s_connect` | TODO |
92 | TBD | `BIO_set_conn_hostname` | TODO |
93 | TBD | `BIO_new_bio_pair` | TODO |
94 | New | `BIO_s_dgram_pair` | Done |
95 | Unchanged | `BIO_dgram_get_mtu` | Done |
96 | Unchanged | `BIO_dgram_set_mtu` | Done |
97 | New | `BIO_sendmmsg` | Done |
98 | New | `BIO_recvmmsg` | Done |
99 | New | `BIO_dgram_set_no_trunc` | Done |
100 | New | `BIO_dgram_get_no_trunc` | Done |
101 | New | `BIO_dgram_set_caps` | Done |
102 | New | `BIO_dgram_get_caps` | Done |
103 | New | `BIO_dgram_get_effective_caps` | Done |
104 | New | `BIO_dgram_get_local_addr_cap` | Done |
105 | New | `BIO_dgram_set_local_addr_enable` | Done |
106 | New | `BIO_dgram_get_local_addr_enable` | Done |
107 | New | `BIO_get_rpoll_descriptor` | Done |
108 | New | `BIO_get_wpoll_descriptor` | Done |
109 | New | `BIO_err_is_non_fatal` | Done |
114 The objectives of the QUIC API design are:
116 - to provide an API suitable for use with QUIC, now and in the future;
118 - to reuse the existing libssl APIs to the extent feasible;
120 - to enable existing applications to adapt to using QUIC with only
126 ### Structure of Documentation
128 Each API listed below has an information table with the following fields:
130 - **Semantics**: This can be one of:
132 - **Unchanged**: The semantics of this existing libssl API call are
134 - **Changed**: The semantics are changed for QUIC.
135 - **New**: The API is new for QUIC.
137 - `SSL_get_error`: Can this API, when used with QUIC, change the
138 state returned by `SSL_get_error`? This can be any combination of:
140 - **Never**: Does not interact with `SSL_get_error`.
141 - **Error**: Non-`WANT_READ`/`WANT_WRITE` errors can be raised.
142 - **Want**: `WANT_READ`/`WANT_WRITE` can be raised.
144 - **Can Tick?**: Whether this function is allowed to perform event processing
145 for the QUIC state machine and potentially perform network I/O.
147 - **CSHL:** Connection/Stream/Handshake Layer classification.
150 - **HL:** This is a handshake layer related call. It should be supported
151 on a QUIC connection SSL object, forwarding to the handshake layer
152 SSL object. QUIC stream SSL objects do not allow these calls to be
155 - **HL-Forbidden:** This is a handshake layer related call, but it is
156 inapplicable to QUIC, so it is not supported.
158 - **C:** Not handshake-layer related. QUIC connection SSL object usage only.
159 Fails on a QUIC stream SSL object.
161 - **CS:** Not handshake-layer related. Can be used on any QUIC SSL object.
163 - **S**: Requires a QUIC stream SSL object or a QUIC connection SSL object
164 with a default stream attached.
168 #### `SSL_set_connect_state`
170 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
171 | --------- | ------------- | --------- | ------------- |
172 | Unchanged | Never | No | HL |
174 #### `SSL_set_accept_state`
176 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
177 | --------- | ------------- | --------- | ------------- |
178 | Unchanged | Never | No | HL |
180 **Note:** Attempting to proceed in this state will not function for now because
181 we do not implement server support at this time. However, the semantics of this
182 function as such are unchanged.
186 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
187 | --------- | ------------- | --------- | ------------- |
188 | Unchanged | Never | No | HL |
192 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
193 | --------- | ------------- | --------- | ------------- |
194 | Unchanged | Error/Want | Yes | HL |
196 Simple composition of `SSL_set_connect_state` and `SSL_do_handshake`.
200 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
201 | --------- | ------------- | --------- | ------------- |
202 | Unchanged | Error/Want | Yes | HL |
204 Simple composition of `SSL_set_accept_state` and `SSL_do_handshake`.
206 #### `SSL_do_handshake`
208 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
209 | --------- | ------------- | --------- | ------------- |
210 | Unchanged | Error/Want | Yes | HL |
212 **Note:** Idempotent if handshake already completed.
214 **Blocking Considerations:** Blocks until handshake completed if in blocking
217 #### `SSL_read`, `SSL_read_ex`, `SSL_peek`, `SSL_peek_ex`
219 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
220 | --------- | ------------- | --------- | ------------- |
221 | Unchanged | Error/Want | Yes | CS |
223 **Blocking Considerations:** Blocks until at least one byte is available or an
224 error occurs if in blocking mode (including the peek functions).
226 If the read part of the stream has been finished by the peer, calls to
227 `SSL_read` will fail with `SSL_ERROR_ZERO_RETURN`.
229 If a stream has terminated in a non-normal fashion (for example because the
230 stream has been reset, or the connection has terminated), calls to `SSL_read`
231 will fail with `SSL_ERROR_SSL`.
233 `SSL_get_stream_read_state` can be used to clarify the stream state when an
236 #### `SSL_write`, `SSL_write_ex`
238 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
239 | --------- | ------------- | --------- | ------------- |
240 | Unchanged | Error/Want | Yes | CS |
242 We have to implement all of the following modes:
244 - `SSL_MODE_ENABLE_PARTIAL_WRITE` on or off
245 - `SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER` on or off
246 - Blocking mode on or off
248 **Blocking Considerations:** Blocks until libssl has accepted responsibility for
249 (i.e., copied) all data provided, or an error occurs, if in blocking mode. In
250 other words, it blocks until it can buffer the data. This does not necessarily
251 mean that the data has actually been sent.
253 `SSL_get_stream_write_state` can be used to clarify the stream state when an
258 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
259 | --------- | ------------- | --------- | ------------- |
260 | Unchanged | Never | No | CS |
262 #### `SSL_has_pending`
264 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
265 | --------- | ------------- | --------- | ------------- |
266 | Unchanged | Never | No | CS |
270 - Semantics unchanged or approximated (essentially, `SSL_pending() || any RXE
271 queued || any URXE queued`).
272 - Change semantics to only determine the return value based on if there is
273 data in the stream receive buffer.
277 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
278 | --------- | ------------- | --------- | ------------- |
279 | Unchanged | Error | Yes | CS |
281 See `SSL_shutdown_ex` below for discussion of how this will work for QUIC.
283 Calling `SSL_shutdown` is always exactly identical in function to calling
284 `SSL_shutdown_ex` with `flags` set to 0 and `args` set to `NULL`.
288 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
289 | --------- | ------------- | --------- | ------------- |
290 | TBD | TBD | No | C |
292 There are potential implementation hazards:
294 >SSL_clear() resets the SSL object to allow for another connection. The reset
295 >operation however keeps several settings of the last sessions (some of these
296 >settings were made automatically during the last handshake). It only makes sense
297 >for a new connection with the exact same peer that shares these settings, and
298 >may fail if that peer changes its settings between connections.
300 **TBD:** How should `SSL_clear` be implemented? Either:
302 - Modernised implementation which resets everything, handshake layer
303 re-instantiated (safer);
304 - Preserve `SSL_clear` semantics at the handshake layer, reset all QUIC state
305 (`QUIC_CHANNEL` torn down, CSM reset).
307 **TBD:** Semantics of this on stream objects.
311 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
312 | --------- | ------------- | --------- | ------------- |
313 | Changed | Never | No | CS |
315 **QUIC stream SSL objects.** When used on a QUIC stream SSL object, parts of the
316 stream state may continue to exist internally, managed inside the QUIC
317 connection SSL object, until they can be correctly torn down, or until the QUIC
318 connection SSL object is freed.
320 If a QUIC stream SSL object is freed for a stream which has not reached a
321 terminal state for all of its parts (both send and receive, as applicable), the
322 stream is automatically reset (non-normal termination) with an application error
323 code of 0. To explicitly reset a stream with a different application error code,
324 call `SSL_stream_reset` before calling this function.
326 If the peer continues to send data on the stream before it processes the
327 notification of the stream's termination, that incoming data will be discarded.
328 However, the peer will be reliably notified of the non-normal termination of the
329 stream assuming that the connection remains healthy.
331 When freeing a QUIC stream SSL object which was terminated in a non-normal
332 fashion, or which was terminated automatically due to a call to this function,
333 any data which was appended to the stream via `SSL_write` may or may not have
334 already been transmitted, and even if already transmitted, may or may not be
335 retransmitted in the event of loss.
337 When freeing a QUIC stream SSL object which was terminated normally (for example
338 via `SSL_stream_conclude`), data appended to the stream via `SSL_write` will
339 still be transmitted or retransmitted as necessary, assuming that the QUIC
340 connection SSL object is not freed and that the connection remains healthy.
342 **QUIC connection SSL objects.** `SSL_free` is largely unchanged for QUIC
343 connection SSL objects on the client side. When freeing a QUIC connection SSL
344 object being used in client mode, there is immediate termination of any QUIC
345 network I/O processing as the resources needed to handle the connection are
346 immediately freed. This means that, if a QUIC connection SSL object which has
347 not been shutdown properly is freed using this function:
349 - Any data which was pending transmission or retransmission will not be
350 transmitted, including in streams which were terminated normally;
352 - The connection closure process will not function correctly or in an
353 RFC-compliant manner. Connection closure will not be signalled to the peer
354 and the connection will simply disappear from the perspective of the peer. The
355 connection will appear to remain active until the connection's idle timeout
356 (if negotiated) takes effect.
358 For further discussion of this issue, see `SSL_shutdown_ex` and the Q&A.
360 #### `SSL_set0_rbio`, `SSL_set0_wbio`, `SSL_set_bio`
362 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
363 | --------- | ------------- | --------- | ------------- |
364 | Changed | Never | No | C |
366 Sets network-side BIO.
368 The changes to the semantics of these calls are as follows:
370 - The BIO MUST be a BIO with datagram semantics (this is a change relative to
371 TLS, though not to DTLS).
373 - If the BIO is non-pollable (see below), application-level blocking mode will
376 #### `SSL_set_[rw]fd`
378 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
379 | --------- | ------------- | --------- | ------------- |
380 | Changed | Never | No | C |
382 Sets network-side socket FD.
384 Existing behaviour: Instantiates a `BIO_s_socket`, sets an FD on it, and sets it
387 New proposed behaviour:
389 - Instantiate a `BIO_s_dgram` instead for a QUIC connection SSL object.
390 - Fails (no-op) for a QUIC stream SSL object.
392 #### `SSL_get_[rw]fd`
394 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
395 | --------- | ------------- | --------- | ------------- |
396 | Unchanged | Never | No | C |
398 Should not require any changes.
400 #### `SSL_CTRL_MODE`, `SSL_CTRL_CLEAR_MODE`
402 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
403 | --------- | ------------- | --------- | ------------- |
404 | Unchanged | Never | No | CS |
408 - `SSL_MODE_ENABLE_PARTIAL_WRITE`: Implemented. If this mode is set during a
409 non-partial-write `SSL_write` operation spanning multiple `SSL_write` calls,
410 this mode does not take effect until the non-partial write operation is
413 - `SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER`: Implemented.
415 - `SSL_MODE_AUTO_RETRY`: TBD.
417 - `SSL_MODE_RELEASE_BUFFERS`: Ignored. This is an optimization and if it has
418 any sensible semantic correspondence to QUIC, this can be considered later.
420 - `SSL_MODE_SEND_FALLBACK_SCSV`: TBD: Either ignore or fail if the client
421 attempts to set this prior to handshake. The latter is probably safer.
423 Ignored if set after handshake (existing behaviour).
425 - `SSL_MODE_ASYNC`: TBD.
427 ### New APIs for Single-Stream Operation
429 #### `SSL_handle_events`
431 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
432 | --------- | ------------- | --------- | ------------- |
433 | New | Never | Yes | CS |
435 Advances the QUIC state machine to the extent feasible, potentially performing
436 network I/O. Also compatible with DTLSv1 and supersedes `DTLSv1_handle_timeout`
439 #### `SSL_get_event_timeout`
441 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
442 | --------- | ------------- | --------- | ------------- |
443 | New | Never | No | CS |
445 Gets the time until the QUIC state machine next wants to receive a timeout
448 This is similar to the existing `DTLSv1_get_timeout` function, but it is not
449 specific to DTLSv1. It is also usable for DTLSv1 and can become a
450 protocol-agnostic API for this purpose, superseding `DTLSv1_get_timeout` for all
453 The design is similar to that of `DTLSv1_get_timeout` and uses a `struct
454 timeval`. However, this function can also output an infinite timeout using the
455 `is_infinite` argument, whereas whereas `DTLSv1_get_timeout` represents an
456 infinite timeout using a 0 return value, which does not allow a failure
457 condition to be distinguished.
459 #### `SSL_set_blocking_mode`, `SSL_get_blocking_mode`
461 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
462 | --------- | ------------- | --------- | ------------- |
463 | New | Never | No | CS |
465 Turns blocking mode on or off. This is necessary because up until now libssl has
466 operated in blocking or non-blocking mode automatically as an emergent
467 consequence of whether the underlying network socket is blocking. For QUIC, this
468 is no longer viable, thus blocking semantics at the application level must be
469 explicitly configured.
471 Use on stream objects: It may be feasible to implement this such that different
472 QUIC stream SSL objects can have different settings for this option.
474 Not supported for non-QUIC SSL objects.
476 #### `SSL_get_rpoll_descriptor`, `SSL_get_wpoll_descriptor`
478 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
479 | --------- | ------------- | --------- | ------------- |
480 | New | Never | No | CS |
482 These functions output poll descriptors which can be used to determine when the
483 QUIC state machine next needs to have events handled. `SSL_get_rpoll_descriptor`
484 is relevant if `SSL_net_read_desired` returns 1, and `SSL_get_wpoll_descriptor`
485 is relevant if `SSL_net_write_desired` returns 1.
487 The implementation of these functions is a simple forward to
488 `BIO_get_rpoll_descriptor` and `BIO_get_wpoll_descriptor` on the underlying
491 TODO: Support these for non-QUIC SSL objects
493 #### `SSL_net_read_desired`, `SSL_net_write_desired`
495 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
496 | --------- | ------------- | --------- | ------------- |
497 | New | Never | No | CS |
499 These calls return 1 if the QUIC state machine is interested in receiving
500 further data from the network, or writing to the network, respectively. The
501 return values of these calls should be used to determine which wakeup events
502 should cause an application to call `SSL_handle_events`. These functions do not
503 mutate any state, and their return values may change after a call to any SSL
504 function other than `SSL_net_read_desired`, `SSL_net_write_desired`,
505 `SSL_get_rpoll_descriptor`, `SSL_get_wpoll_descriptor` and
506 `SSL_get_event_timeout`.
508 TODO: Support these for non-QUIC SSL objects, turning this into a unified
509 replacement for `SSL_want`
511 #### `SSL_want`, `SSL_want_read`, `SSL_want_write`
513 The existing API `SSL_want`, and the macros defined in terms of it, are
514 traditionally used to determine if the SSL state machine has exited in
515 non-blocking mode due to a desire to read from or write to the underlying
516 network BIO. However, this API is unsuitable for use with QUIC because the
517 return value of `SSL_want` can only express one I/O direction at a time (read or
518 write), not both. This call will not be implemented for QUIC (e.g. always
519 returns `SSL_NOTHING`) and `SSL_net_read_desired` and `SSL_net_write_desired`
520 will be used instead.
522 #### `SSL_set1_initial_peer_addr`
524 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
525 | --------- | ------------- | --------- | ------------- |
526 | New | Never | No | CS |
528 `SSL_set1_initial_peer_addr` sets the initial L4 UDP peer address for an outgoing
531 The initial peer address may be autodetected if no peer address has already been
532 set explicitly and the QUIC connection SSL object is provided with a
533 `BIO_s_dgram` with a peer set.
535 `SSL_set1_initial_peer_addr` cannot be called after a connection is established.
537 #### `SSL_shutdown_ex`
539 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
540 | --------- | ------------- | --------- | ------------- |
541 | New | Error | Yes | C |
544 typedef struct ssl_shutdown_ex_args_st {
545 /* These arguments pertain only to QUIC connections. */
546 uint64_t quic_error_code; /* [0, 2**62-1] */
547 const char *quic_reason;
548 } SSL_SHUTDOWN_EX_ARGS;
550 #define SSL_SHUTDOWN_FLAG_RAPID (1U << 0)
551 #define SSL_SHUTDOWN_FLAG_IMMEDIATE (1U << 1)
553 int SSL_shutdown_ex(SSL *ssl,
555 const SSL_SHUTDOWN_EX_ARGS *args,
559 `SSL_shutdown_ex` is an extended version of `SSL_shutdown`.
561 `args` specifies arguments which control how the SSL object is shut down. `args`
562 are read only on the first call to `SSL_shutdown_ex` for a given SSL object and
563 subsequent calls to `SSL_shutdown_ex` ignore the `args` argument. `args_len`
564 should be set to `sizeof(*args)`. This function is idempotent; once the shutdown
565 process for a SSL object is complete, further calls are a no-op and return 1.
567 Calling `SSL_shutdown_ex` on a QUIC connection SSL object causes the immediate
568 close of the QUIC connection. “Immediate close” is as defined by RFC 9000.
570 If no QUIC connection attempt was ever initiated using the given SSL object, the
571 QUIC connection transitions immediately to the Terminated state. Otherwise, the
572 connection closure process is initiated if it has not already begun.
574 Any application stream data on a non-terminated or normally terminated stream
575 which has yet to be transmitted is flushed to the network before the termination
576 process begins. This ensures that where an application which calls `SSL_write`
577 and performs a connection closure in a way which is considered normal to the
578 application protocol being used, all of the data written is delivered to the
579 peer. This behaviour may be skipped by setting the `SSL_SHUTDOWN_FLAG_IMMEDIATE`
580 flag, in which case any data appended to streams via `SSL_write` (or any
581 end-of-stream conditions) may not be transmitted to the peer. This flag may be
582 useful where a non-normal application condition has occurred and the delivery of
583 data written to streams via `SSL_write` is no longer relevant. Application
584 stream data on streams which were terminated non-normally (for example via
585 `SSL_stream_reset`) is not transmitted by this function.
587 A QUIC connection can be shut down using this function in two different ways:
589 - **RFC compliant mode.** In this mode, which provides the most robust
590 operation, the shutdown process may take a period of time up to three times
591 the current estimated RTT to the peer. It is possible for the closure process
592 to complete much faster in some circumstances but this cannot be relied upon.
594 In blocking mode, the function will return once the closure process is
595 complete. In non-blocking mode, `SSL_shutdown_ex` should be called until it
596 returns 1, indicating the closure process is complete and the connection is
599 - **Rapid mode.** In this mode, a `CONNECTION_CLOSE` frame is sent in a
600 best-effort manner and the connection is terminated immediately. If the
601 `CONNECTION_CLOSE` frame sent is lost, the peer will not know that the
602 connection has terminated until the negotiated idle timeout (if any) expires.
604 This will generally return 0 on success, indicating that the connection has
605 not yet reached the Terminating state (unless it has already done so, in which
606 case it will return 1).
608 In blocking mode, this blocks until at least one `CONNECTION_CLOSE` frame is
609 sent but does not otherwise block. In non-blocking mode, this should be called
610 until it returns a non-negative value. A negative value indicates failure or
611 an I/O would-block condition.
613 It is permissible for an application to implement a hybrid approach, for example
614 by initiating a rapid or non-blocking shutdown and continuing to call
615 `SSL_handle_events` for a duration it chooses.
617 If `SSL_SHUTDOWN_FLAG_RAPID` is specified in `flags`, a rapid shutdown is
618 performed, otherwise an RFC-compliant shutdown is performed. The principal
619 effect of this flag is to partially disable blocking behaviour in blocking mode,
620 and the QUIC implementation will still attempt to implement the Terminating
621 state semantics if the application happens to call `SSL_handle_events`, until it
622 reaches the Terminated state or is freed. An application can change its mind
623 about performing a rapid shutdown by making a subsequent call to
624 `SSL_shutdown_ex` without the flag set.
626 Calling `SSL_shutdown_ex` on a QUIC stream SSL object is not valid; such a call
627 will fail and has no effect. The rationale for this is that an application may
628 well want to pass around SSL objects for individual QUIC streams to existing
629 parts of its own code which expect something which behaves like a typical SSL
630 object (i.e., a single bytestream); those components may well already call
631 `SSL_shutdown` and it is not desired for such calls to affect the whole
634 The `args->quic_error_code` and `args->reason` fields allow the application
635 error code and reason string for the closure of a QUIC connection to be
636 specified. If `args` or `args->reason` is `NULL`, a zero-length string is used
637 for the reason. If `args` is `NULL`, an error code of 0 is used.
638 `args->quic_error_code` must be in the range `[0, 2**62-1]`, else this function
639 fails. These fields are ignored for SSL objects which do not represent QUIC
642 #### `SSL_stream_conclude`
644 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
645 | --------- | ------------- | --------- | ------------- |
646 | New | Error | Yes | S |
649 int SSL_stream_conclude(SSL *ssl, uint64_t flags);
652 `SSL_stream_conclude` signals the normal end-of-stream condition to the send
653 part of a QUIC stream. If called on a QUIC connection SSL object with a default
654 stream, it signals the end of that stream to the peer. If called on a QUIC
655 stream SSL object, it signals the end of that stream to the peer.
657 This function may only be called for bidirectional streams and for outgoing
658 unidirectional streams. It is a no-op if it has already been called for a given
659 stream, or if either the stream or connection have entered an error state.
661 Any data already queued for transmission via a call to `SSL_write()` will still
662 be written in a reliable manner before the end-of-stream is signalled, assuming
663 the connection remains healthy. This function can be thought of as appending a
664 logical end-of-stream marker after any data which has previously been written to
665 the stream via calls to `SSL_write`. Further attempts to call `SSL_write` after
666 calling this function will fail.
668 When calling this on a bidirectional stream, the receive part of the stream
669 remains unaffected, and the peer may continue to send data via it until the peer
670 also signals the end of the stream. Thus, `SSL_read()` can still be used.
672 This function is used to conclude the send part of a stream in a normal manner.
673 To perform non-normal termination of both the sending and receiving parts of a
674 stream, see `SSL_stream_reset`.
676 `flags` is reserved and should be set to 0.
678 #### `SSL_stream_reset`
680 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
681 | --------- | ------------- | --------- | ------------- |
682 | New | Error | Yes | S |
685 typedef struct ssl_stream_reset_args_st {
686 uint64_t quic_error_code; /* [0, 2**62-1] */
687 } SSL_STREAM_RESET_ARGS;
689 int SSL_stream_reset(SSL *ssl,
690 const SSL_STREAM_RESET_ARGS *args,
694 Conducts a non-normal termination of a bidirectional or outgoing unidirectional
695 stream. For QUIC, this corresponds to a stream reset using a `RESET_STREAM`
698 It may be called on either a QUIC stream SSL object or a QUIC connection SSL
699 object with a default stream; the given stream is reset. The QUIC connection is
702 For bidirectional streams, this terminates both sending and receiving parts of
703 the stream. It may not be called on an incoming unidirectional stream.
705 If `args` is `NULL`, an application error code of 0 is used. Otherwise, the
706 application error code to use is specified in `args->quic_error_code`, which
707 must be in the range `[0, 2**62-1]`. `args_len` must be set to `sizeof(*args)`
708 if `args` is non-NULL.
710 Only the first call to this function has any effect; subsequent calls are
711 no-ops. This is considered a success case.
713 #### `SSL_get_stream_state`
715 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
716 | --------- | ------------- | --------- | ------------- |
717 | New | Never | No | S |
721 * e.g. Non-QUIC SSL object, or QUIC connection SSL object without a default
724 #define SSL_STREAM_STATE_NONE 0
727 * The read or write part of the stream is still available and has not been
728 * terminated in a normal or non-normal manner.
730 #define SSL_STREAM_STATE_OK 1
733 * The stream is a unidirectional stream and this direction cannot be used; for
734 * example, a remotely initiated unidirectional stream where
735 * SSL_get_stream_write_state is called, or a locally initiated unidirectional
736 * stream where SSL_get_stream_read_state is
739 #define SSL_STREAM_STATE_WRONG_DIR 2
742 * The read or write part of the stream has been finished in a normal manner.
744 * For SSL_get_stream_read_state, this means that there is no more data to read,
745 * and that any future SSL_read calls will return any residual data waiting to
746 * be read followed by a SSL_ERROR_ZERO_RETURN condition.
748 * For SSL_get_stream_write_state, this means that the local application has
749 * already indicated the end of the stream by calling SSL_stream_conclude,
750 * and that future calls to SSL_write will fail.
752 #define SSL_STREAM_STATE_FINISHED 3
755 * The stream was reset by the local party.
757 * For SSL_get_stream_read_state, this means that the stream was aborted using a
758 * locally transmitted STOP_SENDING frame. Attempts to read from the stream via
759 * SSL_read will fail, though SSL_read may allow any residual data waiting to
760 * be read to be read first.
762 * For SSL_get_stream_write_state, this means that the stream was aborted
763 * using a locally transmitted RESET_STREAM frame. Attempts to write to
764 * the stream will fail.
766 #define SSL_STREAM_STATE_RESET_LOCAL 4
769 * The stream was reset by the remote party.
771 * For SSL_get_stream_read_state, this means the peer sent a STREAM_RESET
772 * frame for the stream.
774 * For SSL_get_stream_write_state, this means the peer sent a STOP_SENDING
775 * frame for the stream.
777 #define SSL_STREAM_STATE_RESET_REMOTE 5
780 * The underlying connection supporting the stream has closed or otherwise
783 * For SSL_get_stream_read_state, this means that attempts to read from the
784 * stream via SSL_read will fail, though SSL_read may allow any residual
785 * data waiting to be read to be read first.
787 * For SSL_get_stream_write_state, this means that attempts to write to the
790 #define SSL_STREAM_STATE_CONN_CLOSED 6
792 int SSL_get_stream_read_state(SSL *ssl);
793 int SSL_get_stream_write_state(SSL *ssl);
796 This API allows the current state of a stream to be queried. This allows an
797 application to determine whether a stream is still usable and why a stream has
798 reached an error state.
800 #### `SSL_get_stream_read_error_code`, `SSL_get_stream_write_error_code`
802 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
803 | --------- | ------------- | --------- | ------------- |
804 | New | Never | No | S |
807 int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
808 int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);
811 `SSL_get_stream_read_error_code` gets the error code for the read part of the
814 `SSL_get_stream_write_error_code` gets the error code for the write part of
817 If a stream has been terminated normally, returns 0.
819 If a stream has been terminated non-normally, returns 1 and writes the
820 applicable application error code to `*app_error_code`.
822 If a stream is still healthy, or was healthy at the time the connection was
823 closed, or the respective part of the stream does not exist (e.g. for a
824 unidirectional stream), returns -1.
826 #### `SSL_get_conn_close_info`
828 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
829 | --------- | ------------- | --------- | ------------- |
830 | New | Never | No | C |
833 typedef struct ssl_conn_close_info_st {
839 } SSL_CONN_CLOSE_INFO;
841 int SSL_get_conn_close_info(SSL *ssl,
842 SSL_CONN_CLOSE_INFO *info,
846 If a connection is still healthy, returns 0. Otherwise, fills `*info` with
847 information about the error causing connection termination and returns 1.
848 `info_len` must be set to `sizeof(*info)`. Returns -1 if called on a non-QUIC
849 SSL object or if the connection status cannot be determined.
851 `info->reason` is set to point to a buffer containing a reason string. The
852 buffer is valid for the lifetime of the SSL object. The reason string will
853 always be zero terminated, but since it is received from a potentially untrusted
854 peer, may also contain zero bytes. `info->reason_len` is the true length of the
855 reason string in bytes.
857 `info->is_local` is 1 if the connection closure was locally initiated.
859 `info->is_transport` is 1 if the connection closure was initiated by QUIC, and 0
860 if it was initiated by the application. The namespace of `info->error_code` is
861 determined by this parameter.
863 ### New APIs for Multi-Stream Operation
865 The above new APIs are built on constructively to facilitate multi-stream
868 The concept of a QUIC stream SSL object is introduced. A QUIC SSL object is
869 either a QUIC connection SSL object or a QUIC stream SSL object. A QUIC stream
870 SSL object belongs to a QUIC connection SSL object. A QUIC connection SSL object
871 may or may not have an associated default stream. There may only be at most one
872 default stream for a QUIC connection SSL object. Reading or writing application
873 data to a QUIC connection SSL object with a default stream is equivalent to
874 reading or writing to that stream. It is an error to attempt to read or write
875 application data, or perform other stream-specific operations, on a QUIC
876 connection SSL object without a default stream associated.
878 #### Notes on Multi-Threaded Operation
880 Initially these APIs will not be thread safe over the same connection, but in
881 the longer term we intend to support multiple threads using different QUIC
882 stream SSL objects on different threads over the same connection without the
883 application having to do any locking. This is referred to as multi-stream
884 multi-thread (MSMT) operation. Only APIs explicitly denoted below will
885 eventually be MSMT-safe.
887 #### Notes on Blocking
889 The blocking mode can be configured on each SSL object individually. When a QUIC
890 stream SSL object is created it inherits its blocking state from the currently
891 configured blocking state of the QUIC connection SSL object at the time the
892 stream is created. This can be changed independently. For example, a QUIC
893 connection SSL object can be in blocking mode to allow for blocking
894 `SSL_accept_stream` calls, yet have some or all QUIC stream SSL objects be in
895 non-blocking mode concurrently.
897 #### Notes on Application-Level Polling
899 An API may be added in the future to allow applications to poll multiple QUIC
900 connection SSL objects efficiently for new stream and stream readability events.
901 This is not yet urgent but will be more relevant for concurrent server
904 #### `SSL_get0_connection`
906 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
907 | --------- | ------------- | --------- | ------------- |
908 | New | Never | No | CS |
912 * Get the SSL object representing the connection associated with this object.
914 * If the SSL object represents a non-QUIC method or a QUIC connection, this
915 * returns the same object passed.
917 * If the SSL object represents a QUIC stream returns the QUIC connection
920 SSL *SSL_get0_connection(SSL *ssl);
923 #### `SSL_is_connection`
925 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
926 | --------- | ------------- | --------- | ------------- |
927 | New | Never | No | CS |
931 * Returns 1 if the object represents a connection. This always returns 1 for
932 * non-QUIC methods, but returns 0 for SSL objects for QUIC streams which are
933 * not also the QUIC connection object.
935 * This is exactly equivalent to (SSL_get0_connection(ssl) == ssl).
937 int SSL_is_connection(SSL *ssl);
940 #### `SSL_get_stream_type`
942 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
943 | --------- | ------------- | --------- | ------------- |
944 | New | Never | No | S |
948 * If the object represents a stream, returns a SSL_STREAM_TYPE value
949 * designating whether the stream can be used for transmission, reception,
952 * This always returns SSL_STREAM_TYPE_BIDI for non-QUIC methods.
954 * It returns SSL_STREAM_TYPE_NONE for a QUIC connection object if it
955 * does not have a default stream.
957 #define SSL_STREAM_TYPE_NONE 0
958 #define SSL_STREAM_TYPE_READ 1
959 #define SSL_STREAM_TYPE_WRITE 2
960 #define SSL_STREAM_TYPE_BIDI (SSL_STREAM_TYPE_READ | SSL_STREAM_TYPE_WRITE)
961 __owur int SSL_get_stream_type(SSL *ssl);
964 #### `SSL_get_stream_id`
966 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
967 | --------- | ------------- | --------- | ------------- |
968 | New | Never | No | S |
972 * QUIC: Returns the unique stream ID for the stream, an integer in range [0, 2**62-1],
973 * or UINT64_MAX if the stream ID is not available. If called on a QUIC
974 * connection, returns the unique stream ID for the default stream if there is
975 * one, and otherwise returns UINT64_MAX.
977 * TLS, DTLS: Returns UINT64_MAX.
979 __owur uint64_t SSL_get_stream_id(SSL *ssl);
982 #### `SSL_new_stream`
984 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
985 | --------- | ------------- | --------- | ------------- |
986 | New | Never | No | C |
990 * Create a new SSL object representing a single additional stream.
992 * There is no need to call SSL_connect on the resulting object, and
993 * any such call is a no-op.
996 * Creates a new stream. Must be called only on a QUIC connection SSL object.
997 * Can be used on client or server. If the SSL_STREAM_FLAG_UNI flag is set,
998 * the created stream is unidirectional, otherwise it is bidirectional.
1002 * For TLS and DTLS SSL objects:
1005 #define SSL_STREAM_FLAG_UNI 1
1007 SSL *SSL_new_stream(SSL *ssl, uint64_t flags);
1010 #### `SSL_accept_stream`
1012 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
1013 | --------- | ------------- | --------- | ------------- |
1014 | New | Never | Yes | C |
1018 * Create a new SSL object representing an additional stream which was created
1021 * There is no need to call SSL_accept on the resulting object, and
1022 * any such call is a no-op.
1025 * Must be called only on a QUIC connection SSL object. Fails if called on a
1026 * stream object. Checks if a new stream has been created by the peer. If it
1027 * has, creates a new SSL object to represent it and returns it. Otherwise,
1028 * returns NULL. If multiple streams are available to be accepted, the oldest
1029 * stream (that is, the stream with the lowest stream ID) is accepted.
1031 * For all other methods:
1034 * The flags argument is unused and should be set to zero.
1036 * To be MSMT-safe (i.e., can be called from multiple threads).
1038 * If the QUIC connection SSL object is configured in blocking mode, this
1039 * function will block unless the SSL_ACCEPT_STREAM_NO_BLOCK flag is passed.
1041 * This function returns NULL if the effective incoming stream reject policy is
1044 #define SSL_ACCEPT_STREAM_NO_BLOCK 1
1046 SSL *SSL_accept_stream(SSL *ssl, uint64_t flags);
1049 #### `SSL_get_accept_stream_queue_len`
1051 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
1052 | --------- | ------------- | --------- | ------------- |
1053 | New | Never | No | C |
1057 * Determine the number of streams waiting to be returned on a subsequent call
1058 * to SSL_accept_stream. If this returns a non-zero value, the next call to
1059 * SSL_accept_stream (on any thread) is guaranteed to work. Returns 0 for
1060 * non-QUIC objects, or for QUIC stream objects.
1064 size_t SSL_get_accept_stream_queue_len(SSL *ssl);
1067 #### `SSL_set_incoming_stream_policy`
1069 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
1070 | --------- | ------------- | --------- | ------------- |
1071 | New | Never | No | C |
1075 * Sets the policy for incoming streams. If `policy` is `AUTO` (the default):
1077 * - if the default stream mode is
1078 * `SSL_DEFAULT_STREAM_MODE_AUTO_BIDI` or
1079 * `SSL_DEFAULT_STREAM_MODE_AUTO_UNI`, this is equivalent to `REJECT`;
1081 * - otherwise, this is equivalent to `ACCEPT`.
1083 * If configured to `ACCEPT`, incoming streams are placed on the accept queue
1084 * for application consumption. `aec` is ignored in this case.
1086 * If configured to `REJECT`, incoming streams automatically have both their
1087 * receiving and sending parts handled via non-normal termination. `aec` is an
1088 * application error code used for the `STOP_SENDING` and `RESET_STREAM` frames
1089 * used for the purposes of this termination. The default AEC value used if this
1090 * function is never called is 0.
1092 #define SSL_INCOMING_STREAM_POLICY_AUTO 0
1093 #define SSL_INCOMING_STREAM_POLICY_ACCEPT 1
1094 #define SSL_INCOMING_STREAM_POLICY_REJECT 2
1096 int SSL_set_incoming_stream_policy(SSL *ssl, int policy, uint64_t aec);
1099 #### `SSL_set_default_stream_mode`
1101 | Semantics | `SSL_get_error` | Can Tick? | CSHL |
1102 | --------- | ------------- | --------- | ------------- |
1103 | New | Never | No | C |
1107 * Used to control single stream operation. Calling this function determines the
1108 * nature of the default stream which will automatically be created on the QUIC
1109 * connection SSL object.
1111 * The default mode is `SSL_DEFAULT_STREAM_MODE_AUTO_BIDI`.
1113 * The modes are as follows:
1115 * - `SSL_DEFAULT_STREAM_MODE_NONE`: No default stream will ever be created.
1116 * The application is assumed to understand multi-stream operation.
1117 * Remotely-initiated streams are placed in the accept queue for application
1118 * consumption. `SSL_read` and `SSL_write` calls must be made on a QUIC
1119 * stream SSL object, not the QUIC connection SSL object, as no default
1120 * stream will be associated with it.
1122 * - `SSL_DEFAULT_STREAM_MODE_AUTO_BIDI`: "First stream wins" mode of
1123 * operation for single-stream usage. If `SSL_write` is called before the
1124 * peer opens a remotely-initiated stream, a locally-initiated bidirectional
1125 * stream is created and bound as the default stream. If the peer opens a
1126 * remotely-initiated stream before the local application calls `SSL_write`
1127 * (with `len > 0`) for the first time, that stream is bound as the default
1128 * stream, which may be bidirectional or unidirectional; if it is
1129 * unidirectional, calls to `SSL_write` will fail. Attempts to create
1130 * additional streams by the peer are automatically rejected unless
1131 * the application opts in (API TBD).
1133 * - `SSL_DEFAULT_STREAM_MODE_AUTO_UNI`: "First stream wins" mode of
1134 * operation for single-stream usage, with a unidirectional stream. This
1135 * functions identically to `SSL_DEFAULT_STREAM_MODE_AUTO_BIDI`, but if the
1136 * local application calls `SSL_write` prior to the peer creating a
1137 * remotely-initiated stream, a unidirectional TX-only stream is created and
1138 * bound as the default stream. Thereafter, calls to `SSL_read` will fail.
1139 * If the peer creates a remotely-initiated stream prior to the first call
1140 * to `SSL_write` (with `len > 0`), that stream will be bound as the default
1141 * stream; note that a bidirectional stream may be bound in this case.
1142 * Attempts to create additional streams by the peer are automatically
1143 * rejected unless the application opts in (API TBD).
1145 * This function must be called before a default stream object is created, for
1146 * example before initiating a connection. If the function is too late to have
1147 * an effect, this function fails and returns 0.
1149 #define SSL_DEFAULT_STREAM_MODE_NONE 0
1150 #define SSL_DEFAULT_STREAM_MODE_AUTO_BIDI 1
1151 #define SSL_DEFAULT_STREAM_MODE_AUTO_UNI 2
1153 __owur int SSL_set_default_stream_mode(SSL *ssl, uint32_t mode);
1158 A custom poller interface may be provided in the future. For more information,
1159 see the QUIC I/O Architecture design document.
1166 #### `BIO_s_connect`, `BIO_new_ssl_connect`, `BIO_set_conn_hostname`
1168 We are aiming to support use of the existing `BIO_new_ssl_connect` API with only
1169 minimal changes. This will require internal changes to `BIO_s_connect`, which
1170 should automatically detect when it is being used with a QUIC `SSL_CTX` and act
1173 #### `BIO_new_bio_pair`
1175 Unsuitable for use with QUIC on the network side; instead, applications can
1176 make use of the new `BIO_s_dgram_pair` which provides equivalent functionality
1177 with datagram semantics.
1179 #### Interactions with `BIO_f_buffer`
1181 Existing applications sometimes combine a network socket BIO with a
1182 `BIO_f_buffer`. This is problematic because the datagram semantics of writes are
1183 not preserved, therefore the BIO provided to libssl is, as provided, unusable
1184 for the purposes of implementing QUIC. Moreover, output buffering is not a
1185 relevant or desirable performance optimisation for the transmission of UDP
1186 datagrams and will actually undermine QUIC performance by causing incorrect
1187 calculation of ACK delays and consequently inaccurate RTT calculation.
1191 - Require applications to be changed to not use QUIC with a `BIO_f_buffer`.
1192 - Detect when a `BIO_f_buffer` is part of a BIO stack and bypass it
1193 (yucky and surprising).
1198 [BIO_s_dgram_pair(3)](https://www.openssl.org/docs/manmaster/man3/BIO_s_dgram_pair.html)
1200 `BIO_dgram_get_mtu` (`BIO_CTRL_DGRAM_GET_MTU`) and `BIO_dgram_set_mtu`
1201 (`BIO_CTRL_DGRAM_SET_MTU`) already exist for `BIO_s_dgram` and are implemented
1202 on a `BIO_s_dgram_pair` to allow the MTU to be determined and configured. One
1203 side of a pair can configure the MTU to allow the other side to detect it.
1205 `BIO_s_dgram` also has pre-existing support for getting the correct MTU value
1206 from the OS using `BIO_CTRL_DGRAM_QUERY_MTU`.
1210 #### `BIO_sendmmsg` and `BIO_recvmmsg`
1213 [BIO_sendmmsg(3)](https://www.openssl.org/docs/manmaster/man3/BIO_sendmmsg.html)
1215 The BIO interface features a new high-performance API for the execution of
1216 multiple read or write operations in a single system call, on supported OSes. On
1217 other OSes, a compatible fallback implementation is used.
1219 Unlike all other BIO APIs, this API is intended for concurrent threaded use and
1220 as such operates in a stateless fashion with regards to a BIO. This means, for
1221 example, that retry indications are made using explicit API inputs and outputs
1222 rather than setting an internal flag on the BIO.
1224 This new BIO API includes:
1226 - Local address support (getting the destination address of an incoming
1227 packet; setting the source address of an outgoing packet), where support
1228 for this is available;
1229 - Peer address support (setting the destination address of an outgoing
1230 packet; getting the source address of an incoming packet), where support
1231 for this is available.
1233 The following functionality was intentionally left out of this design because
1234 not all OSes can provide support:
1236 - Iovecs (which have also been determined not to be necessary for a
1237 performant QUIC implementation);
1238 - Features such as `MSG_DONTWAIT`, etc.
1240 This BIO API is intended to be extensible. For more information on this API, see
1241 BIO_sendmmsg(3) and BIO_recvmmsg(3).
1243 Custom BIO implementers may set their own implementation of these APIs via
1244 corresponding `BIO_meth` getter/setter functions.
1246 #### Truncation Mode
1249 [BIO_s_dgram_pair(3)](https://www.openssl.org/docs/manmaster/man3/BIO_s_dgram_pair.html)
1251 The controls `BIO_dgram_set_no_trunc` (`BIO_CTRL_DGRAM_SET_NO_TRUNC`) and
1252 `BIO_dgram_get_no_trunc` (`BIO_CTRL_DGRAM_GET_NO_TRUNC`) are introduced. This is
1253 a boolean value which may be implemented by BIOs with datagram semantics. When
1254 enabled, attempting to receive a datagram such that the datagram would
1255 ordinarily be truncated (as per the design of the Berkeley sockets API) instead
1256 results in a failure. This is intended for implementation by `BIO_s_dgram_pair`.
1257 For compatibility, the default behaviour is off.
1259 #### Capability Negotiation
1262 [BIO_s_dgram_pair(3)](https://www.openssl.org/docs/manmaster/man3/BIO_s_dgram_pair.html)
1264 Where a `BIO_s_dgram_pair` is used, there is the potential for such a memory BIO
1265 to be used by existing application code which is being adapted for use with
1266 QUIC. A problem arises whereby one end of a `BIO_s_dgram_pair` (for example, the
1267 side being used by OpenSSL's QUIC implementation) may assume that the other end
1268 supports certain capabilities (for example, specifying a peer address), when in
1269 actual fact the opposite end of the `BIO_s_dgram_pair` does not.
1271 A capability signalling mechanism is introduced which allows one end of a
1272 `BIO_s_dgram_pair` to indicate to the user of the opposite BIO the following
1273 capabilities and related information:
1275 - Whether source addresses the peer specifies will be processed.
1276 - Whether destination addresses the peer specifies will be processed.
1277 - Whether source addresses will be provided to the opposite BIO when it
1279 - Whether destination addresses will be provided to the opposite BIO
1280 when it receives datagrams.
1282 The usage is as follows:
1284 - One side of a BIO pair calls `BIO_dgram_set_caps` with zero or
1285 more of the following flags to advertise its capabilities:
1286 - `BIO_DGRAM_CAP_HANDLES_SRC_ADDR`
1287 - `BIO_DGRAM_CAP_HANDLES_DST_ADDR`
1288 - `BIO_DGRAM_CAP_PROVIDES_SRC_ADDR`
1289 - `BIO_DGRAM_CAP_PROVIDES_DST_ADDR`
1290 - The other side of the BIO pair calls `BIO_dgram_get_effective_caps`
1291 to learn the effective capabilities of the BIO. These are the capabilities set
1292 by the opposite BIO.
1293 - The above process can also be repeated in the opposite direction.
1295 #### Local Address Support
1298 [BIO_s_dgram_pair(3)](https://www.openssl.org/docs/manmaster/man3/BIO_s_dgram_pair.html)
1300 Support for local addressing (the reception of destination addresses for
1301 incoming packets, and the specification of source addresses for outgoing
1302 packets) varies by OS. Thus, it may not be available in all circumstances. A
1303 feature negotiation mechanism is introduced to facilitate this.
1305 `BIO_dgram_get_local_addr_cap` (`BIO_CTRL_DGRAM_GET_LOCAL_ADDR_CAP`) determines
1306 if a BIO is potentially capable of supporting local addressing on the current
1307 platform. If it determines that support is available, local addressing support
1308 must then be explicitly enabled via `BIO_dgram_set_local_addr_enable`
1309 (`BIO_CTRL_DGRAM_SET_LOCAL_ADDR_ENABLE`). If local addressing support has not
1310 been enabled, attempts to use local addressing (for example via `BIO_sendmmsg`
1311 or `BIO_recvmmsg` with a `BIO_MSG` with a non-NULL `local` field) fails.
1313 An explicit enablement call is required because setting up local addressing
1314 support requires system calls on most operating systems prior to sending or
1315 receiving packets and we do not wish to do this automatically inside the
1316 `BIO_sendmmsg`/`BIO_recvmmsg` fastpaths, particularly since the process of
1317 enabling support could fail due to lack of OS support, etc.
1319 `BIO_dgram_get_local_addr_enable` (`BIO_CTRL_DGRAM_GET_LOCAL_ADDR_ENABLE`) is
1322 It is important to note that `BIO_dgram_get_local_addr_cap` is entirely distinct
1323 from the application capability negotiation mechanism discussed above. Whereas
1324 the capability negotiation mechanism discussed above allows *applications* to
1325 signal what they are capable of handling in their usage of a given BIO,
1326 `BIO_dgram_local_addr_cap` allows a *BIO implementation* to indicate to the
1327 users of that BIO whether it is able to support local addressing (where
1330 #### `BIO_s_dgram_pair`
1333 [BIO_s_dgram_pair(3)](https://www.openssl.org/docs/manmaster/man3/BIO_s_dgram_pair.html)
1335 A new BIO implementation, `BIO_s_dgram_pair`, is provided. This is similar to
1336 the existing BIO pair but provides datagram semantics. It provides full support
1337 for the new APIs `BIO_sendmmsg`, `BIO_recvmmsg`, the capability negotiation
1338 mechanism described above, local address support and the MTU signalling
1339 mechanism described above.
1341 It can be instantiated using the new API `BIO_new_dgram_pair`.
1343 #### `BIO_POLL_DESCRIPTOR`
1345 The concept of *poll descriptors* are introduced. A poll descriptor is a tagged
1346 union structure which represents an abstraction over some unspecified kind of OS
1347 descriptor which can be used for synchronization and waiting.
1349 The most commonly used kind of poll descriptor is one which describes a network
1350 socket (i.e., on POSIX-like platforms, a file descriptor), however other kinds
1351 of poll descriptor may be defined.
1353 A BIO may be queried for whether it has a poll descriptor for read or write
1354 operations respectively:
1356 - Where `BIO_get_rpoll_descriptor` (`BIO_CTRL_GET_RPOLL_DESCRIPTOR`) is called,
1357 the BIO should output a poll descriptor which describes a resource which can
1358 be used to determine when the BIO will next become readable via a call to
1359 `BIO_read` or, if supported by the BIO, `BIO_recvmmsg`.
1361 `BIO_get_wpoll_descriptor` (`BIO_CTRL_GET_WPOLL_DESCRIPTOR`) is called, the
1362 BIO should output a poll descriptor which describes a resource which can be
1363 used to determine when the BIO will next become writeable via a call to
1364 `BIO_write` or, if supported by the BIO, `BIO_sendmmsg`.
1366 A BIO may not necessarily be able to provide a poll descriptor. For example,
1367 memory-based BIOs such as `BIO_s_dgram_pair` do not correspond to any OS
1368 synchronisation resource, and thus the `BIO_get_rpoll_descriptor` and
1369 `BIO_get_wpoll_descriptor` calls are not supported for such BIOs.
1371 A BIO which supports these functions is known as pollable, and a BIO which does
1372 not is known as non-pollable. `BIO_s_dgram` supports these functions.
1374 The implementation of these functions for a `BIO_f_ssl` forwards to
1375 `SSL_get_rpoll_descriptor` and `SSL_get_wpoll_descriptor` respectively. The
1377 #### `BIO_s_dgram_mem`
1379 This is a basic memory buffer BIO with datagram semantics. Unlike
1380 `BIO_s_dgram_pair`, it is unidirectional and does not support peer addressing or
1383 #### `BIO_err_is_non_fatal`
1385 A new predicate function `BIO_err_is_non_fatal` is defined which determines if
1386 an error code represents a non-fatal or transient error. For details, see
1387 [BIO_sendmmsg(3)](https://www.openssl.org/docs/manmaster/man3/BIO_sendmmsg.html).
1392 To assist in understanding, when a “TBD” listed above is removed, or when a
1393 relevant question is raised, the resolution to the question will be placed here.
1395 **Q. Should `SSL_do_handshake` wait until the handshake is completed, or until it
1398 **Note:** [The terms *handshake complete* and *handshake confirmed* are defined
1399 in RFC 9001 and have specific
1400 meanings.](https://www.rfc-editor.org/rfc/rfc9001.html#name-handshake-complete)
1402 A. `SSL_do_handshake` should wait until the handshake is completed, because
1403 handshake completion represents the completion of the cryptographic
1404 authentication of the connection. When a connection's handshake is completed,
1405 TLS 1.3 Finished messages have been exchanged by both parties, even if the
1406 handshake has not yet been *confirmed*. Moreover, RFC 9001 s. 4.1.2 states:
1408 >Additionally, a client MAY consider the handshake to be confirmed when it
1409 >receives an acknowledgment for a 1-RTT packet.
1411 This logically implies that it is OK for a client to start transmitting 1-RTT
1412 packets prior to handshake confirmation, otherwise there would be no in-flight
1413 1-RTT packets for the client to receive ACKs for.
1415 **Q. Does `ENABLE_PARTIAL_WRITE` interact with blocking mode?**
1417 A. No; this mode is only relevant to non-blocking mode. In blocking mode,
1418 `SSL_write` always waits until all data is written unless an error occurs. The
1419 semantics of `SSL_write` are preserved unchanged.
1421 **Q. Does `SSL_write` block until data is written to the network, or simply
1422 until it is buffered?**
1424 A. `SSL_write` blocks until it has accepted responsibility for the data passed
1425 to it, just like `write(2)` or `send(2)`. In other words, it blocks until it can
1426 buffer the data. This does not necessarily mean that the data has actually been
1429 **Q. How should connection closure work?**
1431 A. **RFC requirements.** After we begin terminating the connection by sending a
1432 `CONNECTION_CLOSE` frame, QUIC requires that we continue to process network I/O
1433 for a certain period of time so that any further traffic from the peer results
1434 in generation of a further `CONNECTION_CLOSE` frame. This is necessary to handle
1435 the possibility that the `CONNECTION_CLOSE` frame which was initially sent may
1438 **API issues.** This creates a complication because it implies that the
1439 connection closure process may take a fair amount of time, whereas existing API
1440 users will generally expect to be able to call `SSL_shutdown` and then
1441 immediately free the SSL object.
1443 However, if the caller immediately frees the SSL object, this precludes
1444 our implementing the applicable logic, at least on the client side. Moreover,
1445 existing API users are likely to tear down underlying network BIOs immediately
1446 after calling `SSL_free` anyway. In other words, any implementation based on
1447 secretly keeping QUIC state around after a call to `SSL_free` does not seem
1448 particularly workable on the client side.
1450 **Server side considerations.** There is more of a prospect here on the server
1451 side, since multiple connections will share the same socket, which will
1452 presumably be associated with some kind of enduring listener object. Thus when
1453 server support is implemented in the future connection teardown could be handled
1454 internally by maintaining the state of connections undergoing termination inside
1455 the listener object. However, similar caveats to those discussed here arise when
1456 the listener object itself is to be town down. (It is also possible we could
1457 optionally allow use of the server-style API to make multiple outgoing client
1458 connections with a non-zero-length client-side CID on the same underlying
1461 There are only really two ways to handle this:
1463 - **RFC conformant mode.** `SSL_shutdown` only indicates that shutdown is
1464 complete once the the entire connection closure process is complete.
1466 This process consists of the Closing and Draining states. In some cases the
1467 Closing state may last only briefly, namely if the peer chooses to respond to
1468 our `CONNECTION_CLOSE` frame with a `CONNECTION_CLOSE` frame of its own. This
1469 allows immediate progression to the Draining state. However, a peer is *not*
1470 required to respond with such a frame. Thus in the worst case, this state can
1471 be as long as `3*PTO`; for example a peer with a high estimated RTT of 300ms
1472 would have us wait for 900ms.
1474 In the Draining state we simply ignore all incoming traffic and do not
1475 generate outgoing traffic. The purpose of this state is to simply tie up the
1476 socket and ensure any data still in flight is discarded. However, RFC 9000
1479 Disposing of connection state prior to exiting the closing or draining state
1480 could result in an endpoint generating a Stateless Reset unnecessarily when
1481 it receives a late-arriving packet. Endpoints that have some alternative
1482 means to ensure that late-arriving packets do not induce a response, such as
1483 those that are able to close the UDP socket, MAY end these states earlier to
1484 allow for faster resource recovery. Servers that retain an open socket for
1485 accepting new connections SHOULD NOT end the closing or draining state early
1487 Because our client mode implementation uses one socket per connection, it
1488 appears to be reasonable based on the above text to omit the implementation of
1489 the draining state (the same may not be the case for the server role when
1490 implemented in the future).
1492 Thus, in general, `SSL_shutdown` can be expected to take about one round
1493 trip's time to complete when dealing with a peer whose QUIC implementation
1494 happens to respond to a `CONNECTION_CLOSE` frame with a `CONNECTION_CLOSE`
1495 frame of its own, and about three round trips otherwise.
1497 - **Rapid shutdown mode.** `SSL_shutdown` sends a `CONNECTION_CLOSE` frame once
1498 and completes immediately. The Closing and Draining states are not used, and
1499 if the `CONNECTION_CLOSE` frame was lost, the peer will have to wait for idle
1500 timeout to determine that the connection is gone (there is also the
1501 possibility that, if the socket is closed by the application after teardown, a
1502 peer will make something of ICMP Port Unreachable messages, but this is
1503 unlikely to be reliable and since this message is not authenticated, QUIC
1504 implementations probably shouldn't pay much attention to it anyway.)
1506 There is little problem with `SSL_shutdown` taking as long as it needs to for
1507 some long-running applications, but for others it poses a real issue. For
1508 example, a command-line tool which makes one connection, performs one
1509 application-specific transaction, and then tears down the connection. In this
1510 case an RFC-conformant connection termination would essentially require the
1511 process to hang around for a substantial amount of time after the work of the
1514 For this reason, it is concluded that both of these shutdown modes need to be
1517 Where connection closure is initiated remotely rather than locally, only the
1518 draining state is relevant. Since we conclude above that we do not need to
1519 implement the draining state on the client side, this means that connection
1520 closure can be completed immediately in the case of a remote closure.
1522 **Q. Should we just map `SSL_handle_events` to `DTLS_CTRL_HANDLE_TIMEOUT`
1525 A. No, since the infinite time representation is different between the two
1528 **Q. How should `STOP_SENDING` be supported?**
1530 TODO: Determine how `STOP_SENDING` should be supported.
1532 **Q. Can data be received on a locally initiated bidirectional stream before any
1533 data is sent on that stream?**
1535 This is an interesting question without a clear answer to be found in the QUIC
1536 RFCs. A close reading of RFC 9000 suggests that the answer is, in principle,
1537 yes; however the RFC also grants explicit permission to make design choices in
1538 implementations which would preclude this:
1540 >An implementation might choose to defer allocating a stream ID to a stream until
1541 >it sends the first STREAM frame and enters this state, which can allow for
1542 >better stream prioritization.
1544 If an ID has not been allocated to a stream, obviously incoming data cannot be
1545 addressed to it. However, supposing that an implementation does not do this,
1546 RFC 9000 seems basically clear that it is valid for an application to create a
1547 stream locally, then receive data on it before sending anything:
1549 >The sending part of a stream that the endpoint initiates (types 0 and 2 for
1550 >clients, 1 and 3 for servers) is opened by the application. The "Ready"
1551 >state represents a newly created stream that is able to accept data from the
1556 >For a bidirectional stream, the receiving part enters the "Recv" state when
1557 >the sending part initiated by the endpoint (type 0 for a client, type 1 for
1558 >a server) enters the "Ready" state.
1560 A peer is not generally notified of the creation of a stream which has not sent
1561 any data yet, since the creation of a stream is signalled only implicitly via
1562 the transmission of data in `STREAM` frames. However, a zero-length STREAM frame
1563 could presumably be used to effect such a notification. RFC 9000 contains no
1564 specific discussion of this possibility but does not preclude it. As such, in
1565 order to receive data on a locally-initiated bidirectional stream before sending
1566 any data on that stream, it would be necessary to either
1568 - Use a QUIC implementation which signals a bidirectional stream which has
1569 not yet sent any data via a zero-length stream frame, or
1571 - Use an application protocol which can inform the peer of the stream ID
1572 of the created stream in some application protocol-specific way.
1573 This is somewhat less plausible because it would require an API between
1574 the application and its QUIC library to inform the QUIC library
1575 that the peer has in fact created a stream with a given ID and to
1576 take its word for it. This is unlikely to be commonly available, especially as
1577 application errors in usage of such an API would lead to internal
1578 inconsistencies in QUIC connection state.
1580 Of course this discussion is somewhat esoteric as it is unclear why an
1581 application would want to create a locally-initiated stream and then have the
1582 peer transmit on it first, rather than simply use a remotely-initiated stream.
1583 Thus this discussion of this edge case is more of a curiosity, however for
1584 completeness it needs to be thought about in the API design.
1586 **Q. How should single-stream operation support locally and remotely-initiated
1589 Note that the ID of a stream depends on whether it is bidirectional and whether
1590 it is initiated by the client or server. Therefore, in single stream operation,
1591 it is necessary to know whether single-stream QUIC is being used with
1592 client-initiated or server-initiated stream initiation, and whether a
1593 bidirectional or unidirectional stream is being used; otherwise, we do not know
1594 which stream ID to bind to.
1596 The object of single stream operation is to support simple uses cases for simple
1597 applications. There seems no need to support esoteric usage of streams such as
1598 receiving first on a locally initiated stream here, thus we avoid supporting
1599 this to simplify the API.
1601 As such, an application which calls `SSL_write` on a QUIC connection SSL object
1602 before it calls `SSL_read` by definition is using a locally-initiated stream,
1603 and an application which does the opposite is using a remotely-initiated stream.
1604 We can use the ordering of initial calls to `SSL_read` and `SSL_write` to infer
1605 the desired stream type.
1607 Supporting locally-initiated streams (`SSL_write` called first) is simple;
1608 we automatically create the stream and queue data for transmission.
1610 Supporting remotely-initiated streams (`SSL_read` called first) is a little
1611 stranger. We could create the stream with the correct ID when cued to by the
1612 initial call to `SSL_read` implying use of a remotely-initiated stream. However,
1613 this would mean we are creating state tracking a remotely-initiated stream
1614 before the peer has signalled it. This would work in the happy case where the
1615 client is connected to a compatible server but may result in strange
1616 inconsistencies of QUIC internal state if a client is accidentally connected to
1617 an incompatible peer. Since the peer ought to be the authority on the streams it
1618 creates, this seems like an undesirable approach.
1620 Ergo, creation of a default remotely-initiated stream needs to be deferred
1621 until the *peer* signals such a stream.
1623 This leads naturally to a "first stream wins" model of implementation:
1625 - When a QUIC connection SSL object is created, default stream mode is
1626 enabled, meaning that a default stream will be bound to the QUIC connection
1627 SSL object at the earliest available opportunity. However, no default
1628 stream is bound yet.
1630 - One of the following events happened — whichever happens first wins:
1632 - The local application calls `SSL_write()` (`len > 0`). A locally-initiated
1633 stream with ordinal 0 is created. The stream is bidirectional by default but
1634 this can be changed. This stream is bound as the default stream.
1636 - The peer creates a stream. This stream is bound as the default stream.
1638 If the local application calls `SSL_read()` before either of the above
1639 occur, `SSL_read()` fails as though no data is available until one
1640 of the above events occurs.
1642 Once one of the above events occurs, any additional stream created by the peer
1643 is automatically terminated using both `STOP_SENDING` and `STREAM_RESET` frames
1644 (to terminate both the receiving and sending parts respectively) and there is no
1645 API-visible effect to the local application (unless the application explicitly
1646 opts into supporting additional streams).