idnits 2.17.1 draft-cms-masque-connect-ip-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 : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (27 August 2021) is 971 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 7540 (ref. 'H2') (Obsoleted by RFC 9113) == Outdated reference: A later version (-11) exists of draft-ietf-masque-h3-datagram-03 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7235 (ref. 'AUTH') (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MASQUE A. Chernyakhovsky 3 Internet-Draft D. McCall 4 Intended status: Standards Track D. Schinazi 5 Expires: 28 February 2022 Google LLC 6 27 August 2021 8 The CONNECT-IP HTTP Method 9 draft-cms-masque-connect-ip-02 11 Abstract 13 This document describes the CONNECT-IP HTTP method. CONNECT-IP is 14 similar to CONNECT-UDP, but allows transmitting IP packets, without 15 being limited to just TCP like CONNECT or UDP like CONNECT-UDP. 17 Discussion Venues 19 This note is to be removed before publishing as an RFC. 21 Discussion of this document takes place on the Multiplexed 22 Application Substrate over QUIC Encryption Working Group mailing list 23 (masque@ietf.org), which is archived at 24 https://mailarchive.ietf.org/arch/browse/masque/. 26 Source for this draft and an issue tracker can be found at 27 https://github.com/DavidSchinazi/draft-cms-masque-connect-ip. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 28 February 2022. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 64 2. The CONNECT-IP Method . . . . . . . . . . . . . . . . . . . . 3 65 3. Transmitting IP Packets using HTTP Datagrams . . . . . . . . 4 66 4. Forwarding of IP Packets . . . . . . . . . . . . . . . . . . 4 67 5. Capsules . . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 5.1. ADDRESS_ASSIGN Capsule . . . . . . . . . . . . . . . . . 5 69 5.2. ADDRESS_REQUEST Capsule . . . . . . . . . . . . . . . . . 6 70 5.3. SHUTDOWN Capsule . . . . . . . . . . . . . . . . . . . . 6 71 6. Extensibility Considerations . . . . . . . . . . . . . . . . 7 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 73 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 74 8.1. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 7 75 8.2. Capsule Type Registrations . . . . . . . . . . . . . . . 8 76 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 77 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 78 9.2. Informative References . . . . . . . . . . . . . . . . . 9 79 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 9 80 A.1. Consumer VPN . . . . . . . . . . . . . . . . . . . . . . 9 81 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 10 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 84 1. Introduction 86 This document describes the CONNECT-IP HTTP method. CONNECT-IP is 87 similar to CONNECT-UDP, but allows transmitting IP packets, without 88 being limited to just TCP like CONNECT or UDP like CONNECT-UDP. 90 CONNECT-IP allows endpoints to set up an IP tunnel between one 91 another. This can be used to implement a consumer VPN, point-to- 92 point and point-to-network capabilities as described in [REQS]. 94 1.1. Conventions and Definitions 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in BCP 99 14 [RFC2119] [RFC8174] when, and only when, they appear in all 100 capitals, as shown here. 102 In this document, we use the term "proxy" to refer to the HTTP server 103 that responds to the CONNECT-IP request. If there are HTTP 104 intermediaries (as defined in Section 2.3 of [RFC7230]) between the 105 client and the proxy, those are referred to as "intermediaries" in 106 this document. 108 2. The CONNECT-IP Method 110 The CONNECT-IP method establishes a stream to an endpoint server that 111 then permits the exchange of control data, such as IP address 112 information and other relevant information for successfully 113 transmitting IP datagrams between hosts. 115 The request-target of a CONNECT-IP request is a URI [URI] which uses 116 the "https" scheme and a client-specified path. When using HTTP/2 117 [H2] or later, CONNECT-IP requests use HTTP pseudo-headers with the 118 following requirements: 120 * The ":method" pseudo-header field is set to "CONNECT-IP". 122 * The ":scheme" pseudo-header field is set to "https". 124 * The ":path" pseudo-header field is set to the value provided by 125 the client. That value MUST NOT be empty. 127 * The ":authority" pseudo-header field contains the host and port of 128 the proxy. The target of a CONNECT-IP request is the server 129 providing the CONNECT-IP featureset, not an individual endpoint 130 with which a connection is desired. 132 A CONNECT-IP request that does not conform to these restrictions is 133 malformed (see [H2], Section 8.1.2.6). 135 Any 2xx (Successful) response indicates that the proxy is willing to 136 open an IP tunnel between it and the client. Any response other than 137 a successful response indicates that the tunnel has not yet been 138 formed. 140 A proxy MUST NOT send any Transfer-Encoding or Content-Length header 141 fields in a 2xx (Successful) response to CONNECT-IP. A client MUST 142 treat a successful response to CONNECT-IP containing any Content- 143 Length or Transfer-Encoding header fields as malformed. 145 A payload within a CONNECT-IP request message has no defined 146 semantics; a CONNECT-IP request with a non-empty payload is 147 malformed. Note that the CONNECT-IP stream is used to convey control 148 messages, but they are not semantically part of the request or 149 response themselves. 151 Responses to the CONNECT-IP method are not cacheable. 153 The lifetime of the tunnel is tied to the CONNECT-IP stream. Closing 154 the stream (via the FIN bit on a QUIC STREAM frame, or a QUIC 155 RESET_STREAM frame) closes the associated tunnel. 157 3. Transmitting IP Packets using HTTP Datagrams 159 IP packets are sent using HTTP Datagrams [HTTP-DGRAM]. The HTTP 160 Datagram Payload contains a full IP packet, from the IP Version field 161 until the last byte of the IP Payload. In order to use HTTP 162 Datagrams, the CONNECT-IP client will first decide whether or not to 163 use HTTP Datagram Contexts and then register its context ID (or lack 164 thereof) using the corresponding registration capsule, see 165 [HTTP-DGRAM]. 167 Since HTTP Datagrams require prior negotiation (for example, in 168 HTTP/3 it is necessary to both send and receive the H3_DATAGRAM 169 SETTINGS Parameter), clients MUST NOT send any HTTP Datagrams until 170 they have established support on a given connection. If negotiation 171 of HTTP Datagrams fails (for example if an HTTP/3 SETTINGS frame was 172 received without the H3_DATAGRAM SETTINGS Parameter), the client MUST 173 consider its CONNECT-IP request as failed. 175 4. Forwarding of IP Packets 177 Since CONNECT-IP allows the transmission of IP packets over HTTP, 178 CONNECT-IP endpoints will most often forward these packets to and 179 from traditional IP interfaces. As such, CONNECT-IP endpoints act as 180 IP routers. When a CONNECT-IP endpoint receives an HTTP Datagram 181 containing an IP packet, it will parse the packet's IP header, 182 perform any local policy checks (e.g., source address validation), 183 check their routing table to pick an outbound interface, and then use 184 an implementation-specific mechanism (such as raw sockets) to send 185 the IP packet on that interface. 187 Conversely, when a CONNECT-IP endpoint receives an IP packet whose 188 destination address does not match any local addresses, it consults 189 its routing table to pick a forwarding destination, and if the table 190 points to a CONNECT-IP tunnel, the endpoint performs the same 191 forwarding checks before transmitting the packet inside the tunnel. 193 Note that CONNECT-IP endpoints will decrement the IP Hop Count (or 194 TTL) upon encapsulation but not decapsulation. In other words, the 195 Hop Count is decremented right before an IP packet is transmitted in 196 an HTTP Datagram. This prevents infinite loops in the presence of 197 routing loops, and matches the choices in IPsec [IPSEC]. 199 Endpoints MAY implement additional filtering policies on the IP 200 packets they forward. 202 5. Capsules 204 5.1. ADDRESS_ASSIGN Capsule 206 The ADDRESS_ASSIGN capsule allows an endpoint to inform its peer that 207 it has assigned an IP address to it. It allows assigning a prefix 208 which can contain multiple addresses. This capsule uses a Capsule 209 Type of 0xfff100. Its value uses the following format: 211 ADDRESS_ASSIGN Capsule { 212 IP Version (8), 213 IP Address (32..128), 214 IP Prefix Length (8), 215 } 217 Figure 1: ADDRESS_ASSIGN Capsule Format 219 IP Version: IP Version of this address assignment. MUST be either 4 220 or 6. 222 IP Address: Assigned IP address. If the IP Version field has value 223 4, the IP Address field SHALL have a length of 32 bits. If the IP 224 Version field has value 6, the IP Address field SHALL have a 225 length of 128 bits. 227 IP Prefix Length: Length of the IP Prefix assigned, in bits. MUST 228 be lesser or equal to the length of the IP Address field, in bits. 230 5.2. ADDRESS_REQUEST Capsule 232 The ADDRESS_REQUEST capsule allows an endpoint to request assignment 233 of an IP address from its peer. It allows the endpoint to optionally 234 indicate a preference for which address it would get assigned. This 235 capsule uses a Capsule Type of 0xfff101. Its value uses the 236 following format: 238 ADDRESS_REQUEST Capsule { 239 IP Version (8), 240 IP Address (32..128), 241 IP Prefix Length (8), 242 } 244 Figure 2: ADDRESS_REQUEST Capsule Format 246 IP Version: IP Version of this address request. MUST be either 4 or 247 6. 249 IP Address: Requested IP address. If the IP Version field has value 250 4, the IP Address field SHALL have a length of 32 bits. If the IP 251 Version field has value 6, the IP Address field SHALL have a 252 length of 128 bits. 254 IP Prefix Length: Length of the IP Prefix requested, in bits. MUST 255 be lesser or equal to the length of the IP Address field, in bits. 257 Upon receiving the ADDRESS_REQUEST capsule, an endpoint SHOULD assign 258 an IP address to its peer, and then respond with an ADDRESS_ASSIGN 259 capsule to inform the peer of the assignment. 261 5.3. SHUTDOWN Capsule 263 The SHUTDOWN capsule allows an endpoint to communicate to its peer 264 that it is about to close the CONNECT-IP stream, with a string 265 explaining the reason for the shutdown. This capsule uses a Capsule 266 Type of 0xfff105. Its value uses the following format: 268 SHUTDOWN Capsule { 269 Reason Phrase (..), 270 } 272 Figure 3: SHUTDOWN Capsule Format 274 Reason Phrase: Additional diagnostic information for the shutdown. 276 This SHOULD be a UTF-8 encoded string [UTF8], though the frame 277 does not carry information, such as language tags, that would aid 278 comprehension by any entity other than the one that created the 279 text. 281 Note that the SHUTDOWN capsule is informational, the tunnel is only 282 closed when its corresponding CONNECT-IP stream is closed. Endpoints 283 MAY close the tunnel with a reason phrase by sending the SHUTDOWN 284 capsule with the FIN bit set on the underlying QUIC STREAM frame that 285 carried it. 287 6. Extensibility Considerations 289 CONNECT-IP can be extended via multiple mechanisms to increase 290 functionality. There are three main ways to extend CONNECT-IP: HTTP 291 headers, Capsule Types, and HTTP Datagram Registration Extension 292 Data. For example, an authentication extension could define an HTTP 293 header that allows endpoints to send authentication credentials to 294 their peer during the creation of the tunnel. Alternatively, one 295 could specify an extension that defines a new Capsule Type which 296 allows exchanging DNS configuration between endpoints. Additionally, 297 an extension to CONNECT-IP can use multiple HTTP Datagram Contexts 298 [HTTP-DGRAM] simultaneously to compress some IP packets by 299 associating the compression context with an HTTP Datagram Context ID. 301 7. Security Considerations 303 There are significant risks in allowing arbitrary clients to 304 establish a tunnel to arbitrary servers, as that could allow bad 305 actors to send traffic and have it attributed to the proxy. Proxies 306 that support CONNECT-IP SHOULD restrict its use to authenticated 307 users. The HTTP Authorization header [AUTH] MAY be used to 308 authenticate clients. More complex authentication schemes are out of 309 scope for this document but can be implemented using CONNECT-IP 310 extensions. 312 Since CONNECT-IP endpoints can proxy IP packets send by their peer, 313 they SHOULD follow the guidance in [BCP38] to help prevent denial of 314 service attacks. 316 8. IANA Considerations 318 8.1. HTTP Method 320 This document will request IANA to register "CONNECT-IP" in the HTTP 321 Method Registry (IETF review) maintained at 322 . 324 +-------------+------+------------+---------------+ 325 | Method Name | Safe | Idempotent | Reference | 326 +-------------+------+------------+---------------+ 327 | CONNECT-IP | no | no | This document | 328 +-------------+------+------------+---------------+ 330 8.2. Capsule Type Registrations 332 This document will request IANA to add the following values to the 333 "HTTP Capsule Types" registry created by [HTTP-DGRAM]: 335 +----------+---------------------+---------------------+---------------+ 336 | Value | Type | Description | Reference | 337 +----------+---------------------+---------------------+---------------+ 338 | 0xfff100 | ADDRESS_ASSIGN | Address Assignment | This document | 339 | 0xfff101 | ADDRESS_REQUEST | Address Request | This document | 340 | 0xfff105 | SHUTDOWN | Shutdown Reason | This document | 341 +----------+---------------------+---------------------+---------------+ 343 9. References 345 9.1. Normative References 347 [BCP38] Ferguson, P. and D. Senie, "Network Ingress Filtering: 348 Defeating Denial of Service Attacks which employ IP Source 349 Address Spoofing", BCP 38, RFC 2827, DOI 10.17487/RFC2827, 350 May 2000, . 352 [H2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 353 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 354 DOI 10.17487/RFC7540, May 2015, 355 . 357 [HTTP-DGRAM] 358 Schinazi, D. and L. Pardue, "Using Datagrams with HTTP", 359 Work in Progress, Internet-Draft, draft-ietf-masque-h3- 360 datagram-03, 12 July 2021, 361 . 364 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 365 Requirement Levels", BCP 14, RFC 2119, 366 DOI 10.17487/RFC2119, March 1997, 367 . 369 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 370 Protocol (HTTP/1.1): Message Syntax and Routing", 371 RFC 7230, DOI 10.17487/RFC7230, June 2014, 372 . 374 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 375 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 376 May 2017, . 378 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 379 Resource Identifier (URI): Generic Syntax", STD 66, 380 RFC 3986, DOI 10.17487/RFC3986, January 2005, 381 . 383 [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO 384 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 385 2003, . 387 9.2. Informative References 389 [AUTH] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 390 Protocol (HTTP/1.1): Authentication", RFC 7235, 391 DOI 10.17487/RFC7235, June 2014, 392 . 394 [IPSEC] Kent, S. and K. Seo, "Security Architecture for the 395 Internet Protocol", RFC 4301, DOI 10.17487/RFC4301, 396 December 2005, . 398 [REQS] Chernyakhovsky, A., McCall, D., and D. Schinazi, 399 "Requirements for a MASQUE Protocol to Proxy IP Traffic", 400 Work in Progress, Internet-Draft, draft-ietf-masque-ip- 401 proxy-reqs-03, 27 August 2021, 402 . 405 Appendix A. Examples 407 A.1. Consumer VPN 409 In this scenario, the client will typically receive a single IP 410 address that the proxy has picked from a pool of addresses it 411 maintains. The client will route all traffic through the tunnel. 412 The exchange could look as follows: 414 Client Server 416 ADDRESS_REQUEST --------> 417 IP Version = 4 418 IP Address = 0.0.0.0 419 IP Prefix Length = 0 421 <-------- ADDRESS_ASSIGN 422 IP Version = 4 423 IP Address = 192.0.2.42 424 IP Prefix Length = 32 426 Acknowledgments 428 The design of CONNECT-IP was inspired by discussions in the MASQUE 429 working group around [REQS]. The authors would like to thank 430 participants in those discussions for their feedback. 432 Authors' Addresses 434 Alex Chernyakhovsky 435 Google LLC 436 1600 Amphitheatre Parkway 437 Mountain View, California 94043, 438 United States of America 440 Email: achernya@google.com 442 Dallas McCall 443 Google LLC 444 1600 Amphitheatre Parkway 445 Mountain View, California 94043, 446 United States of America 448 Email: dallasmccall@google.com 450 David Schinazi 451 Google LLC 452 1600 Amphitheatre Parkway 453 Mountain View, California 94043, 454 United States of America 456 Email: dschinazi.ietf@gmail.com