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 differents 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.1) 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
