1QUIC Requirements
2=================
3
4There have been various sources of requirements for the OpenSSL QUIC
5implementation. The following sections summarise the requirements obtained from
6each of these sources.
7
8Original OMC Requirements
9-------------------------
10
11The OMC have specified an initial set of requirements for QUIC as well as other
12requirements for the coming releases. The remainder of this section summarises
13the OMC requirements that were originally
14[posted](https://mta.openssl.org/pipermail/openssl-project/2021-October/002764.html)
15and that were specific to QUIC
16
17* The focus for the next releases is QUIC, with the objective of providing a
18  fully functional QUIC implementation over a series of releases (2-3).
19
20* The current libssl record layer includes support for TLS, DTLS and KTLS. QUIC
21  will introduce another variant and there may be more over time. The OMC requires
22  a pluggable record layer interface to be implemented to enable this to be less
23  intrusive, more maintainable, and to harmonize the existing record layer
24  interactions between TLS, DTLS, KTLS and the planned QUIC protocols. The pluggable
25  record layer interface will be internal only for MVP and be public in a future
26  release.
27
28* The application must have the ability to be in control of the event loop without
29  requiring callbacks to process the various events. An application must also have
30  the ability to operate in “blocking” mode.
31
32* The QUIC implementation must include at least one congestion control algorithm.
33  The fully functional release will provide the ability to plug in more
34  implementations (via a provider).
35
36* The minimum viable product (MVP) for the next release is a pluggable record
37  layer interface and a single stream QUIC client in the form of s_client that
38  does not require significant API changes. In the MVP, interoperability should be
39  prioritized over strict standards compliance.
40
41* The MVP will not contain a library API for an HTTP/3 implementation (it is a
42  non-goal of the initial release). Our expectation is that other libraries will
43  be able to use OpenSSL to build an HTTP/3 client on top of OpenSSL for the
44  initial release.
45
46* Once we have a fully functional QUIC implementation (in a subsequent release),
47  it should be possible for external libraries to be able to use the pluggable
48  record layer interface and it should offer a stable ABI (via a provider).
49
50* The next major release number is intended to be reserved for the fully
51  functional QUIC release (this does not imply we expect API breakage to occur as
52  part of this activity - we can change major release numbers even if APIs remain
53  compatible).
54
55* PR#8797 will not be merged and compatibility with the APIs proposed in that PR
56  is a non-goal.
57
58* We do not plan to place protocol versions themselves in separate providers at
59  this stage.
60
61* For the MVP a single interop target (i.e. the server implementation list):
62
63  1. [Cloudfare](https://cloudflare-quic.com/)
64
65* Testing against other implementations is not a release requirement for the MVP.
66
67### Non-QUIC OpenSSL Requirements
68
69In addition to the QUIC requirements, the OMC also required that:
70
71* The objective is to have shorter release timeframes, with releases occurring
72  every six months.
73
74* The platform policy, covering the primary and secondary platforms, should be
75  followed. (Note that this includes testing of primary and secondary platforms
76  on project CI)
77
78OMC Blog post requirements
79--------------------------
80
81The OMC additionally published a
82[blog post](https://www.openssl.org/blog/blog/2021/11/25/openssl-update/) which
83also contained some requirements regarding QUIC. Statements from that blog post
84have been extracted, paraphrased and summarised here as requirements:
85
86* The objective is to have APIs that allow applications to support any of our
87  existing (or future) security protocols and to select between them with minimal
88  effort.
89
90* In TLS/DTLS each connection represents a single stream and each connection is
91  treated separately by our APIs. In the context of QUIC, APIs to be able to
92  handle a collection of streams will be necessary for many applications. With the
93  objective of being able to select which security protocol is used, APIs that
94  encompass that capability for all protocols will need to be added.
95
96* The majority of existing applications operate using a single connection (i.e.
97  effectively they are single stream in nature) and this fundamental context of
98  usage needs to remain simple.
99
100* We need to enable the majority of our existing user’s applications to be able
101  to work in a QUIC environment while expanding our APIs to enable future
102  application usage to support the full capabilities of QUIC.
103
104* We will end up with interfaces that allow other QUIC implementations
105  (outside of OpenSSL) to be able to use the TLS stack within OpenSSL – however
106  that is not the initial focus of the work.
107
108* A long term supported core API for external QUIC library implementation usage
109  in a future OpenSSL release will be provided.
110
111* Make it easy for our users to communicate securely, flexibly and performantly
112  using whatever security protocol is most appropriate for the task at hand.
113
114* We will provide unified, consistent APIs to our users that work for all types
115  of applications ranging from simple single stream clients up to optimised high
116  performance servers
117
118Additional OTC analysis
119-----------------------
120
121An OTC document provided the following analysis.
122
123There are different types of application that we need to cater for:
124
125* Simple clients that just do basic SSL_read/SSL_write or BIO_read/BIO_write
126  interactions. We want to be able to enable them to transfer to using single
127  stream QUIC easily. (MVP)
128
129* Simple servers that just do basic SSL_read/SSL_write or BIO_read/BIO_write
130  interactions. We want to be able to enable them to transfer to using single
131  stream QUIC easily. More likely to want to do multi-stream.
132
133* High performance applications (primarily server based) using existing libssl
134  APIs; using custom network interaction BIOs in order to get the best performance
135  at a network level as well as OS interactions (IO handling, thread handling,
136  using fibres). Would prefer to use the existing APIs - they don’t want to throw
137  away what they’ve got. Where QUIC necessitates a change they would be willing to
138  make minor changes.
139
140* New applications. Would be willing to use new APIs to achieve their goals.
141
142Other requirements
143------------------
144
145The following section summarises requirements obtained from other sources and
146discussions.
147
148* The differences between QUIC, TLS, DTLS etc, should be minimised at an API
149  level - the structure of the application should be the same. At runtime
150  applications should be able to pick whatever protocol they want to use
151
152* It shouldn’t be harder to do single stream just because multi stream as a
153  concept exists.
154
155* It shouldn’t be harder to do TLS just because you have the ability to do DTLS
156  or QUIC.
157
158* Application authors will need good documentation, demos, examples etc.
159
160* QUIC performance should be comparable (in some future release - not MVP) with
161  other major implementations and measured by a) handshakes per second
162  b) application data throughput (bytes per second) for a single stream/connection
163
164* The internal architecture should allow for the fact that we may want to
165  support "single copy" APIs in the future:
166
167  A single copy API would make it possible for application data being sent or
168  received via QUIC to only be copied from one buffer to another once. The
169  "single" copy allowed is to allow for the implicit copy in an encrypt or decrypt
170  operation.
171
172  Single copy for sending data occurs when the application supplies a buffer of
173  data to be sent. No copies of that data are made until it is encrypted. Once
174  encrypted no further copies of the encrypted data are made until it is provided
175  to the kernel for sending via a system call.
176
177  Single copy for receiving data occurs when a library supplied buffer is filled
178  by the kernel via a system call from the socket. No further copies of that data
179  are made until it is decrypted. It is decrypted directly into a buffer made
180  available to (or supplied by) the application with no further internal copies
181  made.
182
183MVP Requirements (3.2)
184----------------------
185
186This section summarises those requirements from the above that are specific to
187the MVP.
188
189* a pluggable record layer (not public for MVP)
190
191* a single stream QUIC client in the form of s_client that does not require
192  significant API changes.
193
194* interoperability should be prioritized over strict standards compliance.
195
196* Single interop target for testing (cloudflare)
197
198* Testing against other implementations is not a release requirement for the MVP.
199
200* Support simple clients that just do basic SSL_read/SSL_write or BIO_read/BIO_write
201  interactions. We want to be able to enable them to transfer to using single
202  stream QUIC easily. (MVP)
203