diff options
author | Matt Caswell <matt@openssl.org> | 2022-01-24 16:59:30 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2022-04-12 14:53:06 +0100 |
commit | cb629550cdab518c925e9b402e11b86497a03845 (patch) | |
tree | 50a3780637b01cc1f9a67914b825364ec86750e2 /doc | |
parent | bcd5645b34c319b8e4d72d6850ead80e85f18921 (diff) |
Add an initial QUIC Technical requirements document
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17577)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/designs/quic-design/quic-requirements.md | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/doc/designs/quic-design/quic-requirements.md b/doc/designs/quic-design/quic-requirements.md new file mode 100644 index 0000000000..6122c0de1f --- /dev/null +++ b/doc/designs/quic-design/quic-requirements.md @@ -0,0 +1,202 @@ +QUIC Requirements +================= + +There have been various sources of requirements for the OpenSSL QUIC +implementation. The following sections summarise the requirements obtained from +each of these sources. + +Original OMC Requirements +------------------------- + +The OMC have specified an initial set of requirements for QUIC as well as other +requirements for the coming releases. The remainder of this section summarises +the OMC requirements that were originally +[posted](https://mta.openssl.org/pipermail/openssl-project/2021-October/002764.html) +and that were specific to QUIC + +* The focus for the next releases is QUIC, with the objective of providing a + fully functional QUIC implementation over a series of releases (2-3). + +* The current libssl record layer includes support for TLS, DTLS and KTLS. QUIC + will introduce another variant and there may be more over time. The OMC requires + a pluggable record layer interface to be implemented to enable this to be less + intrusive, more maintainable, and to harmonize the existing record layer + interactions between TLS, DTLS, KTLS and the planned QUIC protocols. The pluggable + record layer interface will be internal only for MVP and be public in a future + release. + +* The application must have the ability to be in control of the event loop without + requiring callbacks to process the various events. An application must also have + the ability to operate in “blocking” mode. + +* The QUIC implementation must include at least one congestion control algorithm. + The fully functional release will provide the ability to plug in more + implementations (via a provider). + +* The minimum viable product (MVP) for the next release is a pluggable record + layer interface and a single stream QUIC client in the form of s_client that + does not require significant API changes. In the MVP, interoperability should be + prioritized over strict standards compliance. + +* The MVP will not contain a library API for an HTTP/3 implementation (it is a + non-goal of the initial release). Our expectation is that other libraries will + be able to use OpenSSL to build an HTTP/3 client on top of OpenSSL for the + initial release. + +* Once we have a fully functional QUIC implementation (in a subsequent release), + it should be possible for external libraries to be able to use the pluggable + record layer interface and it should offer a stable ABI (via a provider). + +* The next major release number is intended to be reserved for the fully + functional QUIC release (this does not imply we expect API breakage to occur as + part of this activity - we can change major release numbers even if APIs remain + compatible). + +* PR#8797 will not be merged and compatibility with the APIs proposed in that PR + is a non-goal. + +* We do not plan to place protocol versions themselves in separate providers at + this stage. + +* For the MVP a single interop target (i.e. the server implementation list): + + 1. [Cloudfare](https://cloudflare-quic.com/) + +* Testing against other implementations is not a release requirement for the MVP. + +### Non-QUIC OpenSSL Requirements + +In addition to the QUIC requirements, the OMC also required that: + +* The objective is to have shorter release timeframes, with releases occurring + every six months. + +* The platform policy, covering the primary and secondary platforms, should be + followed. (Note that this includes testing of primary and secondary platforms + on project CI) + +OMC Blog post requirements +-------------------------- + +The OMC additionally published a +[blog post](https://www.openssl.org/blog/blog/2021/11/25/openssl-update/) which +also contained some requirements regarding QUIC. Statements from that blog post +have been extracted, paraphrased and summarised here as requirements: + +* The objective is to have APIs that allow applications to support any of our + existing (or future) security protocols and to select between them with minimal + effort. + +* In TLS/DTLS each connection represents a single stream and each connection is + treated separately by our APIs. In the context of QUIC, APIs to be able to + handle a collection of streams will be necessary for many applications. With the + objective of being able to select which security protocol is used, APIs that + encompass that capability for all protocols will need to be added. + +* The majority of existing applications operate using a single connection (i.e. + effectively they are single stream in nature) and this fundamental context of + usage needs to remain simple. + +* We need to enable the majority of our existing user’s applications to be able + to work in a QUIC environment while expanding our APIs to enable future + application usage to support the full capabilities of QUIC. + +* We will end up with interfaces that allow other QUIC implementations + (outside of OpenSSL) to be able to use the TLS stack within OpenSSL – however + that is not the initial focus of the work. + +* A long term supported core API for external QUIC library implementation usage + in a future OpenSSL release will be provided. + +* Make it easy for our users to communicate securely, flexibly and performantly + using whatever security protocol is most appropriate for the task at hand. + +* We will provide unified, consistent APIs to our users that work for all types + of applications ranging from simple single stream clients up to optimised high + performance servers + +Additional OTC analysis +----------------------- + +An OTC document provided the following analysis. + +There are differents types of application that we need to cater for: + +* Simple clients that just do basic SSL_read/SSL_write or BIO_read/BIO_write + interactions. We want to be able to enable them to transfer to using single + stream QUIC easily. (MVP) + +* Simple servers that just do basic SSL_read/SSL_write or BIO_read/BIO_write + interactions. We want to be able to enable them to transfer to using single + stream QUIC easily. More likely to want to do multi-stream. + +* High performance applications (primarily server based) using existing libssl + APIs; using custom network interaction BIOs in order to get the best performance + at a network level as well as OS interactions (IO handling, thread handling, + using fibres). Would prefer to use the existing APIs - they don’t want to throw + away what they’ve got. Where QUIC necessitates a change they would be willing to + make minor changes. + +* New applications. Would be willing to use new APIs to achieve their goals. + +Other requirements +------------------ + +The following section summarises requirements obtained from other sources and +discussions. + +* The differences between QUIC, TLS, DTLS etc, should be minimised at an API + level - the structure of the application should be the same. At runtime + applications should be able to pick whatever protocol they want to use + +* It shouldn’t be harder to do single stream just because multi stream as a + concept exists. + +* It shouldn’t be harder to do TLS just because you have the ability to do DTLS + or QUIC. + +* Application authors will need good documentation, demos, examples etc. + +* QUIC performance should be comparable (in some future release - not MVP) with + other major implementations and measured by a) handshakes per second + b) application data throughput (bytes per second) for a single stream/connection + +* The internal architecture should allow for the fact that we may want to + support "single copy" APIs in the future: + + A single copy API would make it possible for application data being sent or + received via QUIC to only be copied from one buffer to another once. The + "single" copy allowed is to allow for the implicit copy in an encrypt or decrypt + operation. + + Single copy for sending data occurs when the application supplies a buffer of + data to be sent. No copies of that data are made until it is encrypted. Once + encrypted no further copies of the encrypted data are made until it is provided + to the kernel for sending via a system call. + + Single copy for receiving data occurs when a library supplied buffer is filled + by the kernel via a system call from the socket. No further copies of that data + are made until it is decrypted. It is decrypted directly into a buffer made + available to (or supplied by) the application with no further internal copies + made. + +MVP Requirements (3.1) +---------------------- + +This section summarises those requirements from the above that are specific to +the MVP. + +* a pluggable record layer (not public for MVP) + +* a single stream QUIC client in the form of s_client that does not require + significant API changes. + +* interoperability should be prioritized over strict standards compliance. + +* Single interop target for testing (cloudflare) + +* Testing against other implementations is not a release requirement for the MVP. + +* Support simple clients that just do basic SSL_read/SSL_write or BIO_read/BIO_write + interactions. We want to be able to enable them to transfer to using single + stream QUIC easily. (MVP) |