idnits 2.17.1 draft-kinnear-httpbis-http2-transport-02.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 4, 2019) is 1606 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) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Kinnear 3 Internet-Draft T. Pauly 4 Intended status: Standards Track Apple Inc. 5 Expires: May 7, 2020 November 4, 2019 7 Using HTTP/2 as a Transport for Arbitrary Bytestreams 8 draft-kinnear-httpbis-http2-transport-02 10 Abstract 12 HTTP/2 provides multiplexing of HTTP requests over a single 13 underlying transport connection. HTTP/2 Transport defines the use of 14 the bidirectional extended CONNECT handshake to negotiate the use of 15 application protocols using streams of an HTTP/2 connection as 16 transport. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 7, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 54 2. The SETTINGS_ENABLE_BIDIRECTIONAL_CONNECT Parameter . . . . . 3 55 3. Negotiating Bidirectional Transport . . . . . . . . . . . . . 3 56 3.1. Initiating the Extended CONNECT Handshake . . . . . . . . 4 57 3.2. Responding to the Extended CONNECT Handshake . . . . . . 4 58 4. Using Tunnels Established via the Extended CONNECT Handshake 5 59 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 62 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7 63 8. Normative References . . . . . . . . . . . . . . . . . . . . 7 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 66 1. Introduction 68 HTTP/2 [RFC7540] provides a framing layer that describes the exchange 69 of HTTP messages. This framing layer includes multiplexing of 70 multiple streams on a single underlying transport connection, flow 71 control, stream dependencies and priorities, and exchange of 72 configuration information between endpoints. 74 Section 8.3 of [RFC7540] defines the HTTP CONNECT method for HTTP/2, 75 which converts a HTTP/2 stream into a tunnel for arbitrary data. 76 [RFC8441] describes the use of the extended CONNECT method to 77 negotiate the use of the WebSocket Protocol [RFC6455] on an HTTP/2 78 stream. 80 This document extends the CONNECT handshake to allow both endpoints 81 of an HTTP/2 connection to establish streams that tunnel data. It 82 also defines a protocol name for use in the extended CONNECT 83 handshake that allow negotiation of HTTP/2 streams that transport 84 arbitrary bytestreams. Being able to transport application protocol 85 data on individual HTTP/2 streams allows an underlying connection to 86 be shared by multiple protocols and allows all protocols to benefit 87 from the features provided by HTTP/2 framing. 89 1.1. Notational Conventions 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 93 "OPTIONAL" in this document are to be interpreted as described in BCP 94 14 [RFC2119] [RFC8174] when, and only when, they appear in all 95 capitals, as shown here. 97 2. The SETTINGS_ENABLE_BIDIRECTIONAL_CONNECT Parameter 99 As described in Section 5.5 of [RFC7540], SETTINGS parameters allow 100 endpoints to negotiate use of protocol extensions that would 101 otherwise generate protocol errors. Use of the CONNECT method 102 extension defined in [RFC6455] requires the 103 SETTINGS_ENABLE_CONNECT_PROTOCOL parameter to be received by a client 104 prior to its use. 106 This document introduces another SETTINGS parameter, 107 SETTINGS_ENABLE_BIDIRECTIONAL_CONNECT, which MUST have a value of 0 108 or 1. 110 Once a SETTINGS_ENABLE_BIDIRECTIONAL_CONNECT parameter has been sent 111 with a value of 1, an endpoint MUST NOT send the parameter with a 112 value of 0. 114 Upon receipt of SETTINGS_ENABLE_BIDIRECTIONAL_CONNECT with a value of 115 1, an endpoint MAY use the extended CONNECT defined in [RFC6455] with 116 the protocol values defined in this document. An endpoint that 117 supports receiving the extended CONNECT method SHOULD send this 118 setting with a value of 1. 120 Note that [RFC6455] restricts SETTINGS_ENABLE_CONNECT_PROTOCOL to 121 have no effect if received by a server. This document modifies that 122 restriction and allows both SETTINGS_ENABLE_CONNECT_PROTOCOL and 123 SETTINGS_ENABLE_BIDIRECTIONAL_CONNECT to take effect if received by 124 either endpoint of an HTTP/2 connection. 126 3. Negotiating Bidirectional Transport 128 [RFC6455] defines the psuedo-header field :protocol which can 129 indicate the protocol intended to be used on the tunnel established 130 by the CONNECT method. Values for the :protocol psuedo-header field 131 are maintained in an Upgrade Token Registry established by [RFC7230] 132 for protocol-name tokens. 134 After receiving both SETTINGS_ENABLE_CONNECT_PROTOCOL and 135 SETTINGS_ENABLE_BIDIRECTIONAL_CONNECT, either endpoint of an HTTP/2 136 connection can send a request in HEADERS frames to establish a new 137 stream via the extended CONNECT method. Similarly, either endpoint 138 may be required to respond to an incoming CONNECT request seeking to 139 establish such a stream. 141 3.1. Initiating the Extended CONNECT Handshake 143 Endpoints using this mechanism to establish bidirectional transport 144 over HTTP/2 streams follow the CONNECT handshake procedure defined in 145 [RFC6455]. However, instead of supplying "websocket" for the 146 :protocol psuedo-header field to indicate a WebSocket connection, 147 they negotiate the use of a specific application protocol by 148 specifying an appropriate value. This document registers 149 "bytestream" as a value to be used when an out-of-band negotiation 150 has already occurred and an application protocol wishes to transport 151 arbitrary bytes on an HTTP/2 stream. Any endpoint supplying 152 "bytestream" as a value for the :protocol psuedo-header MUST have 153 previously negotiated the use of this value via another mechanism. 155 The :scheme and :path psuedo-headers are required by [RFC6455]. The 156 scheme of the target URI MUST be set to "https" for all :protocol 157 values. The path is used in the same manner as for the WebSocket 158 protocol, and MAY be set to "/" (an empty path component) if not 159 desired for use. 161 Implementations should note that the Origin, Sec-WebSocket-Version, 162 Sec-WebSocket-Protocol, and Sec-WebSocket-Extensions header fields 163 are not included in the CONNECT request and response header fields, 164 since this handshake mechanism is not being used to negotiate a 165 WebSocket connection. 167 If the response to the extended CONNECT request indicates success of 168 the handshake, then all further data sent or received on the new 169 HTTP/2 stream is considered to be that of the supplied :protocol 170 value and follows the semantics defined by that protocol. 172 3.2. Responding to the Extended CONNECT Handshake 174 A recipient of the extended CONNECT method follows the same procedure 175 outlined by [RFC8441]. 177 If the recipient encounters a :protocol psuedo-header with an unknown 178 value or a value corresponding to a protocol they do not support, or 179 if the recipient encounters violations of the extended CONNECT 180 handshake protocol, they MUST return an HTTP response with an 181 appropriate error code, such as 400 Bad Request. Otherwise, unknown 182 header fields are ignored. 184 Once the handshake has been validated and is considered successful, 185 the responder sends a HTTP response with status 200. After that 186 response, all further data sent or received on the new HTTP/2 stream 187 is considered to be of the supplied :protocol value. 189 4. Using Tunnels Established via the Extended CONNECT Handshake 191 DATA frames are used as usual on the stream established by the 192 CONNECT handshake to transmit data. 194 If the application negotiated the "bytestream" protocol, then 195 individual DATA frames represent segments of an in-order byte stream 196 and are delivered to the application as a stream of bytes. 197 Implementations can deliver data to the application as soon as it 198 becomes available, since there are no message boundaries to preserve. 200 The same considerations around intermediaries as defined in Section 7 201 of [RFC6455] apply to the extended CONNECT method. A client that 202 connects via HTTP/2 to an HTTP proxy SHOULD use a traditional CONNECT 203 request to tunnel through that proxy to the destination server. 205 Streams created via the extended CONNECT method participate in flow 206 control, stream prioritization, and other HTTP/2 features in the same 207 manner as request and response streams defined in [RFC7540]. Stream 208 closure continues to be interpreted as defined in Section 5 of 209 [RFC8441]. 211 Note that the frame type restrictions defined in Section 8.3 of 212 [RFC7540] remain in effect: only DATA, RST_STREAM, WINDOW_UPDATE, and 213 PRIORITY frames are allowed on the connected streams and any other 214 frame types MUST be treated as a stream error (Section 5.4.2 of 215 [RFC7540]) if received. 217 4.1. Example 219 An example of negotiating a "bytestream" stream on an HTTP/2 220 connection follows. This example is intended to closely follow the 221 example in Section 5.1 of [RFC8441] to help illustrate the minor 222 differences defined in this document. 224 [[ From Client ]] [[ From Server ]] 226 SETTINGS 227 SETTINGS_ENABLE_CONNECT_[..] = 1 228 SETTINGS_ENABLE_BIDIRECTIONAL_[..] = 1 230 SETTINGS 231 SETTINGS_ENABLE_CONNECT_[..] = 1 232 SETTINGS_ENABLE_BIDIRECTIONAL_[..] = 1 234 HEADERS + END_HEADERS 235 :method = CONNECT 236 :protocol = bytestream 237 :scheme = https 238 :path = / 239 :authority = server.example.com 241 HEADERS + END_HEADERS 242 :status = 200 244 DATA 245 Bytestream Data 247 DATA + END_STREAM 248 Bytestream Data 250 DATA + END_STREAM 251 Bytestream Data 253 5. IANA Considerations 255 This specification registers an entry in the "HTTP Upgrade Tokens" 256 registry that was established by [RFC7230]. 258 A new token, "bytestream", for arbitrary bytestream data. 260 o Value: bytestream 262 o Description: Arbitrary bidirectional bytestream data 264 o Expected Version Tokens: 266 o References: [[RFC Editor: Please fill in this value with the RFC 267 number for this document.]] 269 6. Security Considerations 271 The tunnels established by the CONNECT handshake are expected to be 272 protected with a TLS connection. They inherit the security 273 properties of this cryptographic context. 275 The security considerations of [RFC8441] Section 8 and [RFC7540] 276 Section 10, and Section 10.5.2 especially, apply to this use of the 277 CONNECT method. 279 7. Acknowledgments 281 Thanks to Anthony Chivetta, Joshua Otto, and Valentin Pistol for 282 their contributions in the design and implementation of this work. 284 8. Normative References 286 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 287 Requirement Levels", BCP 14, RFC 2119, 288 DOI 10.17487/RFC2119, March 1997, 289 . 291 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 292 RFC 6455, DOI 10.17487/RFC6455, December 2011, 293 . 295 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 296 Protocol (HTTP/1.1): Message Syntax and Routing", 297 RFC 7230, DOI 10.17487/RFC7230, June 2014, 298 . 300 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 301 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 302 DOI 10.17487/RFC7540, May 2015, 303 . 305 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 306 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 307 May 2017, . 309 [RFC8441] McManus, P., "Bootstrapping WebSockets with HTTP/2", 310 RFC 8441, DOI 10.17487/RFC8441, September 2018, 311 . 313 Authors' Addresses 315 Eric Kinnear 316 Apple Inc. 317 One Apple Park Way 318 Cupertino, California 95014 319 United States of America 321 Email: ekinnear@apple.com 323 Tommy Pauly 324 Apple Inc. 325 One Apple Park Way 326 Cupertino, California 95014 327 United States of America 329 Email: tpauly@apple.com