The QUIC Demo-Driven Design process was undertaken to meet the OMC requirement to develop a QUIC API that required only minimal changes to existing applications to be able to adapt their code to use QUIC. The demo-driven design process developed a set of representative demos modelling a variety of common OpenSSL usage patterns based on analysis of a broad spectrum of open source software projects using OpenSSL.
As part of this process, a set of proposed diffs were produced. These proposed diffs were the expected changes which would be needed to the baseline demos to support QUIC based on theoretical analysis of the minimum requirements to be able to support QUIC. This analysis concluded that the changes needed to applications could be kept very small in many circumstances, with only minimal diff sizes to the baseline demos.
Following the development of QUIC MVP, these demos have been revisited and the correspondence of our actual final API and usage patterns with the planned diffs have been reviewed.
This document discusses the planned changes and the actual changes for each demo and draws conclusions on the level of disparity.
Since tracking a set of diffs separately is unwieldy, both the planned and
unplanned changes have been folded into the original baseline demo files guarded
with #ifdef USE_QUIC. Viewing these files therefore is informative to
application writers as it provides a clear view of what is different when using
QUIC. (The originally planned changes, and the final changes, are added in
separate, clearly-labelled commits; to view the originally planned changes only,
view the commit history for a given demo file.)
This demo exists to demonstrate the simplest possible usage of OpenSSL, whether with TLS or QUIC.
The originally planned change to enable applications for QUIC amounted to just a single line:
+ ctx = SSL_CTX_new(QUIC_client_method());
- ctx = SSL_CTX_new(TLS_client_method());
The following additional changes needed to be made:
QUIC_client_method was renamed to OSSL_QUIC_client_method for namespacing
reasons.
A call to SSL_set_alpn_protos to configure ALPN was added. This is necessary
because QUIC mandates the use of ALPN, and this was not noted during the
DDD process.
This demo exists to demonstrate simple non-blocking usage. As with
ddd-01-conn-blocking, the name resolution process is managed by BIO_s_connect.
It also arbitrarily adds a BIO_f_buffer pushed onto the BIO stack
as this is a common application usage pattern.
The originally planned changes to enable applications for QUIC amounted to:
Change of method (as for ddd-01-conn-blocking);
Use of a BIO_f_dgram_buffer BIO method instead of a BIO_f_buffer;
Use of a BIO_get_poll_fd function to get the FD to poll rather than
BIO_get_fd;
A change to how the POLLIN/POLLOUT/POLLERR flags to pass to poll(2)
need to be determined.
Additional functions in application code to determine event handling
timeouts related to QUIC (get_conn_pump_timeout) and to pump
the QUIC event loop (pump).
Timeout computation code which involves merging and comparing different
timeouts and calling pump as needed, based on deadlines reported
by libssl.
Note that some of these changes are unnecessary when using the thread assisted mode (see the variant ddd-02-conn-nonblocking-threads below).
The following additional changes needed to be made:
Change of method name (as for ddd-01-conn-blocking);
Use of ALPN (as for ddd-01-conn-blocking);
The strategy for how to expose pollable OS resource handles
to applications to determine I/O readiness has changed substantially since the
original DDD process. As such, applications now use BIO_get_rpoll_descriptor
and BIO_get_wpoll_descriptor to determine I/O readiness, rather than the
originally hypothesised SSL_get_poll_fd.
The strategy for how to determine when to poll for POLLIN, when to
poll for POLLOUT, etc. has changed since the original DDD process.
This information is now exposed via SSL_net_read_desired and
SSL_net_write_desired.
The API to expose the event handling deadline for the QUIC engine
has evolved since the original DDD process. The new API
SSL_get_event_timeout is used, rather than the originally hypothesised
BIO_get_timeout/SSL_get_timeout.
The API to perform QUIC event processing has been renamed to be
more descriptive. It is now called SSL_handle_events rather than
the originally hypothesised BIO_pump/SSL_pump.
The following changes were foreseen to be necessary, but turned out to actually not be necessary:
BIO_f_buffer() after a SSL BIO
was foreseen as use of buffering on the network side is unworkable with
QUIC. This turned out not to be necessary since we can just reject the
BIO_push() call. The buffer should still be freed eventually when the
SSL BIO is freed. The buffer is not used and is unnecessary, so it is
still desirable for applications to remove this code.This is a variant of the ddd-02-conn-nonblocking demo. The base is the same, but the changes made are different. The use of thread-assisted mode, in which an internal assist thread is used to perform QUIC event handling, enables an application to make fewer changes than are needed in the ddd-02-conn-nonblocking demo.
The originally planned changes to enable applications for QUIC amounted to:
Change of method, this time using method QUIC_client_thread_method rather
than QUIC_client_method;
Use of a BIO_get_poll_fd function to get the FD to poll rather than
BIO_get_fd;
A change to how the POLLIN/POLLOUT/POLLERR flags to pass to poll(2)
need to be determined.
Note that this is a substantially smaller list of changes than for ddd-02-conn-nonblocking.
The following additional changes needed to be made:
Change of method name (QUIC_client_thread_method was renamed to
OSSL_QUIC_client_thread_method for namespacing reasons);
Use of ALPN (as for ddd-01-conn-blocking);
Use of BIO_get_rpoll_descriptor rather than BIO_get_poll_fd (as for
ddd-02-conn-nonblocking).
Use of SSL_net_read_desired and SSL_net_write_desired (as for
ddd-02-conn-nonblocking).
This demo is similar to ddd-01-conn-blocking but uses a file descriptor passed directly by the application rather than BIO_s_connect.
Change of method (as for ddd-01-conn-blocking);
The arguments to the socket(2) call are changed from (AF_INET, SOCK_STREAM,
IPPROTO_TCP) to (AF_INET, SOCK_DGRAM, IPPROTO_UDP).
The following additional changes needed to be made:
Change of method name (as for ddd-01-conn-blocking);
Use of ALPN (as for ddd-01-conn-blocking).
This demo is similar to ddd-01-conn-nonblocking but uses a file descriptor passed directly by the application rather than BIO_s_connect.
Change of method (as for ddd-01-conn-blocking);
The arguments to the socket(2) call are changed from (AF_INET, SOCK_STREAM,
IPPROTO_TCP) to (AF_INET, SOCK_DGRAM, IPPROTO_UDP);
A change to how the POLLIN/POLLOUT/POLLERR flags to pass to poll(2)
need to be determined.
Additional functions in application code to determine event handling
timeouts related to QUIC (get_conn_pump_timeout) and to pump
the QUIC event loop (pump).
Timeout computation code which involves merging and comparing different
timeouts and calling pump as needed, based on deadlines reported
by libssl.
The following additional changes needed to be made:
Change of method name (as for ddd-01-conn-blocking);
Use of ALPN (as for ddd-01-conn-blocking);
SSL_get_timeout replaced with SSL_get_event_timeout (as for
ddd-02-conn-nonblocking);
SSL_pump renamed to SSL_handle_events (as for ddd-02-conn-nonblocking);
The strategy for how to determine when to poll for POLLIN, when to
poll for POLLOUT, etc. has changed since the original DDD process.
This information is now exposed via SSL_net_read_desired and
SSL_net_write_desired (as for ddd-02-conn-nonblocking).
This demo is more elaborate. It uses memory buffers created and managed by an application as an intermediary between libssl and the network, which is a common usage pattern for applications. Managing this pattern for QUIC is more elaborate since datagram semantics on the network channel need to be maintained.
Change of method (as for ddd-01-conn-blocking);
Call to BIO_new_bio_pair is changed to BIO_new_dgram_pair, which
provides a bidirectional memory buffer BIO with datagram semantics.
A change to how the POLLIN/POLLOUT/POLLERR flags to pass to poll(2)
need to be determined.
Potential changes to buffer sizes used by applications to buffer datagrams, if those buffers are smaller than 1472 bytes.
The arguments to the socket(2) call are changed from (AF_INET, SOCK_STREAM,
IPPROTO_TCP) to (AF_INET, SOCK_DGRAM, IPPROTO_UDP);
The following additional changes needed to be made:
Change of method name (as for ddd-01-conn-blocking);
Use of ALPN (as for ddd-01-conn-blocking);
The API to construct a BIO_s_dgram_pair ended up being named
BIO_new_bio_dgram_pair rather than BIO_new_dgram_pair;
Use of SSL_net_read_desired and SSL_net_write_desired (as for
ddd-02-conn-nonblocking).
This demo is the most elaborate of the set. It uses a real-world asynchronous I/O reactor, namely libuv (the engine used by Node.js). In doing so it seeks to demonstrate and prove the viability of our API design with a real-world asynchronous I/O system. It operates wholly in non-blocking mode and uses memory buffers on either side of the QUIC stack to feed data to and from the application and the network.
Change of method (as for ddd-01-conn-blocking);
Various changes to use of libuv needed to switch to using UDP;
Additional use of libuv to configure a timer event;
Call to BIO_new_bio_pair is changed to BIO_new_dgram_pair
(as for ddd-05-mem-nonblocking);
Some reordering of code required by the design of libuv.
The following additional changes needed to be made:
Change of method name (as for ddd-01-conn-blocking);
Use of ALPN (as for ddd-01-conn-blocking);
BIO_new_dgram_pair renamed to BIO_new_bio_dgram_pair (as for
ddd-05-mem-nonblocking);
SSL_get_timeout replaced with SSL_get_event_timeout (as for
ddd-02-conn-nonblocking);
SSL_pump renamed to SSL_handle_events (as for ddd-02-conn-nonblocking);
Fixes to use of libuv based on a corrected understanding of its operation, and changes that necessarily ensue.
The DDD process has successfully delivered on the objective of delivering a QUIC
API which can be used with only minimal API changes. The additional changes on
top of those originally planned which were required to successfully execute the
demos using QUIC were highly limited in scope and mostly constituted only minor
changes. The sum total of the changes required for each demo (both planned and
additional), as denoted in each DDD demo file under #ifdef USE_QUIC guards,
are both minimal and limited in scope.
“Minimal” and “limited” are distinct criteria. If inexorable technical requirements dictate, an enormous set of changes to an application could be considered “minimal”. The changes required to representative applications, as demonstrated by the DDD demos, are not merely minimal but also limited.
For example, while the extent of these necessary changes varies by the sophistication of each demo and the kind of application usage pattern it represents, some demos in particular demonstrate exceptionally small changesets; for example, ddd-01-conn-blocking and ddd-02-conn-nonblocking-threads, with ddd-01-conn-blocking literally being enabled by a single line change assuming ALPN is already configured.
This report concludes the DDD process for the single-stream QUIC client API design process, which sought to validate our API design and API ease of use for existing applications seeking to adopt QUIC.