idnits 2.17.1 draft-petersson-forwarded-for-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 : ---------------------------------------------------------------------------- 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 seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (November 17, 2011) is 4545 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) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-17 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4395 (Obsoleted by RFC 7595) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Petersson 3 Internet-Draft M. Nilsson 4 Intended status: Standards Track Opera Software 5 Expires: May 20, 2012 November 17, 2011 7 Forwarded HTTP Extension 8 draft-petersson-forwarded-for-02 10 Abstract 12 This document standardizes an HTTP extension header field that allows 13 proxy components to disclose information lost in the proxying 14 process, e.g. the originating IP number of a request or IP number of 15 the proxy on the incoming side. Given a trusted path of proxying 16 components, each subsequent component will have access to all IP 17 numbers used in the chain of proxied HTTP requests. 19 This document also standardizes ways for a proxy administrator to 20 anonymize the origin of a request. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 20, 2012. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 58 3. Syntax Notations . . . . . . . . . . . . . . . . . . . . . . . 3 59 4. Forwarded . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 5. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 5.1. Forwarded by . . . . . . . . . . . . . . . . . . . . . . . 5 62 5.2. Forwarded for . . . . . . . . . . . . . . . . . . . . . . 6 63 5.3. Forwarded host . . . . . . . . . . . . . . . . . . . . . . 6 64 5.4. Forwarded proto . . . . . . . . . . . . . . . . . . . . . 6 65 5.5. Private extensions . . . . . . . . . . . . . . . . . . . . 6 66 5.6. Future extensions . . . . . . . . . . . . . . . . . . . . 6 67 6. Node identifiers . . . . . . . . . . . . . . . . . . . . . . . 6 68 6.1. IPv4 and IPv6 identifiers . . . . . . . . . . . . . . . . 7 69 6.2. The "unknown" identifier . . . . . . . . . . . . . . . . . 7 70 6.3. The "hidden" identifier . . . . . . . . . . . . . . . . . 8 71 6.4. Obfuscated identifier . . . . . . . . . . . . . . . . . . 8 72 7. Implentation considerations . . . . . . . . . . . . . . . . . 8 73 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 74 8.1. Header validity . . . . . . . . . . . . . . . . . . . . . 8 75 8.2. Information Leak . . . . . . . . . . . . . . . . . . . . . 9 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 10.1. Normative references . . . . . . . . . . . . . . . . . . . 9 79 10.2. Informative references . . . . . . . . . . . . . . . . . . 10 80 Appendix A. Forwarded BNF definition . . . . . . . . . . . . . . 10 81 Appendix B. Change Log (to be removed by RFC Editor before 82 publication) . . . . . . . . . . . . . . . . . . . . 11 83 B.1. Since draft-petersson-forwarded-for-00 . . . . . . . . . . 11 84 B.2. Since draft-petersson-forwarded-for-01 . . . . . . . . . . 11 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 87 1. Introduction 89 In today's HTTP landscape, there are a multitude of different 90 applications acting as a proxy for the user agent and effectively 91 anonymizing the requests to look as if they originated from the proxy 92 IP number or in other ways changing the information in the original 93 request. Examples of such applications include caching, content 94 filtering, content compression, crypto offload, and load balancing. 95 As most of the time this destructive behavior is not the primary 96 purpose, or even a desired effect, a way of disclosing the original 97 information on HTTP level instead of depending on the TCP/IP 98 connection remote IP number is needed. 100 Except for the above mentioned problems, there may also be issues due 101 to the use of NAT. This is further discussed in [RFC6269]. 103 A common way to disclose this information is by using the de facto 104 standard header fields such as X-Forwarded-For, X-Forwarded-By, and 105 X-Forwarded-Proto. This document intends to standardize syntax and 106 semantics for disclosing such information. The header field also 107 combines all information within one single header field, making it 108 possible to correlate the header fields to each other. With the 109 header field format described in this document, it is possible to 110 know what information belongs together, given that the proxies are 111 trusted. Such conclusions are not possible to make with the 112 X-Forwarded class of header fields. This new header field also 113 extends the de facto standard of, e.g., X-Forwarded-For with features 114 for which real life deployments have shown a need. 116 2. Notational Conventions 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in [RFC2119]. 122 3. Syntax Notations 124 This specification uses the augmented BNF notation defined in Section 125 2.1 of [RFC2616], including its rules for implied linear whitespace 126 (LWS). 128 The BNF rules for "IPv6address" and "IPv4address" are defined in 129 [RFC3986] The IPv6address SHOULD comply with textual representation 130 recommendations [RFC5952] (e.g., lowercase, zero compression). 132 4. Forwarded 134 The Forwarded HTTP header field is an optional header field that, 135 when used, contains a list of parameter-identifier pairs that 136 disclose information that is altered or lost in a proxy. This 137 applies to forwarding proxies, as well as reverse proxies. 138 Information passed in this header can be, e.g., the source address of 139 the request, the address of the incoming interface on the proxy, or 140 whether HTTP or HTTPS is used. If the request is passing through 141 several proxies, each proxy MAY add any parameters, it MAY also 142 remove earlier added Forwarded-header fields. 144 The top-level list is represented as a list of HTTP header field- 145 values [RFC2616]. The leftmost element in this list holds 146 information added by the first proxy, followed by information added 147 by any subsequent proxy. Each field-value is a semicolon-separated 148 list, this sub-list consists of parameter-identifier pairs. 149 Parameter-identifier pairs are grouped together by an equals sign. 150 The header field can be defined in augmented BNF syntax as 152 Forwarded: = "Forwarded" ":" LWS Forwarded-v 153 Forwarded-v = 1#forwarded-element 155 forwarded-element = 156 OWS forwarded-value *( OWS ";" OWS forwarded-value ) OWS 158 forwarded-value = for-kv | by-kv | proto-kv | host-kv | ext-kv 160 for-kv = "for=" node 161 by-kv = "by=" node 162 proto-kv = "proto=" proto-name 163 host-kv = "host=" host 164 proto-name = ALPHA *( ALPHA | DIGIT | "+" | "-" | "." ) 166 Example: 168 Forwarded: for=192.0.2.43,for=[2001:db8:cafe::17] 169 Forwarded: proto=https;by=198.51.100.60 171 Given that a proxy wishes to add a Forwarded header field to the 172 outgoing request, if the incoming request has no such header field, 173 the proxy simply adds the header with the list of parameters desired. 174 If, on the other hand, the incoming request has such a header field, 175 the proxy simply adds a comma and the list of parameters a proxy MAY 176 remove all Forwarded header fields from a request. It MUST, however, 177 ensure that the correct header field is updated in case of multiple 178 Forwarded header fields. 180 Example: A request from a client with IP number 192.0.2.43 passes 181 through a proxy with IP number 198.51.100.17, then through another 182 proxy with IP number 203.0.113.60 before reaching a origin server. 183 This could, for example, be an office client behind a corporate 184 malware filter talking to a origin server through a reverse proxy. 186 o The HTTP request between the client and the first proxy has no 187 Forwarded header field. 189 o The HTTP request between the first and second proxy has a 190 "Forwarded: for=192.0.2.43" header field. 192 o The HTTP request between the second proxy and the origin server 193 has a "Forwarded: for=192.0.2.43, 194 for=198.51.100.17;by=203.0.113.60;proto=http;host=example.com" 195 header field. 197 Note that, at some points in a connection chain, the information 198 might not be correctly updated in the Forwarded header field, either 199 because of lack of support of this HTTP extension or because of a 200 policy decision not to disclose information about this network 201 component. 203 5. Parameters 205 Valid parameters are as follows: 207 o "by" identifies the incoming interface of the proxy 209 o "for" identifies the node making the request to the proxy 211 o "host" is the host request header-field as received by the proxy 213 o "proto" tells if the request was made in plain text or encrypted 215 5.1. Forwarded by 217 The "by" parameter is used to disclose the interface where the 218 request came in to the proxy server. Typically, the value of this 219 parameter is an IP-address, but it can, however, be some other kind 220 of identifier. The parameter value MUST, however, be a node 221 identifier as described in Section 6. This is primarily added by 222 reverse proxies that wish to forward this information to the backend 223 server. 225 5.2. Forwarded for 227 The "for" parameter is used to disclose information about the user 228 agent that initiated the request. Typically the value of this 229 parameter is an IP-address, but it can also be some other kind of 230 identifier. The parameter value MUST, however, be a node identifier, 231 as described in Section 6. In a chain of proxy servers where this is 232 fully utilized, the first for-parameter will disclose the user agent 233 where the request first was made, followed by any subsequent proxy 234 identifiers. The last proxy in the chain is not part of the list of 235 for-parameters. The last proxy's IP address is, however, readily 236 available as the remote IP address of the TCP/IP connection. 238 5.3. Forwarded host 240 The "host" parameter is used to forward the original value of the 241 "Host" header field. This can be used by the origin server if a 242 reverse proxy is rewriting the "Host" header field to some internal 243 host name. 245 5.4. Forwarded proto 247 The "proto" parameter has the value of the used protocol type. If 248 present, it MUST contain the URI schema name as defined in section 249 3.1 in [RFC3986] and registered to IANA according to [RFC4395]. 250 Typical values are "http" or "https". For example, in an environment 251 where a reverse proxy is also used as a crypto offloader, this allows 252 the origin server to rewrite URLs in a document to match the type of 253 connection as the user agent requested, even though all connections 254 to the origin server are unencrypted HTTP. 256 5.5. Private extensions 258 Private extensions allow for adding own parameters and values. This 259 may be particularly useful in a reverse proxy environment. 261 5.6. Future extensions 263 One may extend this RFC by writing new RFCs that define new 264 parameters. IANA should be notified if an RFC is updating this RFC 265 with new valid parameters. 267 6. Node identifiers 269 The node identifiers are the IP address of the network node, a 270 predefined token hiding the real identity, but signaling that such a 271 component exists in the network path, or a generated token allowing 272 for tracing and debugging without revealing network internals. 274 nodename = IPv4address | IP-literal | 275 "unknown" | "hidden" | obfnode 277 All of the identifiers may optionally have the port identifier, for 278 example, allowing the identification of the end point in a NATted 279 environment. 281 node = nodename [ ":" node-port ] 283 The node-port can be identified either by its TCP port number or by a 284 generated token obfuscating the real port number. If a node-port is 285 appended to an IPv6address, the IPv6address MUST be enclosed by 286 square brackets. 288 node-port = port | obfport 289 port = 1*5DIGIT 290 obfport = 1*(ALPHA | DIGIT) 292 Note that this also allows port numbers to be appended to the 293 "hidden" and the "unknown" identifiers. Interpretation of such 294 notation is, however, left to the possessor of a proxy adding such a 295 value to the header field. To distinguish an obfport from a port, we 296 RECOMMEND that an obfport always should contain at least one ALPHA. 298 6.1. IPv4 and IPv6 identifiers 300 The IPv4address and IPv6address BNF tokens are defined as follows: 302 IPv6address = "[" addr6 "]" 303 addr6 = hexpart [ ":" IPv4address ] 304 IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT 306 hexpart = hexseq | hexseq "::" [ hexseq ] | "::" [ hexseq ] 307 hexseq = hex4 *( ":" hex4) 308 hex4 = 1*4HEXDIG 310 Note that the IP number may be one from the internal nets, as defined 311 in [RFC1918] and [RFC4193]. 313 6.2. The "unknown" identifier 315 The "unknown" identifier is used when the identity of the preceding 316 entity is not known. One example would be a proxy server process 317 generating an outgoing request without direct access to the incoming 318 request TCP socket. 320 6.3. The "hidden" identifier 322 The "hidden" identifier is used when the administrator of a proxy 323 server entity would like to keep the identity of that entity secret 324 but still disclose that it exists. 326 6.4. Obfuscated identifier 328 A generated identifier may be used where there is a wish to keep the 329 internal IP numbers secret, while still allowing the Forwarded header 330 field to be used for tracing and debugging. The identifiers can be 331 randomly generated for each request and do not need to be statically 332 assigned to resources. To distinguish the obfuscated identifier from 333 other identifiers, it MUST have a leading underscore "_". Further, 334 it MUST also consist of only US-ASCII letters and US-ASCII digits. 336 obfnode = "_" 1*( ALPHA | DIGIT ) 338 7. Implentation considerations 340 Note that an HTTP list allows white spaces to occur between the 341 identifiers, and the list may be split over multiple header fields. 342 As an example, the header field 344 Forwarded: for=192.0.2.43,for=[2001:db8:cafe::17],for=unknown 346 is equivalent to the header field 348 Forwarded: for=192.0.2.43, for=[2001:db8:cafe::17], for=unknown 350 which is equivalent to the header fields 352 Forwarded: for=192.0.2.43 353 Forwarded: for=[2001:db8:cafe::17], for=unknown 355 Also, note that the draft [I-D.ietf-httpbis-p1-messaging] renders the 356 use of folding within a list obsolete. The use of CRLF within the 357 field-value list is therefore NOT RECOMMENDED. 359 8. Security Considerations 361 8.1. Header validity 363 The Forwarded HTTP header field cannot be relied upon to be correct, 364 as it may be modified, whether mistakenly or for malicious reasons, 365 by every node on the way to the server, including the client making 366 the request. 368 One approach is to verify the correctness of proxies and whitelist 369 them as trusted. This approach has at least two weaknesses. First, 370 the chain of IP numbers listed before the request came to the proxy 371 cannot be trusted. Second, unless the communication between proxies 372 and the end point is secured, the data can be modified by an attacker 373 with access to the network. 375 8.2. Information Leak 377 The Forwarded HTTP header field can reveal internal structures of the 378 network setup behind the NAT or proxy setup, which may be undesired. 379 This can be addressed either by preventing the internal nodes from 380 updating the HTTP header field or by having an egress proxy removing 381 entries that reveals internal network information. 383 9. IANA Considerations 385 This document specifies the HTTP header listed below, which should be 386 added to the permanent HTTP header registry defined in [RFC3864]. 388 Header field: Forwarded 389 Applicable protocol: http/https 390 Status: standard 391 Author/Change controller: 392 IETF (iesg@ietf.org) 393 Internet Engineering Task Force 394 Specification document(s): this specification (Section 4) 395 Related information: none 397 10. References 399 10.1. Normative references 401 [I-D.ietf-httpbis-p1-messaging] 402 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 403 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 404 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 405 Message Parsing", draft-ietf-httpbis-p1-messaging-17 (work 406 in progress), October 2011. 408 [RFC1918] Rekhter, Y., Moskowitz, R., Karrenberg, D., Groot, G., and 409 E. Lear, "Address Allocation for Private Internets", 410 BCP 5, RFC 1918, February 1996. 412 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 413 Requirement Levels", BCP 14, RFC 2119, March 1997. 415 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 416 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 417 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 419 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 420 Procedures for Message Header Fields", BCP 90, RFC 3864, 421 September 2004. 423 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 424 Resource Identifier (URI): Generic Syntax", STD 66, 425 RFC 3986, January 2005. 427 [RFC4193] Hinden, R. and B. Haberman, "Unique Local IPv6 Unicast 428 Addresses", RFC 4193, October 2005. 430 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 431 Registration Procedures for New URI Schemes", BCP 35, 432 RFC 4395, February 2006. 434 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 435 Address Text Representation", RFC 5952, August 2010. 437 10.2. Informative references 439 [RFC6269] Ford, M., Boucadair, M., Durand, A., Levis, P., and P. 440 Roberts, "Issues with IP Address Sharing", RFC 6269, 441 June 2011. 443 Appendix A. Forwarded BNF definition 445 This appendix defines the Forwarded header field. 447 Forwarded: = "Forwarded" ":" LWS Forwarded-v 448 Forwarded-v = 1#forwarded-element 450 forwarded-element = 451 OWS forwarded-value *( OWS ";" OWS forwarded-value ) OWS 453 forwarded-value = for-kv | by-kv | proto-kv | host-kv | ext-kv 455 for-kv = "for=" node 456 by-kv = "by=" node 457 proto-kv = "proto=" proto-name 458 host-kv = "host=" host 459 ext-kv = extension "=" ext-value 461 node = nodename [ ":" node-port ] 462 nodename = IPv4address | IP-literal | 463 "unknown" | "hidden" | obfnode 464 obfnode = "_" 1*( ALPHA | DIGIT ) 465 node-port = port | obfport 466 port = 1*5DIGIT 467 obfport = 1*( ALPHA | DIGIT ) 468 proto-name = ALPHA *( ALPHA | DIGIT | "+" | "-" | "." ) 469 extension = 1*( ALPHA | DIGIT | "-" ) 470 ext-value = 472 Appendix B. Change Log (to be removed by RFC Editor before 473 publication) 475 B.1. Since draft-petersson-forwarded-for-00 477 Added IANA considerations. 479 Expanded scope and add parameterized list. 481 B.2. Since draft-petersson-forwarded-for-01 483 Removed "x-" from private extensions. 485 Allow for any protocol name. 487 Rename kv-v to forwarded-element and kv to forwarded-value. 489 Add informative reference RFC6269. 491 Authors' Addresses 493 Andreas Petersson 494 Opera Software 495 S:t Larsgatan 12 496 Linkoping SE-582 24 498 Email: pettson@opera.com 500 Martin Nilsson 501 Opera Software 502 S:t Larsgatan 12 503 Linkoping SE-582 24 505 Email: nilsson@opera.com