109a25192SPierre ProncheryQUIC Requirements 209a25192SPierre Pronchery================= 309a25192SPierre Pronchery 409a25192SPierre ProncheryThere have been various sources of requirements for the OpenSSL QUIC 509a25192SPierre Proncheryimplementation. The following sections summarise the requirements obtained from 609a25192SPierre Proncheryeach of these sources. 709a25192SPierre Pronchery 809a25192SPierre ProncheryOriginal OMC Requirements 909a25192SPierre Pronchery------------------------- 1009a25192SPierre Pronchery 1109a25192SPierre ProncheryThe OMC have specified an initial set of requirements for QUIC as well as other 1209a25192SPierre Proncheryrequirements for the coming releases. The remainder of this section summarises 1309a25192SPierre Proncherythe OMC requirements that were originally 1409a25192SPierre Pronchery[posted](https://mta.openssl.org/pipermail/openssl-project/2021-October/002764.html) 1509a25192SPierre Proncheryand that were specific to QUIC 1609a25192SPierre Pronchery 1709a25192SPierre Pronchery* The focus for the next releases is QUIC, with the objective of providing a 1809a25192SPierre Pronchery fully functional QUIC implementation over a series of releases (2-3). 1909a25192SPierre Pronchery 2009a25192SPierre Pronchery* The current libssl record layer includes support for TLS, DTLS and KTLS. QUIC 2109a25192SPierre Pronchery will introduce another variant and there may be more over time. The OMC requires 2209a25192SPierre Pronchery a pluggable record layer interface to be implemented to enable this to be less 2309a25192SPierre Pronchery intrusive, more maintainable, and to harmonize the existing record layer 2409a25192SPierre Pronchery interactions between TLS, DTLS, KTLS and the planned QUIC protocols. The pluggable 2509a25192SPierre Pronchery record layer interface will be internal only for MVP and be public in a future 2609a25192SPierre Pronchery release. 2709a25192SPierre Pronchery 2809a25192SPierre Pronchery* The application must have the ability to be in control of the event loop without 2909a25192SPierre Pronchery requiring callbacks to process the various events. An application must also have 3009a25192SPierre Pronchery the ability to operate in “blocking” mode. 3109a25192SPierre Pronchery 3209a25192SPierre Pronchery* The QUIC implementation must include at least one congestion control algorithm. 3309a25192SPierre Pronchery The fully functional release will provide the ability to plug in more 3409a25192SPierre Pronchery implementations (via a provider). 3509a25192SPierre Pronchery 3609a25192SPierre Pronchery* The minimum viable product (MVP) for the next release is a pluggable record 3709a25192SPierre Pronchery layer interface and a single stream QUIC client in the form of s_client that 3809a25192SPierre Pronchery does not require significant API changes. In the MVP, interoperability should be 3909a25192SPierre Pronchery prioritized over strict standards compliance. 4009a25192SPierre Pronchery 4109a25192SPierre Pronchery* The MVP will not contain a library API for an HTTP/3 implementation (it is a 4209a25192SPierre Pronchery non-goal of the initial release). Our expectation is that other libraries will 4309a25192SPierre Pronchery be able to use OpenSSL to build an HTTP/3 client on top of OpenSSL for the 4409a25192SPierre Pronchery initial release. 4509a25192SPierre Pronchery 4609a25192SPierre Pronchery* Once we have a fully functional QUIC implementation (in a subsequent release), 4709a25192SPierre Pronchery it should be possible for external libraries to be able to use the pluggable 4809a25192SPierre Pronchery record layer interface and it should offer a stable ABI (via a provider). 4909a25192SPierre Pronchery 5009a25192SPierre Pronchery* The next major release number is intended to be reserved for the fully 5109a25192SPierre Pronchery functional QUIC release (this does not imply we expect API breakage to occur as 5209a25192SPierre Pronchery part of this activity - we can change major release numbers even if APIs remain 5309a25192SPierre Pronchery compatible). 5409a25192SPierre Pronchery 5509a25192SPierre Pronchery* PR#8797 will not be merged and compatibility with the APIs proposed in that PR 5609a25192SPierre Pronchery is a non-goal. 5709a25192SPierre Pronchery 5809a25192SPierre Pronchery* We do not plan to place protocol versions themselves in separate providers at 5909a25192SPierre Pronchery this stage. 6009a25192SPierre Pronchery 6109a25192SPierre Pronchery* For the MVP a single interop target (i.e. the server implementation list): 6209a25192SPierre Pronchery 6309a25192SPierre Pronchery 1. [Cloudfare](https://cloudflare-quic.com/) 6409a25192SPierre Pronchery 6509a25192SPierre Pronchery* Testing against other implementations is not a release requirement for the MVP. 6609a25192SPierre Pronchery 6709a25192SPierre Pronchery### Non-QUIC OpenSSL Requirements 6809a25192SPierre Pronchery 6909a25192SPierre ProncheryIn addition to the QUIC requirements, the OMC also required that: 7009a25192SPierre Pronchery 7109a25192SPierre Pronchery* The objective is to have shorter release timeframes, with releases occurring 7209a25192SPierre Pronchery every six months. 7309a25192SPierre Pronchery 7409a25192SPierre Pronchery* The platform policy, covering the primary and secondary platforms, should be 7509a25192SPierre Pronchery followed. (Note that this includes testing of primary and secondary platforms 7609a25192SPierre Pronchery on project CI) 7709a25192SPierre Pronchery 7809a25192SPierre ProncheryOMC Blog post requirements 7909a25192SPierre Pronchery-------------------------- 8009a25192SPierre Pronchery 8109a25192SPierre ProncheryThe OMC additionally published a 8209a25192SPierre Pronchery[blog post](https://www.openssl.org/blog/blog/2021/11/25/openssl-update/) which 8309a25192SPierre Proncheryalso contained some requirements regarding QUIC. Statements from that blog post 8409a25192SPierre Proncheryhave been extracted, paraphrased and summarised here as requirements: 8509a25192SPierre Pronchery 8609a25192SPierre Pronchery* The objective is to have APIs that allow applications to support any of our 8709a25192SPierre Pronchery existing (or future) security protocols and to select between them with minimal 8809a25192SPierre Pronchery effort. 8909a25192SPierre Pronchery 9009a25192SPierre Pronchery* In TLS/DTLS each connection represents a single stream and each connection is 9109a25192SPierre Pronchery treated separately by our APIs. In the context of QUIC, APIs to be able to 9209a25192SPierre Pronchery handle a collection of streams will be necessary for many applications. With the 9309a25192SPierre Pronchery objective of being able to select which security protocol is used, APIs that 9409a25192SPierre Pronchery encompass that capability for all protocols will need to be added. 9509a25192SPierre Pronchery 9609a25192SPierre Pronchery* The majority of existing applications operate using a single connection (i.e. 9709a25192SPierre Pronchery effectively they are single stream in nature) and this fundamental context of 9809a25192SPierre Pronchery usage needs to remain simple. 9909a25192SPierre Pronchery 10009a25192SPierre Pronchery* We need to enable the majority of our existing user’s applications to be able 10109a25192SPierre Pronchery to work in a QUIC environment while expanding our APIs to enable future 10209a25192SPierre Pronchery application usage to support the full capabilities of QUIC. 10309a25192SPierre Pronchery 10409a25192SPierre Pronchery* We will end up with interfaces that allow other QUIC implementations 10509a25192SPierre Pronchery (outside of OpenSSL) to be able to use the TLS stack within OpenSSL – however 10609a25192SPierre Pronchery that is not the initial focus of the work. 10709a25192SPierre Pronchery 10809a25192SPierre Pronchery* A long term supported core API for external QUIC library implementation usage 10909a25192SPierre Pronchery in a future OpenSSL release will be provided. 11009a25192SPierre Pronchery 11109a25192SPierre Pronchery* Make it easy for our users to communicate securely, flexibly and performantly 11209a25192SPierre Pronchery using whatever security protocol is most appropriate for the task at hand. 11309a25192SPierre Pronchery 11409a25192SPierre Pronchery* We will provide unified, consistent APIs to our users that work for all types 11509a25192SPierre Pronchery of applications ranging from simple single stream clients up to optimised high 11609a25192SPierre Pronchery performance servers 11709a25192SPierre Pronchery 11809a25192SPierre ProncheryAdditional OTC analysis 11909a25192SPierre Pronchery----------------------- 12009a25192SPierre Pronchery 12109a25192SPierre ProncheryAn OTC document provided the following analysis. 12209a25192SPierre Pronchery 12309a25192SPierre ProncheryThere are different types of application that we need to cater for: 12409a25192SPierre Pronchery 12509a25192SPierre Pronchery* Simple clients that just do basic SSL_read/SSL_write or BIO_read/BIO_write 12609a25192SPierre Pronchery interactions. We want to be able to enable them to transfer to using single 12709a25192SPierre Pronchery stream QUIC easily. (MVP) 12809a25192SPierre Pronchery 12909a25192SPierre Pronchery* Simple servers that just do basic SSL_read/SSL_write or BIO_read/BIO_write 13009a25192SPierre Pronchery interactions. We want to be able to enable them to transfer to using single 13109a25192SPierre Pronchery stream QUIC easily. More likely to want to do multi-stream. 13209a25192SPierre Pronchery 13309a25192SPierre Pronchery* High performance applications (primarily server based) using existing libssl 13409a25192SPierre Pronchery APIs; using custom network interaction BIOs in order to get the best performance 13509a25192SPierre Pronchery at a network level as well as OS interactions (IO handling, thread handling, 13609a25192SPierre Pronchery using fibres). Would prefer to use the existing APIs - they don’t want to throw 13709a25192SPierre Pronchery away what they’ve got. Where QUIC necessitates a change they would be willing to 13809a25192SPierre Pronchery make minor changes. 13909a25192SPierre Pronchery 14009a25192SPierre Pronchery* New applications. Would be willing to use new APIs to achieve their goals. 14109a25192SPierre Pronchery 14209a25192SPierre ProncheryOther requirements 14309a25192SPierre Pronchery------------------ 14409a25192SPierre Pronchery 14509a25192SPierre ProncheryThe following section summarises requirements obtained from other sources and 14609a25192SPierre Proncherydiscussions. 14709a25192SPierre Pronchery 14809a25192SPierre Pronchery* The differences between QUIC, TLS, DTLS etc, should be minimised at an API 14909a25192SPierre Pronchery level - the structure of the application should be the same. At runtime 15009a25192SPierre Pronchery applications should be able to pick whatever protocol they want to use 15109a25192SPierre Pronchery 15209a25192SPierre Pronchery* It shouldn’t be harder to do single stream just because multi stream as a 15309a25192SPierre Pronchery concept exists. 15409a25192SPierre Pronchery 15509a25192SPierre Pronchery* It shouldn’t be harder to do TLS just because you have the ability to do DTLS 15609a25192SPierre Pronchery or QUIC. 15709a25192SPierre Pronchery 15809a25192SPierre Pronchery* Application authors will need good documentation, demos, examples etc. 15909a25192SPierre Pronchery 16009a25192SPierre Pronchery* QUIC performance should be comparable (in some future release - not MVP) with 16109a25192SPierre Pronchery other major implementations and measured by a) handshakes per second 16209a25192SPierre Pronchery b) application data throughput (bytes per second) for a single stream/connection 16309a25192SPierre Pronchery 16409a25192SPierre Pronchery* The internal architecture should allow for the fact that we may want to 16509a25192SPierre Pronchery support "single copy" APIs in the future: 16609a25192SPierre Pronchery 16709a25192SPierre Pronchery A single copy API would make it possible for application data being sent or 16809a25192SPierre Pronchery received via QUIC to only be copied from one buffer to another once. The 16909a25192SPierre Pronchery "single" copy allowed is to allow for the implicit copy in an encrypt or decrypt 17009a25192SPierre Pronchery operation. 17109a25192SPierre Pronchery 17209a25192SPierre Pronchery Single copy for sending data occurs when the application supplies a buffer of 17309a25192SPierre Pronchery data to be sent. No copies of that data are made until it is encrypted. Once 17409a25192SPierre Pronchery encrypted no further copies of the encrypted data are made until it is provided 17509a25192SPierre Pronchery to the kernel for sending via a system call. 17609a25192SPierre Pronchery 17709a25192SPierre Pronchery Single copy for receiving data occurs when a library supplied buffer is filled 17809a25192SPierre Pronchery by the kernel via a system call from the socket. No further copies of that data 17909a25192SPierre Pronchery are made until it is decrypted. It is decrypted directly into a buffer made 18009a25192SPierre Pronchery available to (or supplied by) the application with no further internal copies 18109a25192SPierre Pronchery made. 18209a25192SPierre Pronchery 18309a25192SPierre ProncheryMVP Requirements (3.2) 18409a25192SPierre Pronchery---------------------- 18509a25192SPierre Pronchery 18609a25192SPierre ProncheryThis section summarises those requirements from the above that are specific to 18709a25192SPierre Proncherythe MVP. 18809a25192SPierre Pronchery 18909a25192SPierre Pronchery* a pluggable record layer (not public for MVP) 19009a25192SPierre Pronchery 19109a25192SPierre Pronchery* a single stream QUIC client in the form of s_client that does not require 19209a25192SPierre Pronchery significant API changes. 19309a25192SPierre Pronchery 19409a25192SPierre Pronchery* interoperability should be prioritized over strict standards compliance. 19509a25192SPierre Pronchery 19609a25192SPierre Pronchery* Single interop target for testing (cloudflare) 19709a25192SPierre Pronchery 19809a25192SPierre Pronchery* Testing against other implementations is not a release requirement for the MVP. 19909a25192SPierre Pronchery 20009a25192SPierre Pronchery* Support simple clients that just do basic SSL_read/SSL_write or BIO_read/BIO_write 20109a25192SPierre Pronchery interactions. We want to be able to enable them to transfer to using single 20209a25192SPierre Pronchery stream QUIC easily. (MVP) 203