mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-11-27 05:21:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add an initial QUIC Technical requirements document

Browse Source 
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)
This commit is contained in:
Matt Caswell 2022-01-24 16:59:30 +00:00
parent bcd5645b34
commit cb629550cd
1 changed files with 202 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
doc/designs/quic-design/quic-requirements.md Normal file
View File

@ -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)