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)

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)