idnits 2.17.1 draft-ietf-httpbis-bcp56bis-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. -- The draft header indicates that this document obsoletes RFC3205, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 28, 2018) is 2248 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (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 962 -- Looks like a reference, but probably isn't: '2' on line 964 -- Looks like a reference, but probably isn't: '3' on line 966 -- Looks like a reference, but probably isn't: '4' on line 968 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 2821 (Obsoleted by RFC 5321) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 11 errors (**), 0 flaws (~~), 1 warning (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft February 28, 2018 4 Obsoletes: 3205 (if approved) 5 Intended status: Best Current Practice 6 Expires: September 1, 2018 8 On the use of HTTP as a Substrate 9 draft-ietf-httpbis-bcp56bis-02 11 Abstract 13 HTTP is often used as a substrate for other application protocols. 14 This document specifies best practices for these protocols' use of 15 HTTP. 17 Note to Readers 19 Discussion of this draft takes place on the HTTP working group 20 mailing list (ietf-http-wg@w3.org), which is archived at 21 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 23 Working Group information can be found at http://httpwg.github.io/ 24 [2]; source code and issues list for this draft can be found at 25 https://github.com/httpwg/http-extensions/labels/bcp56bis [3]. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on September 1, 2018. 44 Copyright Notice 46 Copyright (c) 2018 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 63 2. Is HTTP Being Used? . . . . . . . . . . . . . . . . . . . . . 4 64 3. What's Important About HTTP . . . . . . . . . . . . . . . . . 5 65 3.1. Generic Semantics . . . . . . . . . . . . . . . . . . . . 5 66 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3.3. Getting Value from HTTP . . . . . . . . . . . . . . . . . 6 68 4. Best Practices for Using HTTP . . . . . . . . . . . . . . . . 7 69 4.1. Specifying the Use of HTTP . . . . . . . . . . . . . . . 7 70 4.2. Defining HTTP Resources . . . . . . . . . . . . . . . . . 8 71 4.3. Specifying Client Behaviours . . . . . . . . . . . . . . 9 72 4.4. HTTP URLs . . . . . . . . . . . . . . . . . . . . . . . . 10 73 4.4.1. Initial URL Discovery . . . . . . . . . . . . . . . . 10 74 4.4.2. URL Schemes . . . . . . . . . . . . . . . . . . . . . 10 75 4.4.3. Transport Ports . . . . . . . . . . . . . . . . . . . 12 76 4.5. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 12 77 4.6. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 12 78 4.7. HTTP Header Fields . . . . . . . . . . . . . . . . . . . 13 79 4.8. Defining Message Payloads . . . . . . . . . . . . . . . . 15 80 4.9. Authentication and Application State . . . . . . . . . . 15 81 4.10. Co-Existing with Web Browsing . . . . . . . . . . . . . . 15 82 4.11. Co-Existing with Other Applications . . . . . . . . . . . 16 83 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 85 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 86 7.1. Normative References . . . . . . . . . . . . . . . . . . 17 87 7.2. Informative References . . . . . . . . . . . . . . . . . 19 88 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 21 89 Appendix A. Changes from RFC3205 . . . . . . . . . . . . . . . . 21 90 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 92 1. Introduction 94 HTTP [RFC7230] is often used as a substrate for other application 95 protocols. This is done for a variety of reasons, including: 97 o familiarity by implementers, specifiers, administrators, 98 developers and users, 100 o availability of a variety of client, server and proxy 101 implementations, 103 o ease of use, 105 o ubiquity of Web browsers, 107 o reuse of existing mechanisms like authentication and encryption, 109 o presence of HTTP servers and clients in target deployments, and 111 o its ability to traverse firewalls. 113 The Internet community has a long tradition of protocol reuse, dating 114 back to the use of Telnet [RFC0854] as a substrate for FTP [RFC0959] 115 and SMTP [RFC2821]. However, layering new protocols over HTTP brings 116 its own set of issues: 118 o Should an application using HTTP define a new URL scheme? Use new 119 ports? 121 o Should it use standard HTTP methods and status codes, or define 122 new ones? 124 o How can the maximum value be extracted from the use of HTTP? 126 o How does it coexist with other uses of HTTP - especially Web 127 browsing? 129 o How can interoperability problems and "protocol dead ends" be 130 avoided? 132 This document contains best current practices regarding the use of 133 HTTP by applications other than Web browsing. Section 2 defines what 134 applications it applies to; Section 3 surveys the properties of HTTP 135 that are important to preserve, and Section 4 conveys best practices 136 for those applications that do use HTTP. 138 It is written primarily to guide IETF efforts to define application 139 protocols using HTTP for deployment on the Internet, but might be 140 applicable in other situations. Note that the requirements herein do 141 not necessarily apply to the development of generic HTTP extensions. 143 1.1. Notational Conventions 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 147 "OPTIONAL" in this document are to be interpreted as described in BCP 148 14 [RFC2119] [RFC8174] when, and only when, they appear in all 149 capitals, as shown here. 151 2. Is HTTP Being Used? 153 Different applications have different goals when using HTTP. In this 154 document, we say an application is _using HTTP_ when any of the 155 following conditions are true: 157 o The transport port in use is 80 or 443, 159 o The URL scheme "http" or "https" is used, 161 o The ALPN protocol ID [RFC7301] generically identifies HTTP (e.g., 162 "http/1.1", "h2", "h2c"), or 164 o The IANA registries defined for HTTP are updated or modified. 166 When an application is using HTTP, all of the requirements of the 167 HTTP protocol suite (including but not limited to [RFC7230], 168 [RFC7231], [RFC7232], [RFC7233], [RFC7234], [RFC7235] and [RFC7540]) 169 are in force. 171 An application might not be _using HTTP_ according to this 172 definition, but still relying upon the HTTP specifications in some 173 manner. For example, an application might wish to avoid re- 174 specifying parts of the message format, but change others; or, it 175 might want to use a different set of methods. 177 Such applications are referred to as _protocols based upon HTTP_ in 178 this document. These have more freedom to modify protocol operation, 179 but are also likely to lose at least a portion of the benefits 180 outlined above, as most HTTP implementations won't be easily 181 adaptable to these changes, and as the protocol diverges from HTTP, 182 the benefit of mindshare will be lost. 184 Protocols that are based upon HTTP MUST NOT reuse HTTP's URL schemes, 185 transport ports, ALPN protocol IDs or IANA registries; rather, they 186 are encouraged to establish their own. 188 3. What's Important About HTTP 190 There are many ways that applications using HTTP are defined and 191 deployed, and sometimes they are brought to the IETF for 192 standardisation. In that process, what might be workable for 193 deployment in a limited fashion isn't appropriate for standardisation 194 and the corresponding broader deployment. 196 This section examines the facets of the protocol that are important 197 to preserve in these situations. 199 3.1. Generic Semantics 201 When writing an application's specification, it's often tempting to 202 specify exactly how HTTP is to be implemented, supported and used. 204 However, this can easily lead to an unintended profile of HTTP's 205 behaviour. For example, it's common to see specifications with 206 language like this: 208 A `200 OK` response means that the widget has successfully been updated. 210 This sort of specification is bad practice, because it is adding new 211 semantics to HTTP's status codes and methods, respectively; a 212 recipient - whether it's an origin server, client library, 213 intermediary or cache - now has to know these extra semantics to 214 understand the message. 216 Some applications even require specific behaviours, such as: 218 A `POST` request MUST result in a `201 Created` response. 220 This forms an expectation in the client that the response will always 221 be "201 Created", when in fact there are a number of reasons why the 222 status code might differ in a real deployment. If the client does 223 not anticipate this, the application's deployment is brittle. 225 Much of the value of HTTP is in its _generic semantics_ - that is, 226 the protocol elements defined by HTTP are potentially applicable to 227 every resource, not specific to a particular context. Application- 228 specific semantics are expressed in the payload; mostly, in the body, 229 but also in header fields. 231 This allows a HTTP message to be examined by generic HTTP software 232 (e.g., HTTP servers, intermediaries, client implementations), and its 233 handling to be correctly determined. It also allows people to 234 leverage their knowledge of HTTP semantics without special-casing 235 them for a particular application. 237 Therefore, applications that use HTTP MUST NOT re-define, refine or 238 overlay the semantics of defined protocol elements. Instead, they 239 SHOULD focus their specifications on protocol elements that are 240 specific to that application; namely their HTTP resources. 242 See Section 4.2 for details. 244 3.2. Links 246 Another common practice is assuming that the HTTP server's name space 247 (or a portion thereof) is exclusively for the use of a single 248 application. This effectively overlays special, application-specific 249 semantics onto that space, precludes other applications from using 250 it. 252 As explained in [RFC7320], such "squatting" on a part of the URL 253 space by a standard usurps the server's authority over its own 254 resources, can cause deployment issues, and is therefore bad practice 255 in standards. 257 Instead of statically defining URL components like paths, it is 258 RECOMMENDED that applications using HTTP define links in payloads, to 259 allow flexibility in deployment. 261 Using runtime links in this fashion has a number of other benefits. 262 For example, navigating with a link allows a request to be routed to 263 a different server without the overhead of a redirection, thereby 264 supporting deployment across machines well. It becomes possible to 265 "mix" different applications on the same server, and offers a natural 266 path for extensibility, versioning and capability management. 268 3.3. Getting Value from HTTP 270 The simplest possible use of HTTP is to POST data to a single URL, 271 thereby effectively tunnelling through the protocol. 273 This "RPC" style of communication does get some benefit from using 274 HTTP - namely, message framing and the availability of 275 implementations - but fails to realise many others when used 276 exclusively: 278 o Caching for server scalability, latency and bandwidth reduction, 279 and reliability; 281 o Granularity of access control (through use of a rich space of 282 URLs); 284 o Partial content to selectively request part of a response; 285 o Definition of an information space using URLs; and 287 o The ability to interact with the application easily using a Web 288 browser. 290 Using such a high-level protocol to tunnel simple semantics has 291 downsides too; because of its more advanced capabilities, breadth of 292 deployment and age, HTTP's complexity can cause interoperability 293 problems that could be avoided by using a simpler substrate (e.g., 294 WebSockets [RFC6455], if browser support is necessary, or TCP 295 [RFC0793] if not), or making the application be _based upon HTTP_, 296 instead of using it (as defined in Section 2). 298 Applications that use HTTP are encouraged to accommodate the various 299 features that the protocol offers, so that their users receive the 300 maximum benefit from it. This document does not require specific 301 features to be used, since the appropriate design tradeoffs are 302 highly specific to a given situation. However, following the 303 practices in Section 4 will help make them available. 305 4. Best Practices for Using HTTP 307 This section contains best practices regarding the use of HTTP by 308 applications, including practices for specific HTTP protocol 309 elements. 311 4.1. Specifying the Use of HTTP 313 When specifying the use of HTTP, an application SHOULD use [RFC7230] 314 as the primary reference; it is not necessary to reference all of the 315 specifications in the HTTP suite unless there are specific reasons to 316 do so (e.g., a particular feature is called out). 318 Applications using HTTP MAY specify a minimum version to be supported 319 (HTTP/1.1 is suggested), and MUST NOT specify a maximum version. 321 Likewise, applications need not specify what HTTP mechanisms - such 322 as redirection, caching, authentication, proxy authentication, and so 323 on - are to be supported. Full featured support for HTTP SHOULD be 324 taken for granted in servers and clients, and the application's 325 function SHOULD degrade gracefully if they are not (although this 326 might be achieved by informing the user that their task cannot be 327 completed). 329 For example, an application can specify that it uses HTTP like this: 331 Foo Application uses HTTP {{RFC7230}}. Implementations MUST support 332 HTTP/1.1, and MAY support later versions. Support for common HTTP 333 mechanisms such as redirection and caching are assumed. 335 When specifying examples of protocol interactions, applications 336 SHOULD document both the request and response messages, with full 337 headers, preferably in HTTP/1.1 format. For example: 339 GET /thing HTTP/1.1 340 Host: example.com 341 Accept: application/things+json 342 User-Agent: Foo/1.0 344 HTTP/1.1 200 OK 345 Content-Type: application/things+json 346 Content-Length: 500 347 Server: Bar/2.2 349 [payload here] 351 4.2. Defining HTTP Resources 353 HTTP Applications SHOULD focus on defining the following application- 354 specific protocol elements: 356 o Media types [RFC6838], often based upon a format convention such 357 as JSON [RFC7159], 359 o HTTP header fields, as per Section 4.7, and 361 o The behaviour of resources, as identified by link relations 362 [RFC5988]. 364 By composing these protocol elements, an application can define a set 365 of resources, identified by link relations, that implement specified 366 behaviours, including: 368 o Retrieval of their state using GET, in one or more formats 369 identified by media type; 371 o Resource creation or update using POST or PUT, with an 372 appropriately identified request body format; 374 o Data processing using POST and identified request and response 375 body format(s); and 377 o Resource deletion using DELETE. 379 For example, an application might specify: 381 Resources linked to with the "example-widget" link relation type are 382 Widgets. The state of a Widget can be fetched in the 383 "application/example-widget+json" format, and can be updated by PUT 384 to the same link. Widget resources can be deleted. 386 The "Example-Count" response header field on Widget representations 387 indicates how many Widgets are held by the sender. 389 The "application/example-widget+json" format is a JSON {{RFC7159}} 390 format representing the state of a Widget. It contains links to 391 related information in the link indicated by the Link header field 392 value with the "example-other-info" link relation type. 394 4.3. Specifying Client Behaviours 396 HTTP does not mandate some behaviours that have nevertheless become 397 very common; if these are not explicitly specified by applications 398 using HTTP, there may be confusing or interoperability problems. 399 This section lists common examples of this, and recommends default 400 handling for them. 402 o Redirect handling - applications using HTTP SHOULD specify that 403 3xx redirect status codes be followed automatically. See 404 [RFC7231], Section 6.4. 406 o Redirect methods - applications using HTTP SHOULD specify that 301 407 and 302 redirect status codes rewrite the POST method to GET. See 408 [RFC7231], Section 6.4. 410 o Cookies - Applications using HTTP MUST explicitly reference the 411 Cookie specification [RFC6265] if they are required. 413 o Certificates - Applications using HTTP MUST specify that TLS 414 certificates are to be checked according to [RFC2818] when HTTPS 415 is used. 417 In general, applications using HTTP SHOULD align their usage as 418 closely as possible with Web browsers, to avoid interoperability 419 issues when they are used. See Section 4.10. 421 Applications using HTTP MUST NOT require HTTP features that are 422 usually negotiated to be supported. For example, requiring that 423 clients support responses with a certain content-encoding ([RFC7231], 424 Section 3.1.2.2) instead of negotiating for it ([RFC7231], 425 Section 5.3.4) means that otherwise conformant clients cannot 426 interoperate with the application. Applications MAY encourage the 427 implementation of such features, though. 429 4.4. HTTP URLs 431 In HTTP, URLs are opaque identifiers under the control of the server. 432 As outlined in [RFC7320], standards cannot usurp this space, since it 433 might conflict with existing resources, and constrain implementation 434 and deployment. 436 In other words, applications that use HTTP MUST NOT associate 437 application semantics with specific URL paths on arbitrary servers. 438 Doing so inappropriately conflates the identity of the resource (its 439 URL) with the capabilities that resource supports, bringing about 440 many of the same interoperability problems that [RFC4367] warns of. 442 For example, specifying that a "GET to the URL /foo retrieves a bar 443 document" is bad practice. Likewise, specifying "The widget API is 444 at the path /bar" violates [RFC7320]. 446 Instead, applications that use HTTP are encouraged to ensure that 447 URLs are discovered at runtime, allowing HTTP-based services to 448 describe their own capabilities. One way to do this is to use typed 449 links [RFC5988] to convey the URIs that are in use, as well as the 450 semantics of the resources that they identify. See Section 4.2 for 451 details. 453 4.4.1. Initial URL Discovery 455 Generally, a client will begin interacting with a given application 456 server by requesting an initial document that contains information 457 about that particular deployment, potentially including links to 458 other relevant resources. 460 Applications that use HTTP SHOULD allow an arbitrary URL to be used 461 as that entry point. For example, rather than specifying "the 462 initial document is at "/foo/v1", they should allow a deployment to 463 use any URL as the entry point for the application. 465 In cases where doing so is impractical (e.g., it is not possible to 466 convey a whole URL, but only a hostname) standard applications that 467 use HTTP can request a well-known URL [RFC5785] as an entry point. 469 4.4.2. URL Schemes 471 Applications that use HTTP will typically use the "http" and/or 472 "https" URL schemes. "https" is preferred to provide authentication, 473 integrity and confidentiality, as well as mitigate pervasive 474 monitoring attacks [RFC7258]. 476 However, application-specific schemes can be defined as well. 478 When defining an URL scheme for an application using HTTP, there are 479 a number of tradeoffs and caveats to keep in mind: 481 o Unmodified Web browsers will not support the new scheme. While it 482 is possible to register new URL schemes with Web browsers (e.g. 483 registerProtocolHandler() in [HTML5] Section 8.7.1.3, as well as 484 several proprietary approaches), support for these mechanisms is 485 not shared by all browsers, and their capabilities vary. 487 o Existing non-browser clients, intermediaries, servers and 488 associated software will not recognise the new scheme. For 489 example, a client library might fail to dispatch the request; a 490 cache might refuse to store the response, and a proxy might fail 491 to forward the request. 493 o Because URLs occur in and are generated in HTTP artefacts 494 commonly, often without human intervention (e.g., in the 495 "Location" response header), it can be difficult to assure that 496 the new scheme is used consistently. 498 o The resources identified by the new scheme will still be available 499 using "http" and/or "https" URLs. Those URLs can "leak" into use, 500 which can present security and operability issues. For example, 501 using a new scheme to assure that requests don't get sent to a 502 "normal" Web site is likely to fail. 504 o Features that rely upon the URL's origin [RFC6454], such as the 505 Web's same-origin policy, will be impacted by a change of scheme. 507 o HTTP-specific features such as cookies [RFC6265], authentication 508 [RFC7235], caching [RFC7234], and CORS [FETCH] might or might not 509 work correctly, depending on how they are defined and implemented. 510 Generally, they are designed and implemented with an assumption 511 that the URL will always be "http" or "https". 513 o Web features that require a secure context 514 [W3C.CR-secure-contexts-20160915] will likely treat a new scheme 515 as insecure. 517 See [RFC7595] for more information about minting new URL schemes. 519 4.4.3. Transport Ports 521 Applications that use HTTP can use the applicable default port (80 522 for HTTP, 443 for HTTPS), or they can be deployed upon other ports. 523 This decision can be made at deployment time, or might be encouraged 524 by the application's specification (e.g., by registering a port for 525 that application). 527 In either case, non-default ports will need to be reflected in the 528 authority of all URLs for that resource; the only mechanism for 529 changing a default port is changing the scheme (see Section 4.4.2). 531 Using a port other than the default has privacy implications (i.e., 532 the protocol can now be distinguished from other traffic), as well as 533 operability concerns (as some networks might block or otherwise 534 interfere with it). Privacy implications SHOULD be documented in 535 Security Considerations. 537 See [RFC7605] for further guidance. 539 4.5. HTTP Methods 541 Applications that use HTTP MUST confine themselves to using 542 registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH. 544 New HTTP methods are rare; they are required to be registered with 545 IETF Review (see [RFC7232]), and are also required to be _generic_. 546 That means that they need to be potentially applicable to all 547 resources, not just those of one application. 549 While historically some applications (e.g., [RFC4791]) have defined 550 non-generic methods, [RFC7231] now forbids this. 552 When authors believe that a new method is required, they are 553 encouraged to engage with the HTTP community early, and document 554 their proposal as a separate HTTP extension, rather than as part of 555 an application's specification. 557 4.6. HTTP Status Codes 559 Applications that use HTTP MUST only use registered HTTP status 560 codes. 562 As with methods, new HTTP status codes are rare, and required (by 563 [RFC7231]) to be registered with IETF review. Similarly, HTTP status 564 codes are generic; they are required (by [RFC7231]) to be potentially 565 applicable to all resources, not just to those of one application. 567 When authors believe that a new status code is required, they are 568 encouraged to engage with the HTTP community early, and document 569 their proposal as a separate HTTP extension, rather than as part of 570 an application's specification. 572 The primary function of status codes is to convey HTTP semantics for 573 the benefit of generic HTTP software, not application-specific 574 semantics. Therefore, applications MUST NOT specify additional 575 semantics or refine existing semantics for status codes. 577 In particular, specifying that a particular status code has a 578 specific meaning in the context of an application is harmful, as 579 these are not generic semantics, since the consumer needs to be in 580 the context of the application to understand them. 582 Furthermore, applications using HTTP MUST NOT re-specify the 583 semantics of HTTP status codes, even if it is only by copying their 584 definition. They MUST NOT require specific reason phrases to be 585 used; the reason phrase has no function in HTTP, and is not 586 guaranteed to be preserved by implementations. The reason phrase is 587 not carried in the [RFC7540] message format. 589 Typically, applications using HTTP will convey application-specific 590 information in the message body and/or HTTP header fields, not the 591 status code. 593 Specifications sometimes also create a "laundry list" of potential 594 status codes, in an effort to be helpful. The problem with doing so 595 is that such a list is never complete; for example, if a network 596 proxy is interposed, the client might encounter a "407 Proxy 597 Authentication Required" response; or, if the server is rate limiting 598 the client, it might receive a "429 Too Many Requests" response. 600 Since the list of HTTP status codes can be added to, it's safer to 601 refer to it directly, and point out that clients SHOULD be able to 602 handle all applicable protocol elements gracefully (i.e., falling 603 back to the generic "n00" semantics of a given status code; e.g., 604 "499" can be safely handled as "400" by clients that don't recognise 605 it). 607 4.7. HTTP Header Fields 609 Applications that use HTTP MAY define new HTTP header fields, 610 following the advice in [RFC7231], Section 8.3.1. 612 Typically, using HTTP header fields is appropriate in a few different 613 situations: 615 o Their content is useful to intermediaries (who often wish to avoid 616 parsing the body), and/or 618 o Their content is useful to generic HTTP software (e.g., clients, 619 servers), and/or 621 o It is not possible to include their content in the message body 622 (usually because a format does not allow it). 624 If none of these motivations apply, using a header field is NOT 625 RECOMMENDED. 627 New header fields MUST be registered, as per [RFC7231] and [RFC3864]. 629 It is RECOMMENDED that header field names be short (even when HTTP/2 630 header compression is in effect, there is an overhead) but 631 appropriately specific. In particular, if a header field is specific 632 to an application, an identifier for that application SHOULD form a 633 prefix to the header field name, separated by a "-". 635 For example, if the "example" application needs to create three 636 headers, they might be called "example-foo", "example-bar" and 637 "example-baz". Note that the primary motivation here is to avoid 638 consuming more generic header names, not to reserve a portion of the 639 namespace for the application; see [RFC6648] for related 640 considerations. 642 The semantics of existing HTTP header fields MUST NOT be re-defined 643 without updating their registration or defining an extension to them 644 (if allowed). For example, an application using HTTP cannot specify 645 that the "Location" header has a special meaning in a certain 646 context. 648 If an application defines a request header field that might be used 649 by a server to change the response's headers or body, authors should 650 point out that this has implications for caching; in general, such 651 resources need to either make their responses uncacheable (e.g., with 652 the "no-store" cache-control directive defined in [RFC7234], 653 Section 5.2.2.3) or consistently send the Vary response header 654 ([RFC7231], Section 7.1.4). 656 See Section 4.9 for requirements regarding header fields that carry 657 application state (e.g,. Cookie). 659 Applications that use already-defined HTTP header fields MUST NOT 660 modify their semantics or syntax, unless the definition of that 661 header field explicitly allows it (e.g., with an extension field). 663 4.8. Defining Message Payloads 665 There are many potential formats for payloads; for example, JSON 666 [RFC8259], XML [W3C.REC-xml-20081126], and CBOR [RFC7049]. Best 667 practices for their use are out of scope for this document. 669 Applications SHOULD register distinct media types for each format 670 they define; this makes it possible to identify them unambiguously 671 and negotiate for their use. See [RFC6838] for more information. 673 4.9. Authentication and Application State 675 Applications that use HTTP MAY use stateful cookies [RFC6265] to 676 identify a client and/or store client-specific data to contextualise 677 requests. 679 If it is only necessary to identify clients, applications that use 680 HTTP MAY use HTTP authentication [RFC7235]. If the Basic 681 authentication scheme [RFC7617] is used, it MUST NOT be used with the 682 'http' URL scheme. If the Digest scheme [RFC7616] is used, it MUST 683 NOT be used with the 'http' URL scheme, unless the chosen hash 684 algorithm is not "MD5". 686 In either case, it is important to carefully specify the scoping and 687 use of these mechanisms; if they expose sensitive data or 688 capabilities (e.g., by acting as an ambient authority), exploits are 689 possible. Mitigations include using a request-specific token to 690 assure the intent of the client. 692 Applications MUST NOT make assumptions about the relationship between 693 separate requests on a single transport connection; doing so breaks 694 many of the assumptions of HTTP as a stateless protocol, and will 695 cause problems in interoperability, security, operability and 696 evolution. 698 4.10. Co-Existing with Web Browsing 700 Even if there is not an intent for an application that uses HTTP to 701 be used with a Web browser, its resources will remain available to 702 browsers and other HTTP clients. 704 This means that all such applications need to consider how browsers 705 will interact with them, particularly regarding security. 707 For example, if an application's state can be changed using a POST 708 request, a Web browser can easily be coaxed into making that request 709 by a HTML form on an arbitrary Web site. 711 Or, if a resource reflects data from the request into a response, 712 that can be used to perform a Cross-Site Scripting attack on Web 713 browsers directed to it. 715 This is only a small sample of the kinds of issues that applications 716 using HTTP must consider. Generally, the best approach is to 717 consider the application _as_ a Web application, and to follow best 718 practices for their secure development. 720 A complete enumeration of such practices is out of scope for this 721 document. External resources are numerous; e.g., 722 https://www.owasp.org/index.php/OWASP_Guide_Project [4]. 724 4.11. Co-Existing with Other Applications 726 Because the origin [RFC6454] is how many HTTP capabilities are 727 scoped, applications also need to consider how deployments might 728 interact with other applications (including Web browsing) on the same 729 origin. 731 For example, if Cookies [RFC6265] are used to carry application 732 state, they will be sent with all requests to the origin by default, 733 unless scoped by path, and the application might receive cookies from 734 other applications on the origin. This can lead to security issues, 735 as well as collisions in cookie name. 737 As a result, when specifying the use of Cookies, HTTP authentication 738 [RFC7235], or other origin-wide HTTP mechanisms, applications using 739 HTTP SHOULD NOT mandate the use of a particular identifier, but 740 instead let deployments configure them. 742 Note that dedicating a hostname to a single application is not a 743 solution to the issues above; see [RFC7320]. 745 Modern Web browsers constrain the ability of content from one origin 746 to access resources from another, to avoid the "confused deputy" 747 problem. As a result, applications that wish to expose cross-origin 748 data to browsers will need to implement [W3C.REC-cors-20140116]. 750 5. IANA Considerations 752 This document has no requirements for IANA. 754 6. Security Considerations 756 Section 4.9 discusses the impact of using stateful mechanisms in the 757 protocol as ambient authority, and suggests a mitigation. 759 Section 4.4.2 requires support for 'https' URLs, and discourages the 760 use of 'http' URLs, to provide authentication, integrity and 761 confidentiality, as well as mitigate pervasive monitoring attacks. 763 Section 4.10 highlights the implications of Web browsers' 764 capabilities on applications that use HTTP. 766 Section 4.11 discusses the issues that arise when applications are 767 deployed on the same origin as Web sites (and other applications). 769 Applications that use HTTP in a manner that involves modification of 770 implementations - for example, requiring support for a new URL 771 scheme, or a non-standard method - risk having those implementations 772 "fork" from their parent HTTP implementations, with the possible 773 result that they do not benefit from patches and other security 774 improvements incorporated upstream. 776 7. References 778 7.1. Normative References 780 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 781 Requirement Levels", BCP 14, RFC 2119, 782 DOI 10.17487/RFC2119, March 1997, 783 . 785 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 786 DOI 10.17487/RFC2818, May 2000, 787 . 789 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 790 Procedures for Message Header Fields", BCP 90, RFC 3864, 791 DOI 10.17487/RFC3864, September 2004, 792 . 794 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 795 DOI 10.17487/RFC5988, October 2010, 796 . 798 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 799 DOI 10.17487/RFC6454, December 2011, 800 . 802 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 803 "Deprecating the "X-" Prefix and Similar Constructs in 804 Application Protocols", BCP 178, RFC 6648, 805 DOI 10.17487/RFC6648, June 2012, 806 . 808 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 809 Specifications and Registration Procedures", BCP 13, 810 RFC 6838, DOI 10.17487/RFC6838, January 2013, 811 . 813 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 814 Protocol (HTTP/1.1): Message Syntax and Routing", 815 RFC 7230, DOI 10.17487/RFC7230, June 2014, 816 . 818 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 819 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 820 DOI 10.17487/RFC7231, June 2014, 821 . 823 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 824 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 825 DOI 10.17487/RFC7232, June 2014, 826 . 828 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 829 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 830 RFC 7233, DOI 10.17487/RFC7233, June 2014, 831 . 833 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 834 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 835 RFC 7234, DOI 10.17487/RFC7234, June 2014, 836 . 838 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 839 Protocol (HTTP/1.1): Authentication", RFC 7235, 840 DOI 10.17487/RFC7235, June 2014, 841 . 843 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 844 "Transport Layer Security (TLS) Application-Layer Protocol 845 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 846 July 2014, . 848 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 849 RFC 7320, DOI 10.17487/RFC7320, July 2014, 850 . 852 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 853 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 854 DOI 10.17487/RFC7540, May 2015, 855 . 857 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 858 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 859 May 2017, . 861 [W3C.REC-cors-20140116] 862 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 863 Web Consortium Recommendation REC-cors-20140116, January 864 2014, . 866 7.2. Informative References 868 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 869 . 871 [HTML5] WHATWG, "HTML - Living Standard", n.d., 872 . 874 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 875 RFC 793, DOI 10.17487/RFC0793, September 1981, 876 . 878 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 879 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, May 880 1983, . 882 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 883 STD 9, RFC 959, DOI 10.17487/RFC0959, October 1985, 884 . 886 [RFC2821] Klensin, J., Ed., "Simple Mail Transfer Protocol", 887 RFC 2821, DOI 10.17487/RFC2821, April 2001, 888 . 890 [RFC4367] Rosenberg, J., Ed. and IAB, "What's in a Name: False 891 Assumptions about DNS Names", RFC 4367, 892 DOI 10.17487/RFC4367, February 2006, 893 . 895 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 896 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 897 DOI 10.17487/RFC4791, March 2007, 898 . 900 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 901 Uniform Resource Identifiers (URIs)", RFC 5785, 902 DOI 10.17487/RFC5785, April 2010, 903 . 905 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 906 DOI 10.17487/RFC6265, April 2011, 907 . 909 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 910 RFC 6455, DOI 10.17487/RFC6455, December 2011, 911 . 913 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 914 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 915 October 2013, . 917 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 918 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 919 2014, . 921 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 922 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 923 2014, . 925 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 926 and Registration Procedures for URI Schemes", BCP 35, 927 RFC 7595, DOI 10.17487/RFC7595, June 2015, 928 . 930 [RFC7605] Touch, J., "Recommendations on Using Assigned Transport 931 Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605, 932 August 2015, . 934 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 935 Digest Access Authentication", RFC 7616, 936 DOI 10.17487/RFC7616, September 2015, 937 . 939 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 940 RFC 7617, DOI 10.17487/RFC7617, September 2015, 941 . 943 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 944 Interchange Format", STD 90, RFC 8259, 945 DOI 10.17487/RFC8259, December 2017, 946 . 948 [W3C.CR-secure-contexts-20160915] 949 West, M., "Secure Contexts", World Wide Web Consortium CR 950 CR-secure-contexts-20160915, September 2016, 951 . 953 [W3C.REC-xml-20081126] 954 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 955 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 956 Edition)", World Wide Web Consortium Recommendation REC- 957 xml-20081126, November 2008, 958 . 960 7.3. URIs 962 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 964 [2] http://httpwg.github.io/ 966 [3] https://github.com/httpwg/http-extensions/labels/bcp56bis 968 [4] https://www.owasp.org/index.php/OWASP_Guide_Project 970 Appendix A. Changes from RFC3205 972 RFC3205 captured the Best Current Practice in the early 2000's, based 973 on the concerns facing protocol designers at the time. Use of HTTP 974 has changed considerably since then, and as a result this document is 975 substantially different. As a result, the changes are too numerous 976 to list individually. 978 Author's Address 980 Mark Nottingham 982 Email: mnot@mnot.net 983 URI: https://www.mnot.net/