Network Working Group T. Pauly Internet-Draft E. Kinnear Intended status: Standards Track Apple Inc. Expires: March 14, 2019 September 10, 2018 An Interface to the QUIC Transport Protocol draft-pauly-quic-interface-00 Abstract This document defines the abstract application interface to the QUIC transport protocol. This allows applications to use a standard interface to directly interact with the QUIC protocol for cases that may not be using an HTTP mapping. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on March 14, 2019. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Pauly & Kinnear Expires March 14, 2019 [Page 1] Internet-Draft QUIC Interface September 2018 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Specification of Requirements . . . . . . . . . . . . . . 3 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. QUIC Streams . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Transport Connection Interface . . . . . . . . . . . . . 3 2.3. Transferring Messages over Streams . . . . . . . . . . . 3 3. API Mappings . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Transport Connection as QUIC Connection . . . . . . . . . 4 3.2. Transport Connection as QUIC Stream . . . . . . . . . . . 5 4. Racing QUIC Connections . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7 8. Informative References . . . . . . . . . . . . . . . . . . . 7 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction The QUIC Transport Protocol [I-D.ietf-quic-transport] defines a mechanism for allowing applications to communicate as clients or servers to securely send and receive data over multiplexed streams associated with a single cryptographic state. While some applications may not need to directly interact with QUIC as a transport if they use HTTP over QUIC, others will need to send and recieve data directly over the transport. Defining a standard application interface to QUIC as a transport has several benefits to applications as they adopt the protocol. These benefits are expressed in the following requirements for a transport interface to QUIC: o Many of the benefits of QUIC, such as reducing head-of-line blocking or being able to send zero-RTT data, can be lost if the transport API does not provide adequate support. The interface SHOULD allow such features to be accessed in a reliable fashion. o Various implementations of the QUIC protocol SHOULD provide similar transport interfaces in order to allow applications to easily adopt them across different platforms and deployments. o The interface to configure QUIC security properties SHOULD be restricted to a standard set of functionality to ensure that applications cannot easily diminish the security properties of the protocol, while still retaining control over the configuration. Pauly & Kinnear Expires March 14, 2019 [Page 2] Internet-Draft QUIC Interface September 2018 1.1. Specification of Requirements The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Background 2.1. QUIC Streams QUIC defines the concept of "streams" of data. Streams may be either bidirectional or unidirectional. For both cases, data in each direction is treated as a reliable in-order sequence of bytes. Streams are transmitted without head-of-line blocking between one another, although data frames for multiple streams may be consolidated into single packets. 2.2. Transport Connection Interface The design of this abstract interface is intended to be compatible with the Transport Services Abstract Interface [I-D.ietf-taps-interface], although it can be used independently. The Transport Services interface defines a Connection as an active transport protocol instance that can send and/or receive Messages between a Local Endpoint and a Remote Endpoint. To avoid confusion with the notion of a QUIC Connection, this definition of a Connection will be referred to as a "Transport Connection Object" in this document. The portions of data that are transferred over the Transport Connection are referred to as Messages. Messages that are sent and received may be associated with metadata and properties in addition to their raw bytes. 2.3. Transferring Messages over Streams The QUIC stream architecture provides several possible mappings of application data into separate streams. Consider a case in which an application wants to send ten separate messages to a peer, and some of these messages expect replies from the remote host. There are two high-level strategies for mapping these messages over QUIC streams: 1. Each message sent is represented as a new stream, and consumes a Stream ID. Any message that expects a reply can use a bidirectional stream, and data sent back on that stream will be Pauly & Kinnear Expires March 14, 2019 [Page 3] Internet-Draft QUIC Interface September 2018 interpreted as the reply. This stategy is descibed in Section 3.1. 2. The messages are sent all over a single bidirectional stream, in order. This requires that the messages are able to encode their boundaries within the byte stream, as well as some message identifier or ordering guarantee to allow correlation of replies with outbound messages. This stategy is descibed in Section 3.2. Strategy (1) relies on QUIC for message delineation and correlation; this may be a benefit if an application does not already define its own message framing. However, if messages already define message boundaries and semantics, strategy (2) may be less redundant. Strategy (1) allows all messages to be delivered without head-of-line blocking, which may be beneficial if there are delays on one stream. However, this approach does not provide any ordering guarantees. If an application will only be able to process messages in a strict order, strategy (2) may be preferable. 3. API Mappings 3.1. Transport Connection as QUIC Connection The mapping of a Transport Connection Object onto an entire QUIC Connection SHOULD be exposed to applications as the "quic-connection" protocol. When this protocol is part of a Protocol Stack being used for a Transport Connection, either as the top-level protocol (the one that the application directly interacts with) or as a protocol in the middle of the stack, each Message object corresponds to a QUIC stream. The description of this mapping will refer to the interation model as if the quic-connection protocol is being used as a top-level protocol. The following API mappings are defined: Initiate: When an application calls Initiate on an outbound connection, and the quic-connection protocol is being used, QUIC MUST initiate its handshake with the Remote Endpoint. The Ready event will be delivered once the handshake is complete and 1-RTT keys have been established. Close: When the application calls Close on its connection, QUIC MUST send a CONNECTION_CLOSE frame to the endpoint if it is currently active. Pauly & Kinnear Expires March 14, 2019 [Page 4] Internet-Draft QUIC Interface September 2018 Send: When the application sends a new Message, QUIC MUST allocate a new stream ID. A metadata option SHOULD be exposed to allow the application to specify whether or not it expects a reply. If it does, the QUIC stream will be bidirectional; if not, the QUIC stream will be unidirectional. The API SHOULD allow the application to configure a default directionality setting on the connection to apply to default Messages. Any data sent associated with the Message Send should be sent in a QUIC stream frame for the new stream ID. Send Idempotent: When the application sends a Message, it may mark it as idempotent, which makes the data eligible for sending under 0-RTT keys. Send End-of-Message: When the application marks the end of a Message, which may be done as part of the first call to Send, or a subsequent call, the associated QUIC stream MUST deliver a FIN. Receive: A call to receive new data from a Connection will invoke the Received event upon receiving new stream data. If a new stream is received from the peer, the Received event will be associated with a new Message object. If the stream data is marked with a FIN, the Received event will indicate that the Message is complete; otherwise, it will indicate that the Message has received partial data. As new data arrives on various streams, Received events will be delivered for various streams, and may result in partial receives be interleaved with one another. If an application does not wish to ever receive partial Messages, it can indicate that in the call to Receive; this means that data will only be delivered on behalf of a QUIC stream once the FIN bit has been received. 3.2. Transport Connection as QUIC Stream The mapping of each Transport Connection Object onto an single QUIC Stream SHOULD be exposed to applications as the "quic-stream" protocol. Messages in this mapping are transferred as in-order chunks of data over a stream represented by the Connection. This Connection is equivalent in contract to a TLS or TCP stream in many ways. The description of this mapping will refer to the interation model as if the quic-stream protocol is being used as a top-level protocol. The following API mappings are defined: Initiate: When an application calls Initiate on an outbound connection, QUIC MUST both start a new handshake with the remote Pauly & Kinnear Expires March 14, 2019 [Page 5] Internet-Draft QUIC Interface September 2018 endpoint and also allocate a new stream ID to be associated with the Transport Connection Object. Clone: When an application calls Clone on an existing outbound Transport Connection Object, and the QUIC connection is not already closed, QUIC MUST allocate a new stream ID and associate that stream with a new Transport Connection Object. Close: If the application calls Close on a connection, QUIC MUST send a FIN on the associated stream if it it has not been marked previously. Send: When the application sends a new Message, QUIC MUST send that data on the associated stream. If the application is using a framing protocol on top of quic-stream, then the message boundaries may be interpreted by the framing protocol. Otherwise, the end of a Message will have no impact on the frames being send by QUIC, unless that Message is also marked Final, in which case the QUIC stream MUST send a FIN. Send Idempotent: When the application sends a Message, it may mark it as idempotent, which makes the data eligible for sending under 0-RTT keys. Receive: A call to Receive will enqueue a request to receive data on the associated QUIC stream only. Once new data is available on the stream, or the stream is remotely closed, the Received event MUST be invoked. If the stream is not allowed to receive data, since it is unidirectional, the Receive call MUST result in a Received event delivering an error. 4. Racing QUIC Connections When a QUIC hostname endpoint is resolved using DNS, a client may want to use the Happy Eyeballs algorithm [RFC8305] to race connections to the various IPv6 and IPv4 addresses returned by the DNS resolver. If multiple connection attempts are run in parallel, the end of the "race" can be determined in one of two ways: 1. The race ends at the completion of the QUIC handshake, once 1-RTT keys are established. 2. The race ends upon successful reception the first Handshake Packet received from the server. Pauly & Kinnear Expires March 14, 2019 [Page 6] Internet-Draft QUIC Interface September 2018 The first strategy results in potentially longer overlap of connection attempts, but guarantees that the chosen connection instance completes authentication. Thus, the first option SHOULD be used when possible. This also means that the API for QUIC as a transport SHOULD support multiple handshakes running in parallel for the duration of the Happy Eyeballs race. If the application needs to be involved in Identity Valdiation, then it may need to validate identities multiple times for a process that results in a single transport connection. 5. Security Considerations The security interface exposed for QUIC as a transport SHOULD be expressed in terms of minimal interactions required for correct behavior. Functionality that MUST be exposed includes Identity Validation (to allow the application to validate a certificate). Functionality that SHOULD NOT be exposed include direct key export for negotiated keys. 6. IANA Considerations This document has no request to IANA. 7. Acknowledgments Thanks to members of the TAPS working group who helped design and review these mappings. 8. Informative References [I-D.ietf-quic-applicability] Kuehlewind, M. and B. Trammell, "Applicability of the QUIC Transport Protocol", draft-ietf-quic-applicability-02 (work in progress), July 2018. [I-D.ietf-quic-transport] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed and Secure Transport", draft-ietf-quic-transport-14 (work in progress), August 2018. [I-D.ietf-taps-interface] Trammell, B., Welzl, M., Enghardt, T., Fairhurst, G., Kuehlewind, M., Perkins, C., Tiesel, P., and C. Wood, "An Abstract Application Layer Interface to Transport Services", draft-ietf-taps-interface-01 (work in progress), July 2018. Pauly & Kinnear Expires March 14, 2019 [Page 7] Internet-Draft QUIC Interface September 2018 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: Better Connectivity Using Concurrency", RFC 8305, DOI 10.17487/RFC8305, December 2017, . Authors' Addresses Tommy Pauly Apple Inc. One Apple Park Way Cupertino, California 95014 United States of America Email: tpauly@apple.com Eric Kinnear Apple Inc. One Apple Park Way Cupertino, California 95014 United States of America Email: ekinnear@apple.com Pauly & Kinnear Expires March 14, 2019 [Page 8]