idnits 2.17.1 draft-ietf-httpbis-proxy-status-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 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 (August 11, 2020) is 1354 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 -- Looks like a reference, but probably isn't: '6' on line 838 ** Obsolete normative reference: RFC 8499 (Obsoleted by RFC 9499) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 7 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: February 12, 2021 Google 6 August 11, 2020 8 The Proxy-Status HTTP Response Header Field 9 draft-ietf-httpbis-proxy-status-02 11 Abstract 13 This document defines the Proxy-Status HTTP field to convey the 14 details of intermediary handling of responses, including generated 15 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 February 12, 2021. 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 Field . . . . . . . . . . . . . . . . . 4 66 2.1. Proxy-Status Parameters . . . . . . . . . . . . . . . . . 5 67 2.1.1. next-hop . . . . . . . . . . . . . . . . . . . . . . 5 68 2.1.2. next-protocol . . . . . . . . . . . . . . . . . . . . 5 69 2.1.3. error . . . . . . . . . . . . . . . . . . . . . . . . 6 70 2.1.4. details . . . . . . . . . . . . . . . . . . . . . . . 7 71 2.2. Defining New Proxy-Status Parameters . . . . . . . . . . 7 72 2.3. Proxy Error Types . . . . . . . . . . . . . . . . . . . . 8 73 2.3.1. DNS Timeout . . . . . . . . . . . . . . . . . . . . . 8 74 2.3.2. DNS Error . . . . . . . . . . . . . . . . . . . . . . 8 75 2.3.3. Destination Not Found . . . . . . . . . . . . . . . . 8 76 2.3.4. Destination Unavailable . . . . . . . . . . . . . . . 9 77 2.3.5. Destination IP Prohibited . . . . . . . . . . . . . . 9 78 2.3.6. Destination IP Unroutable . . . . . . . . . . . . . . 9 79 2.3.7. Connection Refused . . . . . . . . . . . . . . . . . 9 80 2.3.8. Connection Terminated . . . . . . . . . . . . . . . . 10 81 2.3.9. Connection Timeout . . . . . . . . . . . . . . . . . 10 82 2.3.10. Connection Read Timeout . . . . . . . . . . . . . . . 10 83 2.3.11. Connection Write Timeout . . . . . . . . . . . . . . 10 84 2.3.12. Connection Limit Reached . . . . . . . . . . . . . . 11 85 2.3.13. TLS Protocol Error . . . . . . . . . . . . . . . . . 11 86 2.3.14. TLS Certificate Error . . . . . . . . . . . . . . . . 11 87 2.3.15. TLS Alert Received . . . . . . . . . . . . . . . . . 11 88 2.3.16. HTTP Request Error . . . . . . . . . . . . . . . . . 12 89 2.3.17. HTTP Request Denied . . . . . . . . . . . . . . . . . 12 90 2.3.18. HTTP Incomplete Response . . . . . . . . . . . . . . 12 91 2.3.19. HTTP Response Header Block Too Large . . . . . . . . 13 92 2.3.20. HTTP Response Header Too Large . . . . . . . . . . . 13 93 2.3.21. HTTP Response Body Too Large . . . . . . . . . . . . 13 94 2.3.22. HTTP Response Transfer-Coding Error . . . . . . . . . 14 95 2.3.23. HTTP Response Content-Coding Error . . . . . . . . . 14 96 2.3.24. HTTP Response Timeout . . . . . . . . . . . . . . . . 14 97 2.3.25. HTTP Upgrade Failed . . . . . . . . . . . . . . . . . 14 98 2.3.26. HTTP Protocol Error . . . . . . . . . . . . . . . . . 15 99 2.3.27. Proxy Internal Response . . . . . . . . . . . . . . . 15 100 2.3.28. Proxy Internal Error . . . . . . . . . . . . . . . . 15 101 2.3.29. Proxy Configuration Error . . . . . . . . . . . . . . 15 102 2.3.30. Proxy Loop Detected . . . . . . . . . . . . . . . . . 16 103 2.4. Defining New Proxy Error Types . . . . . . . . . . . . . 16 104 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 105 4. Security Considerations . . . . . . . . . . . . . . . . . . . 17 106 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 107 5.1. Normative References . . . . . . . . . . . . . . . . . . 17 108 5.2. Informative References . . . . . . . . . . . . . . . . . 18 109 5.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 112 1. Introduction 114 HTTP intermediaries - including both forward proxies and gateways 115 (also known as "reverse proxies") - have become an increasingly 116 significant part of HTTP deployments. In particular, reverse proxies 117 and Content Delivery Networks (CDNs) form part of the critical 118 infrastructure of many Web sites. 120 Typically, HTTP intermediaries forward requests towards the origin 121 server and then forward their responses back to clients. However, if 122 an error occurs before a response is obtained from upstream, the 123 response is generated by the intermediary itself. 125 HTTP accommodates these types of errors with a few status codes; for 126 example, 502 Bad Gateway and 504 Gateway Timeout. However, 127 experience has shown that more information is necessary to aid 128 debugging and communicate what's happened to the client. 130 Additionally, intermediaries sometimes want to convey additional 131 information about their handling of a response, even if they did not 132 generate it. 134 To enable these uses, Section 2 defines a new HTTP response field to 135 allow intermediaries to convey details of their handling of a 136 response, Section 2.1 enumerates the kind of information that can be 137 conveyed, and Section 2.3 defines a set of error types for use when a 138 proxy generates the response. 140 1.1. Notational Conventions 142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 144 "OPTIONAL" in this document are to be interpreted as described in BCP 145 14 [RFC2119] [RFC8174] when, and only when, they appear in all 146 capitals, as shown here. 148 This specification uses Structured Headers 149 [I-D.ietf-httpbis-header-structure] to specify syntax. The terms sf- 150 list, sf-item, sf-string, sf-token, sf-integer and key refer to the 151 structured types defined therein. 153 Note that in this specification, "proxy" is used to indicate both 154 forward and reverse proxies, otherwise known as gateways. "Next hop" 155 indicates the connection in the direction leading to the origin 156 server for the request. 158 2. The Proxy-Status HTTP Field 160 The Proxy-Status HTTP response field allows an intermediary to convey 161 additional information about its handling of a response and its 162 associated request. 164 It is a List [I-D.ietf-httpbis-header-structure]: 166 Proxy-Status = sf-list 168 Each member of the list represents an intermediary that has handled 169 the response. The first member of the list represents the 170 intermediary closest to the origin server, and the last member of the 171 list represents the intermediary closest to the user agent. 173 For example: 175 Proxy-Status: FooProxy, ExampleCDN 177 indicates that this response was handled first by FooProxy and then 178 ExampleCDN. 180 Intermediaries determine when it is appropriate to add the Proxy- 181 Status field to a response. Some might decide to add it to all 182 responses, whereas others might only do so when specifically 183 configured to, or when the request contains a header that activates a 184 debugging mode. 186 The list members identify the intermediary that inserted the value, 187 and MUST have a type of either sf-string or sf-token. Depending on 188 the deployment, this might be a product or service name (e.g., 189 ExampleProxy or "Example CDN"), a hostname ("proxy-3.example.com"), 190 and IP address, or a generated string. 192 Parameters on each member convey additional information about that 193 intermediary's handling of the response; see Section 2.1 for defined 194 parameters. While all of these parameters are OPTIONAL, 195 intermediaries are encouraged to provide as much information as 196 possible. 198 When adding a value to the Proxy-Status field, intermediaries SHOULD 199 preserve the existing contents of the field, to allow debugging of 200 the entire chain of intermediaries handling the request. 202 Proxy-Status MAY be sent in HTTP trailers, but - as with all trailers 203 - it might be silently discarded along the path to the user agent, so 204 this SHOULD NOT be done unless it is not possible to send it in 205 headers. For example, if an intermediary is streaming a response and 206 the upstream connection suddenly terminates, Proxy-Status can be 207 appended to the trailers of the outgoing message (since the headers 208 have already been sent). 210 Note that there are various security considerations for 211 intermediaries using the Proxy-Status field; see Section 4. 213 Origin servers MUST NOT generate the Proxy-Status field. 215 2.1. Proxy-Status Parameters 217 This section lists parameters that can be used on the members of 218 Proxy-Status. 220 2.1.1. next-hop 222 The "next-hop" parameter's value is a sf-string or sf-token that 223 identifies the intermediary or origin server selected (and used, if 224 contacted) for this response. Its contents might be a hostname, IP 225 address, or alias. 227 For example: 229 Proxy-Status: cdn.example.org; next-hop=backend.example.org 231 2.1.2. next-protocol 233 The "next-protocol" parameter's value indicates the ALPN protocol 234 identifier [RFC7301] used by the intermediary to connect to the next 235 hop. This is only applicable when that connection was actually 236 established. 238 The value MUST be either a sf-token or sf-binary. If the protocol 239 identifier is able to be expressed as a sf-token using UTF-8 240 encoding, that form MUST be used. 242 For example: 244 Proxy-Status: "proxy.example.org"; next-protocol=h2 246 2.1.3. error 248 The "error" parameter's value is a sf-token that is a Proxy Error 249 Type. When present, it indicates that the response was generated by 250 the proxy, not the origin server or any other upstream server. 252 Section 2.3 lists the Proxy Error Types defined in this document; new 253 ones can be defined using the procedure outlined in Section 2.4. 255 For example: 257 HTTP/1.1 504 Gateway Timeout 258 Proxy-Status: SomeCDN; error=connection_timeout 260 indicates that this 504 response was generated by SomeCDN, due to a 261 connection timeout when going forward. 263 Or: 265 HTTP/1.1 429 Too Many Requests 266 Proxy-Status: SomeReverseProxy; error=http_request_error 268 indicates that this 429 Too Many Requests response was generated by 269 the intermediary, not the origin. 271 When sending the error parameter, the most specific Proxy Error Type 272 SHOULD be sent, provided that it accurately represents the error 273 condition. If an appropriate Proxy Error Type is not defined, there 274 are a number of generic error types (e.g., proxy_internal_error, 275 http_protocol_error) that can be used. If they are not suitable, 276 consider registering a new Proxy Error Type (see Section 2.4). 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 sf-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. Defining New Proxy-Status Parameters 297 New Proxy-Status Parameters can be defined by registering them in the 298 HTTP Proxy-Status Parameters registry. 300 Registration requests are reviewed and approved by a Designated 301 Expert, as per [RFC8126], Section 4.5. A specification document is 302 appreciated, but not required. 304 The Expert(s) should consider the following factors when evaluating 305 requests: 307 o Community feedback 309 o If the value is sufficiently well-defined 311 o Generic parameters are preferred over vendor-specific, 312 application-specific or deployment-specific values. If a generic 313 value cannot be agreed upon in the community, the parameter's name 314 should be correspondingly specific (e.g., with a prefix that 315 identifies the vendor, application or deployment). 317 Registration requests should use the following template: 319 o Name: [a name for the Proxy-Status Parameter that matches key] 321 o Description: [a description of the parameter semantics and value] 323 o Reference: [to a specification defining this parameter] 325 See the registry at https://iana.org/assignments/http-proxy-status 326 [4] for details on where to send registration requests. 328 2.3. Proxy Error Types 330 This section lists the Proxy Error Types defined by this document. 331 See Section 2.4 for information about defining new Proxy Error Types. 333 2.3.1. DNS Timeout 335 o Name: dns_timeout 337 o Description: The intermediary encountered a timeout when trying to 338 find an IP address for the next hop hostname. 340 o Extra Parameters: None. 342 o Recommended HTTP status code: 504 344 2.3.2. DNS Error 346 o Name: dns_error 348 o Description: The intermediary encountered a DNS error when trying 349 to find an IP address for the next hop hostname. 351 o Extra Parameters: 353 * rcode: A sf-string conveying the DNS RCODE that indicates the 354 error type. See [RFC8499], Section 3. 356 o Recommended HTTP status code: 502 358 2.3.3. Destination Not Found 360 o Name: destination_not_found 362 o Description: The intermediary cannot determine the appropriate 363 next hop to use for this request; for example, it may not be 364 configured. Note that this error is specific to gateways, which 365 typically require specific configuration to identify the "backend" 366 server; forward proxies use in-band information to identify the 367 origin server. 369 o Extra Parameters: None. 371 o Recommended HTTP status code: 500 373 2.3.4. Destination Unavailable 375 o Name: destination_unavailable 377 o Description: The intermediary considers the next hop to be 378 unavailable; e.g., recent attempts to communicate with it may have 379 failed, or a health check may indicate that it is down. 381 o Extra Parameters: None. 383 o Recommended HTTP status code: 503 385 2.3.5. Destination IP Prohibited 387 o Name: destination_ip_prohibited 389 o Description: The intermediary is configured to prohibit 390 connections to the next hop IP address. 392 o Extra Parameters: None. 394 o Recommended HTTP status code: 502 396 2.3.6. Destination IP Unroutable 398 o Name: destination_ip_unroutable 400 o Description: The intermediary cannot find a route to the next hop 401 IP address. 403 o Extra Parameters: None. 405 o Recommended HTTP status code: 502 407 2.3.7. Connection Refused 409 o Name: connection_refused 411 o Description: The intermediary's connection to the next hop was 412 refused. 414 o Extra Parameters: None. 416 o Recommended HTTP status code: 502 418 2.3.8. Connection Terminated 420 o Name: connection_terminated 422 o Description: The intermediary's connection to the next hop was 423 closed before any part of the response was received. If some part 424 was received, see http_response_incomplete. 426 o Extra Parameters: None. 428 o Recommended HTTP status code: 502 430 2.3.9. Connection Timeout 432 o Name: connection_timeout 434 o Description: The intermediary's attempt to open a connection to 435 the next hop timed out. 437 o Extra Parameters: None. 439 o Recommended HTTP status code: 504 441 2.3.10. Connection Read Timeout 443 o Name: connection_read_timeout 445 o Description: The intermediary was expecting data on a connection 446 (e.g., part of a response), but did not receive any new data in a 447 configured time limit. 449 o Extra Parameters: None. 451 o Recommended HTTP status code: 504 453 2.3.11. Connection Write Timeout 455 o Name: connection_write_timeout 457 o Description: The intermediary was attempting to write data to a 458 connection, but was not able to (e.g., because its buffers were 459 full). 461 o Extra Parameters: None. 463 o Recommended HTTP status code: 504 465 2.3.12. Connection Limit Reached 467 o Name: connnection_limit_reached 469 o Description: The intermediary is configured to limit the number of 470 connections it has to the next hop, and that limit has been 471 passed. 473 o Extra Parameters: None. 475 o Recommended HTTP status code: 503 477 2.3.13. TLS Protocol Error 479 o Name: tls_protocol_error 481 o Description: The intermediary encountered a TLS error when 482 communicating with the next hop, either during handshake or 483 afterwards. 485 o Extra Parameters: None. 487 o Recommended HTTP status code: 502 489 Note that additional information about the error can be recorded in 490 the details parameter (as is the case for all errors). 492 2.3.14. TLS Certificate Error 494 o Name: tls_certificate_error 496 o Description: The intermediary encountered an error when verifying 497 the certificate presented by the next hop. 499 o Extra Parameters: None. 501 o Recommended HTTP status code: 502 503 Note that additional information about the error can be recorded in 504 the details parameter (as is the case for all errors). 506 2.3.15. TLS Alert Received 508 o Name: tls_alert_received 510 o Description: The intermediary received a TLS alert from the next 511 hop. 513 o Extra Parameters: 515 * alert_message: a sf-token containing the applicable description 516 string from the TLS Alerts registry. 518 o Recommended HTTP status code: 502 520 2.3.16. HTTP Request Error 522 o Name: http_request_error 524 o Description: The intermediary is generating a client (4xx) 525 response on the origin's behalf. Applicable status codes include 526 (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 527 415, 416, 417, 429. 529 o Extra Parameters: 531 * status_code: a sf-integer containing the generated status code. 533 * status_phrase: a sf-string containing the generated status 534 phrase. 536 o Recommended HTTP status code: The applicable 4xx status code 538 This type helps distinguish between responses generated by 539 intermediaries from those generated by the origin. 541 2.3.17. HTTP Request Denied 543 o Name: http_request_denied 545 o Description: The intermediary rejected the HTTP request based on 546 its configuration and/or policy settings. The request wasn't 547 forwarded to the next hop. 549 o Extra Parameters: None. 551 o Recommended HTTP status code: 403 553 2.3.18. HTTP Incomplete Response 555 o Name: http_response_incomplete 557 o Description: The intermediary received an incomplete response to 558 the request from the next hop. 560 o Extra Parameters: None. 562 o Recommended HTTP status code: 502 564 2.3.19. HTTP Response Header Block Too Large 566 o Name: http_response_header_block_size 568 o Description: The intermediary received a response to the request 569 whose header block was considered too large. 571 o Extra Parameters: 573 * header_block_size: a sf-integer indicating how large the 574 headers received were. Note that they might not be complete; 575 i.e., the intermediary may have discarded or refused additional 576 data. 578 o Recommended HTTP status code: 502 580 2.3.20. HTTP Response Header Too Large 582 o Name: http_response_header_size 584 o Description: The intermediary received a response to the request 585 containing an individual header line that was considered too 586 large. 588 o Extra Parameters: 590 * header_name: a sf-string indicating the name of the header that 591 triggered the error. 593 o Recommended HTTP status code: 502 595 2.3.21. HTTP Response Body Too Large 597 o Name: http_response_body_size 599 o Description: The intermediary received a response to the request 600 whose body was considered too large. 602 o Extra Parameters: 604 * body_size: a sf-integer indicating how large the body received 605 was. Note that it may not have been complete; i.e., the 606 intermediary may have discarded or refused additional data. 608 o Recommended HTTP status code: 502 610 2.3.22. HTTP Response Transfer-Coding Error 612 o Name: http_response_transfer_coding 614 o Description: The intermediary encountered an error decoding the 615 transfer-coding of the response. 617 o Extra Parameters: 619 * coding: a sf-token containing the specific coding that caused 620 the error. 622 o Recommended HTTP status code: 502 624 2.3.23. HTTP Response Content-Coding Error 626 o Name: http_response_content_coding 628 o Description: The intermediary encountered an error decoding the 629 content-coding of the response. 631 o Extra Parameters: 633 * coding: a sf-token containing the specific coding that caused 634 the error. 636 o Recommended HTTP status code: 502 638 2.3.24. HTTP Response Timeout 640 o Name: http_response_timeout 642 o Description: The intermediary reached a configured time limit 643 waiting for the complete response. 645 o Extra Parameters: None. 647 o Recommended HTTP status code: 504 649 2.3.25. HTTP Upgrade Failed 651 o Name: http_upgrade_failed 653 o Description: The HTTP Upgrade between the intermediary and the 654 next hop failed. 656 o Extra Parameters: None. 658 o Recommended HTTP status code: 502 660 2.3.26. HTTP Protocol Error 662 o Name: http_protocol_error 664 o Description: The intermediary encountered a HTTP protocol error 665 when communicating with the next hop. This error should only be 666 used when a more specific one is not defined. 668 o Extra Parameters: None. 670 o Recommended HTTP status code: 502 672 Note that additional information about the error can be recorded in 673 the details parameter (as is the case for all errors). 675 2.3.27. Proxy Internal Response 677 o Name: proxy_internal_response 679 o Description: The intermediary generated the response locally, 680 without attempting to connect to the next hop (e.g. in response to 681 a request to a debug endpoint terminated at the intermediary). 683 o Extra Parameters: None. 685 o Recommended HTTP status code: 687 2.3.28. Proxy Internal Error 689 o Name: proxy_internal_error 691 o Description: The intermediary encountered an internal error 692 unrelated to the origin. 694 o Extra Parameters: None 696 o Recommended HTTP status code: 500 698 Note that additional information about the error can be recorded in 699 the details parameter (as is the case for all errors). 701 2.3.29. Proxy Configuration Error 703 o Name: proxy_configuration_error 704 o Description: The intermediary encountered an error regarding its 705 configuration. 707 o Extra Parameters: None 709 o Recommended HTTP status code: 500 711 Note that additional information about the error can be recorded in 712 the details parameter (as is the case for all errors). 714 2.3.30. Proxy Loop Detected 716 o Name: proxy_loop_detected 718 o Description: The intermediary tried to forward the request to 719 itself, or a loop has been detected using different means (e.g. 720 [RFC8586]). 722 o Extra Parameters: None. 724 o Recommended HTTP status code: 502 726 2.4. Defining New Proxy Error Types 728 New Proxy Error Types can be defined by registering them in the HTTP 729 Proxy Error Types registry. 731 Registration requests are reviewed and approved by a Designated 732 Expert, as per [RFC8126], Section 4.5. A specification document is 733 appreciated, but not required. 735 The Expert(s) should consider the following factors when evaluating 736 requests: 738 o Community feedback 740 o If the value is sufficiently well-defined 742 o Generic types are preferred over vendor-specific, application- 743 specific or deployment-specific values. If a generic value cannot 744 be agreed upon in the community, the types's name should be 745 correspondingly specific (e.g., with a prefix that identifies the 746 vendor, application or deployment). 748 Registration requests should use the following template: 750 o Name: [a name for the Proxy Error Type that matches sf-token] 751 o Description: [a description of the conditions that generate the 752 Proxy Error Type] 754 o Extra Parameters: [zero or more optional parameters, along with 755 their allowable type(s)] 757 o Recommended HTTP status code: [the appropriate HTTP status code 758 for this entry] 760 See the registry at https://iana.org/assignments/http-proxy-status 761 [5] for details on where to send registration requests. 763 3. IANA Considerations 765 Upon publication, please create the HTTP Proxy-Status Parameters 766 registry and the HTTP Proxy Error Types registry at 767 https://iana.org/assignments/http-proxy-statuses [6] and populate 768 them with the types defined in Section 2.1 and Section 2.3 769 respectively; see Section 2.2 and Section 2.4 for its associated 770 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 field. Note that intermediaries are not required to 781 generate a Proxy-Status field in any response, and can conditionally 782 generate them based upon request attributes (e.g., authentication 783 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 Field Values for 793 HTTP", draft-ietf-httpbis-header-structure-19 (work in 794 progress), June 2020. 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-status 836 [5] https://iana.org/assignments/http-proxy-status 838 [6] https://iana.org/assignments/http-proxy-statuses 840 Authors' Addresses 842 Mark Nottingham 843 Fastly 844 made in 845 Prahran, VIC 846 Australia 848 Email: mnot@mnot.net 849 URI: https://www.mnot.net/ 851 Piotr Sikora 852 Google 854 Email: piotrsikora@google.com