Internet DRAFT - draft-pauly-quic-interface
draft-pauly-quic-interface
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,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2:
Better Connectivity Using Concurrency", RFC 8305,
DOI 10.17487/RFC8305, December 2017,
<https://www.rfc-editor.org/info/rfc8305>.
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]
