idnits 2.17.1 draft-ietf-httpbis-proxy-status-01.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 abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 1, 2020) is 1515 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) -- Looks like a reference, but probably isn't: '1' on line 828 -- Looks like a reference, but probably isn't: '2' on line 830 -- Looks like a reference, but probably isn't: '3' on line 832 -- Looks like a reference, but probably isn't: '4' on line 834 -- Looks like a reference, but probably isn't: '5' on line 836 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-header-structure-13 ** Obsolete normative reference: RFC 8499 (Obsoleted by RFC 9499) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft Fastly 4 Intended status: Standards Track P. Sikora 5 Expires: September 2, 2020 Google 6 March 1, 2020 8 The Proxy-Status HTTP Response Header Field 9 draft-ietf-httpbis-proxy-status-01 11 Abstract 13 This document defines the Proxy-Status HTTP header field to convey 14 the details of intermediary handling of responses, including 15 generated errors. 17 Note to Readers 19 _RFC EDITOR: please remove this section before publication_ 21 Discussion of this draft takes place on the HTTP working group 22 mailing list (ietf-http-wg@w3.org), which is archived at 23 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 25 Working Group information can be found at https://httpwg.org/ [2]; 26 source code and issues list for this draft can be found at 27 https://github.com/httpwg/http-extensions/labels/proxy-status [3]. 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 September 2, 2020. 46 Copyright Notice 48 Copyright (c) 2020 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 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 65 2. The Proxy-Status HTTP Header Field . . . . . . . . . . . . . 4 66 2.1. Proxy-Status Parameters . . . . . . . . . . . . . . . . . 5 67 2.1.1. origin . . . . . . . . . . . . . . . . . . . . . . . 5 68 2.1.2. fwd-protocol . . . . . . . . . . . . . . . . . . . . 6 69 2.1.3. error . . . . . . . . . . . . . . . . . . . . . . . . 6 70 2.1.4. details . . . . . . . . . . . . . . . . . . . . . . . 7 71 2.2. Proxy Error Types . . . . . . . . . . . . . . . . . . . . 7 72 2.2.1. DNS Timeout . . . . . . . . . . . . . . . . . . . . . 7 73 2.2.2. DNS Error . . . . . . . . . . . . . . . . . . . . . . 7 74 2.2.3. Destination Not Found . . . . . . . . . . . . . . . . 7 75 2.2.4. Destination Unavailable . . . . . . . . . . . . . . . 8 76 2.2.5. Destination IP Prohibited . . . . . . . . . . . . . . 8 77 2.2.6. Destination IP Unroutable . . . . . . . . . . . . . . 8 78 2.2.7. Connection Refused . . . . . . . . . . . . . . . . . 8 79 2.2.8. Connection Terminated . . . . . . . . . . . . . . . . 9 80 2.2.9. Connection Timeout . . . . . . . . . . . . . . . . . 9 81 2.2.10. Connection Read Timeout . . . . . . . . . . . . . . . 9 82 2.2.11. Connection Write Timeout . . . . . . . . . . . . . . 9 83 2.2.12. Connection Limit Reached . . . . . . . . . . . . . . 10 84 2.2.13. HTTP Incomplete Response . . . . . . . . . . . . . . 10 85 2.2.14. HTTP Protocol Error . . . . . . . . . . . . . . . . . 10 86 2.2.15. HTTP Response Header Block Too Large . . . . . . . . 10 87 2.2.16. HTTP Response Header Too Large . . . . . . . . . . . 11 88 2.2.17. HTTP Response Body Too Large . . . . . . . . . . . . 11 89 2.2.18. HTTP Response Transfer-Coding Error . . . . . . . . . 11 90 2.2.19. HTTP Response Content-Coding Error . . . . . . . . . 12 91 2.2.20. HTTP Response Timeout . . . . . . . . . . . . . . . . 12 92 2.2.21. TLS Handshake Error . . . . . . . . . . . . . . . . . 12 93 2.2.22. TLS Untrusted Peer Certificate . . . . . . . . . . . 12 94 2.2.23. TLS Expired Peer Certificate . . . . . . . . . . . . 13 95 2.2.24. TLS Unexpected Peer Certificate . . . . . . . . . . . 13 96 2.2.25. TLS Missing Proxy Certificate . . . . . . . . . . . . 13 97 2.2.26. TLS Rejected Proxy Certificate . . . . . . . . . . . 14 98 2.2.27. TLS Error . . . . . . . . . . . . . . . . . . . . . . 14 99 2.2.28. HTTP Request Error . . . . . . . . . . . . . . . . . 14 100 2.2.29. HTTP Request Denied . . . . . . . . . . . . . . . . . 15 101 2.2.30. HTTP Upgrade Failed . . . . . . . . . . . . . . . . . 15 102 2.2.31. Proxy Internal Response . . . . . . . . . . . . . . . 15 103 2.2.32. Proxy Internal Error . . . . . . . . . . . . . . . . 15 104 2.2.33. Proxy Loop Detected . . . . . . . . . . . . . . . . . 16 105 2.3. Defining New Proxy Error Types . . . . . . . . . . . . . 16 106 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 107 4. Security Considerations . . . . . . . . . . . . . . . . . . . 17 108 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 109 5.1. Normative References . . . . . . . . . . . . . . . . . . 17 110 5.2. Informative References . . . . . . . . . . . . . . . . . 18 111 5.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 114 1. Introduction 116 HTTP intermediaries - including both forward proxies and gateways 117 (also known as "reverse proxies") - have become an increasingly 118 significant part of HTTP deployments. In particular, reverse proxies 119 and Content Delivery Networks (CDNs) form part of the critical 120 infrastructure of many Web sites. 122 Typically, HTTP intermediaries forward requests towards the origin 123 server and then forward their responses back to clients. However, if 124 an error occurs, the response is generated by the intermediary 125 itself. 127 HTTP accommodates these types of errors with a few status codes; for 128 example, 502 Bad Gateway and 504 Gateway Timeout. However, 129 experience has shown that more information is necessary to aid 130 debugging and communicate what's happened to the client. 132 Additionally, intermediaries sometimes want to convey additional 133 information about their handling of a response, even if they did not 134 generate it. 136 To enable these uses, Section 2 defines a new HTTP response header 137 field to allow intermediaries to convey details of their handling of 138 a response, and Section 2.2 defines a set of Proxy Error Types for 139 use when a proxy generates the response. Section 2.3 explains how to 140 define new Proxy Error Types. 142 1.1. Notational Conventions 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 146 "OPTIONAL" in this document are to be interpreted as described in BCP 147 14 [RFC2119] [RFC8174] when, and only when, they appear in all 148 capitals, as shown here. 150 This specification uses Structured Headers 151 [I-D.ietf-httpbis-header-structure] to specify syntax. The terms sh- 152 param-list, sh-item, sh-string, sh-token and sh-integer refer to the 153 structured types defined therein. 155 Note that in this specification, "proxy" is used to indicate both 156 forward and reverse proxies, otherwise known as gateways. "Next hop" 157 indicates the connection in the direction leading to the origin 158 server for the request. 160 2. The Proxy-Status HTTP Header Field 162 The Proxy-Status HTTP response header field allows an intermediary to 163 convey additional information about its handling of a response and 164 its associated request. 166 It is a Structured Headers [I-D.ietf-httpbis-header-structure] List 167 of parameterised Tokens: 169 Cache-Status = sh-list 171 Each member of the list represents an intermediary that has handled 172 the response. The first member of the list represents the 173 intermediary closest to the origin server, and the last member of the 174 list represents the intermediary closest to the user agent. 176 For example: 178 Proxy-Status: FooProxy, ExampleCDN 180 indicates that this response was handled first by FooAccelerator and 181 then ExampleCDN. 183 Parameters on each member convey additional information about that 184 intermediary's handling of the response; see Section 2.1 for defined 185 parameters. 187 Intermediaries determine when it is appropriate to add the Proxy- 188 Status header field to a response. Some might decide to add it to 189 all responses, whereas others might only do so when specifically 190 configured to, or when the request contains a header that activates a 191 debugging mode. 193 When adding a value to the Proxy-Status header field, intermediaries 194 SHOULD preserve the existing contents of the header, to allow 195 debugging of the entire chain of intermediaries handling the request. 197 The list members identify the intermediary that inserted the value, 198 and MUST have a type of either sh-string or sh-token. Depending on 199 the deployment, this might be a product or service name (e.g., 200 ExampleProxy or "Example CDN"), a hostname ("proxy-3.example.com"), 201 and IP address, or a generated string. 203 Each member of the list can also have a number of parameters that 204 describe that intermediary's handling of the request. While all of 205 these parameters are OPTIONAL, intermediaries are encouraged to 206 provide as much information as possible. 208 Proxy-Status MAY be sent in HTTP trailers, but - as with all trailers 209 - it might be silently discarded along the path to the user agent, so 210 this SHOULD NOT be done unless it is not possible to send it in 211 headers. For example, if an intermediary is streaming a response and 212 the upstream connection suddenly terminates, Proxy-Status can be 213 appended to the trailers of the outgoing message (since the headers 214 have already been sent). 216 Note that there are various security considerations for 217 intermediaries using the Proxy-Status header field; see Section 4. 219 Origin servers MUST NOT generate the Proxy-Status header field. 221 2.1. Proxy-Status Parameters 223 This section lists parameters that can be used on the members of 224 Proxy-Status. 226 2.1.1. origin 228 The "origin" parameter's value is a sh-string or sh-token that 229 identifies the origin server selected (and used, if contacted) for 230 this response. Its contents might be a hostname, IP address, or 231 alias. 233 This is most useful for gateways (also known as "reverse proxies"), 234 since they are often configured to use an origin server other than 235 that which appears in the URL, and sometimes they use several origins 236 to serve a given site. 238 For example: 240 Proxy-Status: cdn.example.org; origin=backend.example.org 242 2.1.2. fwd-protocol 244 The "fwd-protocol" parameter's value is a sh-token indicating the 245 ALPN protocol identifier [RFC7301] used by the intermediary to 246 connect to the next hop. This is only applicable when that 247 connection was actually established. 249 For example: 251 Proxy-Status: "proxy.example.org"; fwd-protocol=h2 253 2.1.3. error 255 The "error" parameter's value is a sh-token that is a Proxy Error 256 Type. When present, it indicates that the response was generated by 257 the proxy, not the origin server or any other upstream server. 259 Section 2.2 lists the Proxy Error Types defined in this document; new 260 ones can be defined using the procedure outlined in Section 2.3. 262 For example: 264 HTTP/1.1 504 Gateway Timeout 265 Proxy-Status: SomeCDN; error=connection_timeout 267 indicates that this 504 response was generated by SomeCDN, due to a 268 connection timeout when going forward. 270 Or: 272 HTTP/1.1 429 Too Many Requests 273 Proxy-Status: SomeReverseProxy; error=http_request_error 275 indicates that this 429 Too Many Requests response was generated by 276 the intermediary, not the origin. 278 Each Proxy Error Type has a Recommended HTTP Status Code. When 279 generating a HTTP response containing "error", its HTTP status code 280 SHOULD be set to the Recommended HTTP Status Code. However, there 281 may be circumstances (e.g., for backwards compatibility with previous 282 behaviours) when another status code might be used. 284 2.1.4. details 286 The "details" parameter's value is a sh-string containing additional 287 information not captured anywhere else. This can include 288 implementation-specific or deployment-specific information. 290 For example: 292 Proxy-Status: ExampleProxy; error="http_protocol_error"; 293 details="Malformed response header - space before colon" 295 2.2. Proxy Error Types 297 This section lists the Proxy Error Types defined by this document. 298 See Section 2.3 for information about defining new Proxy Error Types. 300 2.2.1. DNS Timeout 302 o Name: dns_timeout 304 o Description: The intermediary encountered a timeout when trying to 305 find an IP address for the next hop hostname. 307 o Extra Parameters: None. 309 o Recommended HTTP status code: 504 311 2.2.2. DNS Error 313 o Name: dns_error 315 o Description: The intermediary encountered a DNS error when trying 316 to find an IP address for the next hop hostname. 318 o Extra Parameters: 320 * rcode: A sh-string conveying the DNS RCODE that indicates the 321 error type. See [RFC8499], Section 3. 323 o Recommended HTTP status code: 502 325 2.2.3. Destination Not Found 327 o Name: destination_not_found 329 o Description: The intermediary cannot determine the appropriate 330 next hop to use for this request; for example, it may not be 331 configured. Note that this error is specific to gateways, which 332 typically require specific configuration to identify the "backend" 333 server; forward proxies use in-band information to identify the 334 origin server. 336 o Extra Parameters: None. 338 o Recommended HTTP status code: 500 340 2.2.4. Destination Unavailable 342 o Name: destination_unavailable 344 o Description: The intermediary considers the next hop to be 345 unavailable; e.g., recent attempts to communicate with it may have 346 failed, or a health check may indicate that it is down. 348 o Extra Parameters: None. 350 o Recommended HTTP status code: 503 352 2.2.5. Destination IP Prohibited 354 o Name: destination_ip_prohibited 356 o Description: The intermediary is configured to prohibit 357 connections to the next hop IP address. 359 o Extra Parameters: None. 361 o Recommended HTTP status code: 502 363 2.2.6. Destination IP Unroutable 365 o Name: destination_ip_unroutable 367 o Description: The intermediary cannot find a route to the next hop 368 IP address. 370 o Extra Parameters: None. 372 o Recommended HTTP status code: 502 374 2.2.7. Connection Refused 376 o Name: connection_refused 378 o Description: The intermediary's connection to the next hop was 379 refused. 381 o Extra Parameters: None. 383 o Recommended HTTP status code: 502 385 2.2.8. Connection Terminated 387 o Name: connection_terminated 389 o Description: The intermediary's connection to the next hop was 390 closed before any part of the response was received. If some part 391 was received, see http_response_incomplete. 393 o Extra Parameters: None. 395 o Recommended HTTP status code: 502 397 2.2.9. Connection Timeout 399 o Name: connection_timeout 401 o Description: The intermediary's attempt to open a connection to 402 the next hop timed out. 404 o Extra Parameters: None. 406 o Recommended HTTP status code: 504 408 2.2.10. Connection Read Timeout 410 o Name: connection_read_timeout 412 o Description: The intermediary was expecting data on a connection 413 (e.g., part of a response), but did not receive any new data in a 414 configured time limit. 416 o Extra Parameters: None. 418 o Recommended HTTP status code: 504 420 2.2.11. Connection Write Timeout 422 o Name: connection_write_timeout 424 o Description: The intermediary was attempting to write data to a 425 connection, but was not able to (e.g., because its buffers were 426 full). 428 o Extra Parameters: None. 430 o Recommended HTTP status code: 504 432 2.2.12. Connection Limit Reached 434 o Name: connnection_limit_reached 436 o Description: The intermediary is configured to limit the number of 437 connections it has to the next hop, and that limit has been 438 passed. 440 o Extra Parameters: None. 442 o Recommended HTTP status code: 503 444 2.2.13. HTTP Incomplete Response 446 o Name: http_response_incomplete 448 o Description: The intermediary received an incomplete response to 449 the request from the next hop. 451 o Extra Parameters: None. 453 o Recommended HTTP status code: 502 455 2.2.14. HTTP Protocol Error 457 o Name: http_protocol_error 459 o Description: The intermediary encountered a HTTP protocol error 460 when communicating with the next hop. This error should only be 461 used when a more specific one is not defined. 463 o Extra Parameters: None. 465 o Recommended HTTP status code: 502 467 2.2.15. HTTP Response Header Block Too Large 469 o Name: http_response_header_block_size 471 o Description: The intermediary received a response to the request 472 whose header block was considered too large. 474 o Extra Parameters: 476 * header_block_size: a sh-integer indicating how large the 477 headers received were. Note that they might not be complete; 478 i.e., the intermediary may have discarded or refused additional 479 data. 481 o Recommended HTTP status code: 502 483 2.2.16. HTTP Response Header Too Large 485 o Name: http_response_header_size 487 o Description: The intermediary received a response to the request 488 containing an individual header line that was considered too 489 large. 491 o Extra Parameters: 493 * header_name: a sh-string indicating the name of the header that 494 triggered the error. 496 o Recommended HTTP status code: 502 498 2.2.17. HTTP Response Body Too Large 500 o Name: http_response_body_size 502 o Description: The intermediary received a response to the request 503 whose body was considered too large. 505 o Extra Parameters: 507 * body_size: a sh-integer indicating how large the body received 508 was. Note that it may not have been complete; i.e., the 509 intermediary may have discarded or refused additional data. 511 o Recommended HTTP status code: 502 513 2.2.18. HTTP Response Transfer-Coding Error 515 o Name: http_response_transfer_coding 517 o Description: The intermediary encountered an error decoding the 518 transfer-coding of the response. 520 o Extra Parameters: 522 * coding: a sh-token containing the specific coding that caused 523 the error. 525 o Recommended HTTP status code: 502 527 2.2.19. HTTP Response Content-Coding Error 529 o Name: http_response_content_coding 531 o Description: The intermediary encountered an error decoding the 532 content-coding of the response. 534 o Extra Parameters: 536 * coding: a sh-token containing the specific coding that caused 537 the error. 539 o Recommended HTTP status code: 502 541 2.2.20. HTTP Response Timeout 543 o Name: http_response_timeout 545 o Description: The intermediary reached a configured time limit 546 waiting for the complete response. 548 o Extra Parameters: None. 550 o Recommended HTTP status code: 504 552 2.2.21. TLS Handshake Error 554 o Name: tls_handshake_error 556 o Description: The intermediary encountered an error during TLS 557 handshake with the next hop. 559 o Extra Parameters: 561 * alert_message: a sh-token containing the applicable description 562 string from the TLS Alerts registry. 564 o Recommended HTTP status code: 502 566 2.2.22. TLS Untrusted Peer Certificate 568 o Name: tls_untrusted_peer_certificate 570 o Description: The intermediary received an untrusted peer 571 certificate during TLS handshake with the next hop. 573 o Extra Parameters: None. 575 o Recommended HTTP status code: 502 577 2.2.23. TLS Expired Peer Certificate 579 o Name: tls_expired_peer_certificate 581 o Description: The intermediary received an expired peer certificate 582 during TLS handshake with the next hop. 584 o Extra Parameters: None. 586 o Recommended HTTP status code: 502 588 2.2.24. TLS Unexpected Peer Certificate 590 o Name: tls_unexpected_peer_certificate 592 o Description: The intermediary received an unexpected peer 593 certificate (e.g., SPKI doesn't match) during the TLS handshake 594 with the next hop. 596 o Extra Parameters: 598 * identity: a sh-string containing a comma-separated list of 599 Subject Alternative Names from the certificate received from 600 the next hop. 602 * sha256: a sh-string containing the hex-encoded SHA-256 of the 603 certificate received from the next hop. 605 * spki: a sh-string containing the base64-encoded SHA-256 of the 606 Subject Public Key Info (SPKI) from the certificate received 607 from the next hop. 609 o Recommended HTTP status code: 502 611 2.2.25. TLS Missing Proxy Certificate 613 o Name: tls_missing_proxy_certificate 615 o Description: The next hop requested a client certificate from the 616 intermediary during TLS handshake, but it wasn't configured with 617 one. 619 o Extra Parameters: None. 621 o Recommended HTTP status code: 500 623 2.2.26. TLS Rejected Proxy Certificate 625 o Name: tls_rejected_proxy_certificate 627 o Description: The next hop rejected the client certificate provided 628 by the intermediary during TLS handshake. 630 o Extra Parameters: None. 632 o Recommended HTTP status code: 500 634 2.2.27. TLS Error 636 o Name: tls_error 638 o Description: The intermediary encountered a TLS error when 639 communicating with the next hop. 641 o Extra Parameters: 643 * alert_message: a sh-token containing the applicable description 644 string from the TLS Alerts registry. 646 o Recommended HTTP status code: 502 648 2.2.28. HTTP Request Error 650 o Name: http_request_error 652 o Description: The intermediary is generating a client (4xx) 653 response on the origin's behalf. Applicable status codes include 654 (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 655 415, 416, 417, 429. 657 o Extra Parameters: 659 * status_code: a sh-integer containing the generated status code. 661 * status_phrase: a sh-string containing the generated status 662 phrase. 664 o Recommended HTTP status code: The applicable 4xx status code 666 This type helps distinguish between responses generated by 667 intermediaries from those generated by the origin. 669 2.2.29. HTTP Request Denied 671 o Name: http_request_denied 673 o Description: The intermediary rejected the HTTP request based on 674 its configuration and/or policy settings. The request wasn't 675 forwarded to the next hop. 677 o Extra Parameters: None. 679 o Recommended HTTP status code: 400 681 2.2.30. HTTP Upgrade Failed 683 o Name: http_upgrade_failed 685 o Description: The HTTP Upgrade between the intermediary and the 686 next hop failed. 688 o Extra Parameters: None. 690 o Recommended HTTP status code: 502 692 2.2.31. Proxy Internal Response 694 o Name: proxy_internal_response 696 o Description: The intermediary generated the response locally, 697 without attempting to connect to the next hop (e.g. in response to 698 a request to a debug endpoint terminated at the intermediary). 700 o Extra Parameters: None. 702 o Recommended HTTP status code: 704 2.2.32. Proxy Internal Error 706 o Name: proxy_internal_error 708 o Description: The intermediary encountered an internal error 709 unrelated to the origin. 711 o Extra Parameters: 713 * error: a sh-string containing details about the error 714 condition. 716 o Recommended HTTP status code: 500 718 2.2.33. Proxy Loop Detected 720 o Name: proxy_loop_detected 722 o Description: The intermediary tried to forward the request to 723 itself, or a loop has been detected using different means (e.g. 724 [RFC8586]). 726 o Extra Parameters: None. 728 o Recommended HTTP status code: 502 730 2.3. Defining New Proxy Error Types 732 New Proxy Error Types can be defined by registering them in the HTTP 733 Proxy Error Types registry. 735 Registration requests are reviewed and approved by a Designated 736 Expert, as per [RFC8126], Section 4.5. A specification document is 737 appreciated, but not required. 739 The Expert(s) should consider the following factors when evaluating 740 requests: 742 o Community feedback 744 o If the value is sufficiently well-defined 746 o If the value is generic; vendor-specific, application-specific and 747 deployment-specific values are discouraged 749 Registration requests should use the following template: 751 o Name: [a name for the Proxy Error Type that is matches sh-token] 753 o Description: [a description of the conditions that generate the 754 Proxy Error Type] 756 o Extra Parameters: [zero or more optional parameters, along with 757 their allowable type(s)] 759 o Recommended HTTP status code: [the appropriate HTTP status code 760 for this entry] 762 See the registry at https://iana.org/assignments/http-proxy-statuses 763 [4] for details on where to send registration requests. 765 3. IANA Considerations 767 Upon publication, please create the HTTP Proxy Error Types registry 768 at https://iana.org/assignments/http-proxy-statuses [5] and populate 769 it with the types defined in Section 2.2; see Section 2.3 for its 770 associated procedures. 772 4. Security Considerations 774 One of the primary security concerns when using Proxy-Status is 775 leaking information that might aid an attacker. For example, 776 information about the intermediary's configuration and back-end 777 topology can be exposed. 779 As a result, care needs to be taken when deciding to generate a 780 Proxy-Status header. Note that intermediaries are not required to 781 generate a Proxy-Status header field in any response, and can 782 conditionally generate them based upon request attributes (e.g., 783 authentication tokens, IP address). 785 Likewise, generation of all parameters is optional. 787 5. References 789 5.1. Normative References 791 [I-D.ietf-httpbis-header-structure] 792 Nottingham, M. and P. Kamp, "Structured Headers for HTTP", 793 draft-ietf-httpbis-header-structure-13 (work in progress), 794 August 2019. 796 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 797 Requirement Levels", BCP 14, RFC 2119, 798 DOI 10.17487/RFC2119, March 1997, 799 . 801 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 802 "Transport Layer Security (TLS) Application-Layer Protocol 803 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 804 July 2014, . 806 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 807 Writing an IANA Considerations Section in RFCs", BCP 26, 808 RFC 8126, DOI 10.17487/RFC8126, June 2017, 809 . 811 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 812 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 813 May 2017, . 815 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 816 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 817 January 2019, . 819 5.2. Informative References 821 [RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop 822 Detection in Content Delivery Networks (CDNs)", RFC 8586, 823 DOI 10.17487/RFC8586, April 2019, 824 . 826 5.3. URIs 828 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 830 [2] https://httpwg.org/ 832 [3] https://github.com/httpwg/http-extensions/labels/proxy-status 834 [4] https://iana.org/assignments/http-proxy-statuses 836 [5] https://iana.org/assignments/http-proxy-statuses 838 Authors' Addresses 840 Mark Nottingham 841 Fastly 843 Email: mnot@mnot.net 844 URI: https://www.mnot.net/ 846 Piotr Sikora 847 Google 849 Email: piotrsikora@google.com