idnits 2.17.00 (12 Aug 2021) /tmp/idnits50508/draft-pauly-quic-interface-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 10, 2018) is 1342 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-quic-applicability' is defined on line 317, but no explicit reference was found in the text == Outdated reference: A later version (-16) exists of draft-ietf-quic-applicability-02 == Outdated reference: draft-ietf-quic-transport has been published as RFC 9000 == Outdated reference: A later version (-15) exists of draft-ietf-taps-interface-01 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Pauly 3 Internet-Draft E. Kinnear 4 Intended status: Standards Track Apple Inc. 5 Expires: March 14, 2019 September 10, 2018 7 An Interface to the QUIC Transport Protocol 8 draft-pauly-quic-interface-00 10 Abstract 12 This document defines the abstract application interface to the QUIC 13 transport protocol. This allows applications to use a standard 14 interface to directly interact with the QUIC protocol for cases that 15 may not be using an HTTP mapping. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on March 14, 2019. 34 Copyright Notice 36 Copyright (c) 2018 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Specification of Requirements . . . . . . . . . . . . . . 3 53 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. QUIC Streams . . . . . . . . . . . . . . . . . . . . . . 3 55 2.2. Transport Connection Interface . . . . . . . . . . . . . 3 56 2.3. Transferring Messages over Streams . . . . . . . . . . . 3 57 3. API Mappings . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.1. Transport Connection as QUIC Connection . . . . . . . . . 4 59 3.2. Transport Connection as QUIC Stream . . . . . . . . . . . 5 60 4. Racing QUIC Connections . . . . . . . . . . . . . . . . . . . 6 61 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7 64 8. Informative References . . . . . . . . . . . . . . . . . . . 7 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 67 1. Introduction 69 The QUIC Transport Protocol [I-D.ietf-quic-transport] defines a 70 mechanism for allowing applications to communicate as clients or 71 servers to securely send and receive data over multiplexed streams 72 associated with a single cryptographic state. While some 73 applications may not need to directly interact with QUIC as a 74 transport if they use HTTP over QUIC, others will need to send and 75 recieve data directly over the transport. 77 Defining a standard application interface to QUIC as a transport has 78 several benefits to applications as they adopt the protocol. These 79 benefits are expressed in the following requirements for a transport 80 interface to QUIC: 82 o Many of the benefits of QUIC, such as reducing head-of-line 83 blocking or being able to send zero-RTT data, can be lost if the 84 transport API does not provide adequate support. The interface 85 SHOULD allow such features to be accessed in a reliable fashion. 87 o Various implementations of the QUIC protocol SHOULD provide 88 similar transport interfaces in order to allow applications to 89 easily adopt them across different platforms and deployments. 91 o The interface to configure QUIC security properties SHOULD be 92 restricted to a standard set of functionality to ensure that 93 applications cannot easily diminish the security properties of the 94 protocol, while still retaining control over the configuration. 96 1.1. Specification of Requirements 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in BCP 101 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. 104 2. Background 106 2.1. QUIC Streams 108 QUIC defines the concept of "streams" of data. Streams may be either 109 bidirectional or unidirectional. For both cases, data in each 110 direction is treated as a reliable in-order sequence of bytes. 111 Streams are transmitted without head-of-line blocking between one 112 another, although data frames for multiple streams may be 113 consolidated into single packets. 115 2.2. Transport Connection Interface 117 The design of this abstract interface is intended to be compatible 118 with the Transport Services Abstract Interface 119 [I-D.ietf-taps-interface], although it can be used independently. 120 The Transport Services interface defines a Connection as an active 121 transport protocol instance that can send and/or receive Messages 122 between a Local Endpoint and a Remote Endpoint. 124 To avoid confusion with the notion of a QUIC Connection, this 125 definition of a Connection will be referred to as a "Transport 126 Connection Object" in this document. 128 The portions of data that are transferred over the Transport 129 Connection are referred to as Messages. Messages that are sent and 130 received may be associated with metadata and properties in addition 131 to their raw bytes. 133 2.3. Transferring Messages over Streams 135 The QUIC stream architecture provides several possible mappings of 136 application data into separate streams. Consider a case in which an 137 application wants to send ten separate messages to a peer, and some 138 of these messages expect replies from the remote host. There are two 139 high-level strategies for mapping these messages over QUIC streams: 141 1. Each message sent is represented as a new stream, and consumes a 142 Stream ID. Any message that expects a reply can use a 143 bidirectional stream, and data sent back on that stream will be 144 interpreted as the reply. This stategy is descibed in 145 Section 3.1. 147 2. The messages are sent all over a single bidirectional stream, in 148 order. This requires that the messages are able to encode their 149 boundaries within the byte stream, as well as some message 150 identifier or ordering guarantee to allow correlation of replies 151 with outbound messages. This stategy is descibed in Section 3.2. 153 Strategy (1) relies on QUIC for message delineation and correlation; 154 this may be a benefit if an application does not already define its 155 own message framing. However, if messages already define message 156 boundaries and semantics, strategy (2) may be less redundant. 158 Strategy (1) allows all messages to be delivered without head-of-line 159 blocking, which may be beneficial if there are delays on one stream. 160 However, this approach does not provide any ordering guarantees. If 161 an application will only be able to process messages in a strict 162 order, strategy (2) may be preferable. 164 3. API Mappings 166 3.1. Transport Connection as QUIC Connection 168 The mapping of a Transport Connection Object onto an entire QUIC 169 Connection SHOULD be exposed to applications as the "quic-connection" 170 protocol. 172 When this protocol is part of a Protocol Stack being used for a 173 Transport Connection, either as the top-level protocol (the one that 174 the application directly interacts with) or as a protocol in the 175 middle of the stack, each Message object corresponds to a QUIC 176 stream. The description of this mapping will refer to the interation 177 model as if the quic-connection protocol is being used as a top-level 178 protocol. 180 The following API mappings are defined: 182 Initiate: When an application calls Initiate on an outbound 183 connection, and the quic-connection protocol is being used, QUIC 184 MUST initiate its handshake with the Remote Endpoint. The Ready 185 event will be delivered once the handshake is complete and 1-RTT 186 keys have been established. 188 Close: When the application calls Close on its connection, QUIC MUST 189 send a CONNECTION_CLOSE frame to the endpoint if it is currently 190 active. 192 Send: When the application sends a new Message, QUIC MUST allocate a 193 new stream ID. A metadata option SHOULD be exposed to allow the 194 application to specify whether or not it expects a reply. If it 195 does, the QUIC stream will be bidirectional; if not, the QUIC 196 stream will be unidirectional. The API SHOULD allow the 197 application to configure a default directionality setting on the 198 connection to apply to default Messages. Any data sent associated 199 with the Message Send should be sent in a QUIC stream frame for 200 the new stream ID. 202 Send Idempotent: When the application sends a Message, it may mark 203 it as idempotent, which makes the data eligible for sending under 204 0-RTT keys. 206 Send End-of-Message: When the application marks the end of a 207 Message, which may be done as part of the first call to Send, or a 208 subsequent call, the associated QUIC stream MUST deliver a FIN. 210 Receive: A call to receive new data from a Connection will invoke 211 the Received event upon receiving new stream data. If a new 212 stream is received from the peer, the Received event will be 213 associated with a new Message object. If the stream data is 214 marked with a FIN, the Received event will indicate that the 215 Message is complete; otherwise, it will indicate that the Message 216 has received partial data. As new data arrives on various 217 streams, Received events will be delivered for various streams, 218 and may result in partial receives be interleaved with one 219 another. If an application does not wish to ever receive partial 220 Messages, it can indicate that in the call to Receive; this means 221 that data will only be delivered on behalf of a QUIC stream once 222 the FIN bit has been received. 224 3.2. Transport Connection as QUIC Stream 226 The mapping of each Transport Connection Object onto an single QUIC 227 Stream SHOULD be exposed to applications as the "quic-stream" 228 protocol. 230 Messages in this mapping are transferred as in-order chunks of data 231 over a stream represented by the Connection. This Connection is 232 equivalent in contract to a TLS or TCP stream in many ways. The 233 description of this mapping will refer to the interation model as if 234 the quic-stream protocol is being used as a top-level protocol. 236 The following API mappings are defined: 238 Initiate: When an application calls Initiate on an outbound 239 connection, QUIC MUST both start a new handshake with the remote 240 endpoint and also allocate a new stream ID to be associated with 241 the Transport Connection Object. 243 Clone: When an application calls Clone on an existing outbound 244 Transport Connection Object, and the QUIC connection is not 245 already closed, QUIC MUST allocate a new stream ID and associate 246 that stream with a new Transport Connection Object. 248 Close: If the application calls Close on a connection, QUIC MUST 249 send a FIN on the associated stream if it it has not been marked 250 previously. 252 Send: When the application sends a new Message, QUIC MUST send that 253 data on the associated stream. If the application is using a 254 framing protocol on top of quic-stream, then the message 255 boundaries may be interpreted by the framing protocol. Otherwise, 256 the end of a Message will have no impact on the frames being send 257 by QUIC, unless that Message is also marked Final, in which case 258 the QUIC stream MUST send a FIN. 260 Send Idempotent: When the application sends a Message, it may mark 261 it as idempotent, which makes the data eligible for sending under 262 0-RTT keys. 264 Receive: A call to Receive will enqueue a request to receive data on 265 the associated QUIC stream only. Once new data is available on 266 the stream, or the stream is remotely closed, the Received event 267 MUST be invoked. If the stream is not allowed to receive data, 268 since it is unidirectional, the Receive call MUST result in a 269 Received event delivering an error. 271 4. Racing QUIC Connections 273 When a QUIC hostname endpoint is resolved using DNS, a client may 274 want to use the Happy Eyeballs algorithm [RFC8305] to race 275 connections to the various IPv6 and IPv4 addresses returned by the 276 DNS resolver. 278 If multiple connection attempts are run in parallel, the end of the 279 "race" can be determined in one of two ways: 281 1. The race ends at the completion of the QUIC handshake, once 1-RTT 282 keys are established. 284 2. The race ends upon successful reception the first Handshake 285 Packet received from the server. 287 The first strategy results in potentially longer overlap of 288 connection attempts, but guarantees that the chosen connection 289 instance completes authentication. Thus, the first option SHOULD be 290 used when possible. This also means that the API for QUIC as a 291 transport SHOULD support multiple handshakes running in parallel for 292 the duration of the Happy Eyeballs race. If the application needs to 293 be involved in Identity Valdiation, then it may need to validate 294 identities multiple times for a process that results in a single 295 transport connection. 297 5. Security Considerations 299 The security interface exposed for QUIC as a transport SHOULD be 300 expressed in terms of minimal interactions required for correct 301 behavior. Functionality that MUST be exposed includes Identity 302 Validation (to allow the application to validate a certificate). 303 Functionality that SHOULD NOT be exposed include direct key export 304 for negotiated keys. 306 6. IANA Considerations 308 This document has no request to IANA. 310 7. Acknowledgments 312 Thanks to members of the TAPS working group who helped design and 313 review these mappings. 315 8. Informative References 317 [I-D.ietf-quic-applicability] 318 Kuehlewind, M. and B. Trammell, "Applicability of the QUIC 319 Transport Protocol", draft-ietf-quic-applicability-02 320 (work in progress), July 2018. 322 [I-D.ietf-quic-transport] 323 Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 324 and Secure Transport", draft-ietf-quic-transport-14 (work 325 in progress), August 2018. 327 [I-D.ietf-taps-interface] 328 Trammell, B., Welzl, M., Enghardt, T., Fairhurst, G., 329 Kuehlewind, M., Perkins, C., Tiesel, P., and C. Wood, "An 330 Abstract Application Layer Interface to Transport 331 Services", draft-ietf-taps-interface-01 (work in 332 progress), July 2018. 334 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 335 Requirement Levels", BCP 14, RFC 2119, 336 DOI 10.17487/RFC2119, March 1997, 337 . 339 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 340 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 341 May 2017, . 343 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 344 Better Connectivity Using Concurrency", RFC 8305, 345 DOI 10.17487/RFC8305, December 2017, 346 . 348 Authors' Addresses 350 Tommy Pauly 351 Apple Inc. 352 One Apple Park Way 353 Cupertino, California 95014 354 United States of America 356 Email: tpauly@apple.com 358 Eric Kinnear 359 Apple Inc. 360 One Apple Park Way 361 Cupertino, California 95014 362 United States of America 364 Email: ekinnear@apple.com