idnits 2.17.1 draft-ietf-httpbis-bcp56bis-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. -- 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 12, 2018) is 2265 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 904 -- Looks like a reference, but probably isn't: '2' on line 906 -- Looks like a reference, but probably isn't: '3' on line 908 -- Looks like a reference, but probably isn't: '4' on line 910 ** 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 7159 (Obsoleted by RFC 8259) Summary: 10 errors (**), 0 flaws (~~), 1 warning (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft February 12, 2018 4 Obsoletes: 3205 (if approved) 5 Intended status: Best Current Practice 6 Expires: August 16, 2018 8 On the use of HTTP as a Substrate 9 draft-ietf-httpbis-bcp56bis-01 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 August 16, 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. HTTP URLs . . . . . . . . . . . . . . . . . . . . . . . . 9 72 4.3.1. Initial URL Discovery . . . . . . . . . . . . . . . . 9 73 4.3.2. URL Schemes . . . . . . . . . . . . . . . . . . . . . 10 74 4.3.3. Transport Ports . . . . . . . . . . . . . . . . . . . 11 75 4.4. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 11 76 4.5. HTTP Status Codes . . . . . . . . . . . . . . . . . . . . 12 77 4.6. HTTP Header Fields . . . . . . . . . . . . . . . . . . . 13 78 4.7. Defining Message Payloads . . . . . . . . . . . . . . . . 14 79 4.8. Authentication and Application State . . . . . . . . . . 14 80 4.9. Co-Existing with Web Browsing . . . . . . . . . . . . . . 14 81 4.10. Co-Existing with Other Applications . . . . . . . . . . . 15 82 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 85 7.1. Normative References . . . . . . . . . . . . . . . . . . 16 86 7.2. Informative References . . . . . . . . . . . . . . . . . 18 87 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 20 88 Appendix A. Changes from RFC3205 . . . . . . . . . . . . . . . . 20 89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 91 1. Introduction 93 HTTP [RFC7230] is often used as a substrate for other application 94 protocols. This is done for a variety of reasons, including: 96 o familiarity by implementers, specifiers, administrators, 97 developers and users, 99 o availability of a variety of client, server and proxy 100 implementations, 102 o ease of use, 104 o ubiquity of Web browsers, 106 o reuse of existing mechanisms like authentication and encryption, 108 o presence of HTTP servers and clients in target deployments, and 110 o its ability to traverse firewalls. 112 The Internet community has a long tradition of protocol reuse, dating 113 back to the use of Telnet [RFC0854] as a substrate for FTP [RFC0959] 114 and SMTP [RFC2821]. However, layering new protocols over HTTP brings 115 its own set of issues: 117 o Should an application using HTTP define a new URL scheme? Use new 118 ports? 120 o Should it use standard HTTP methods and status codes, or define 121 new ones? 123 o How can the maximum value be extracted from the use of HTTP? 125 o How does it coexist with other uses of HTTP - especially Web 126 browsing? 128 o How can interoperability problems and "protocol dead ends" be 129 avoided? 131 This document contains best current practices regarding the use of 132 HTTP by applications other than Web browsing. Section 2 defines what 133 applications it applies to; Section 3 surveys the properties of HTTP 134 that are important to preserve, and Section 4 conveys best practices 135 for those applications that do use HTTP. 137 It is written primarily to guide IETF efforts to define application 138 protocols using HTTP for deployment on the Internet, but might be 139 applicable in other situations. Note that the requirements herein do 140 not necessarily apply to the development of generic HTTP extensions. 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 2. Is HTTP Being Used? 152 Different applications have different goals when using HTTP. In this 153 document, we say an application is _using HTTP_ when any of the 154 following conditions are true: 156 o The transport port in use is 80 or 443, 158 o The URL scheme "http" or "https" is used, 160 o The ALPN protocol ID [RFC7301] generically identifies HTTP (e.g., 161 "http/1.1", "h2", "h2c"), or 163 o The message formats described in [RFC7230] and/or [RFC7540] are 164 used in conjunction with the IANA registries defined for HTTP. 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: 277 o Caching for server scalability, latency and bandwidth reduction, 278 and reliability; 280 o Authentication and access control; 282 o Automatic redirection; 284 o Partial content to selectively request part of a response; 285 o Natural support for extensions and versioning through protocol 286 extension; and 288 o The ability to interact with the application easily using a Web 289 browser. 291 Using such a high-level protocol to tunnel simple semantics has 292 downsides too; because of its more advanced capabilities, breadth of 293 deployment and age, HTTP's complexity can cause interoperability 294 problems that could be avoided by using a simpler substrate (e.g., 295 WebSockets [RFC6455], if browser support is necessary, or TCP 296 [RFC0793] if not), or making the application be _based upon HTTP_, 297 instead of using it (as defined in Section 2). 299 Applications that use HTTP are encouraged to accommodate the various 300 features that the protocol offers, so that their users receive the 301 maximum benefit from it. This document does not require specific 302 features to be used, since the appropriate design tradeoffs are 303 highly specific to a given situation. However, following the 304 practices in Section 4 will help make them available. 306 4. Best Practices for Using HTTP 308 This section contains best practices regarding the use of HTTP by 309 applications, including practices for specific HTTP protocol 310 elements. 312 4.1. Specifying the Use of HTTP 314 When specifying the use of HTTP, an application SHOULD use [RFC7230] 315 as the primary reference; it is not necessary to reference all of the 316 specifications in the HTTP suite unless there are specific reasons to 317 do so (e.g., a particular feature is called out). 319 Applications using HTTP MAY specify a minimum version to be supported 320 (HTTP/1.1 is suggested), and MUST NOT specify a maximum version. 322 Likewise, applications need not specify what HTTP mechanisms - such 323 as redirection, caching, authentication, proxy authentication, and so 324 on - are to be supported. Full featured support for HTTP SHOULD be 325 taken for granted in servers and clients, and the application's 326 function SHOULD degrade gracefully if they are not (although this 327 might be achieved by informing the user that their task cannot be 328 completed). 330 For example, an application can specify that it uses HTTP like this: 332 Foo Application uses HTTP {{RFC7230}}. Implementations MUST support 333 HTTP/1.1, and MAY support later versions. Support for common HTTP 334 mechanisms such as redirection and caching are assumed. 336 When specifying examples of protocol interactions, applications 337 SHOULD document both the request and response messages, with full 338 headers, preferably in HTTP/1.1 format. For example: 340 GET /thing HTTP/1.1 341 Host: example.com 342 Accept: application/things+json 343 User-Agent: Foo/1.0 345 HTTP/1.1 200 OK 346 Content-Type: application/things+json 347 Content-Length: 500 348 Server: Bar/2.2 350 [payload here] 352 4.2. Defining HTTP Resources 354 HTTP Applications SHOULD focus on defining the following application- 355 specific protocol elements: 357 o Media types [RFC6838], often based upon a format convention such 358 as JSON [RFC7159], 360 o HTTP header fields, as per Section 4.6, and 362 o The behaviour of resources, as identified by link relations 363 [RFC5988]. 365 By composing these protocol elements, an application can define a set 366 of resources, identified by link relations, that implement specified 367 behaviours, including: 369 o Retrieval of their state using GET, in one or more formats 370 identified by media type; 372 o Resource creation or update using POST or PUT, with an 373 appropriately identified request body format; 375 o Data processing using POST and identified request and response 376 body format(s); and 378 o Resource deletion using DELETE. 380 For example, an application might specify: 382 Resources linked to with the "example-widget" link relation type are 383 Widgets. The state of a Widget can be fetched in the 384 "application/example-widget+json" format, and can be updated by PUT 385 to the same link. Widget resources can be deleted. 387 The "Example-Count" response header field on Widget representations 388 indicates how many Widgets are held by the sender. 390 The "application/example-widget+json" format is a JSON {{RFC7159}} 391 format representing the state of a Widget. It contains links to 392 related information in the link indicated by the Link header field 393 value with the "example-other-info" link relation type. 395 4.3. HTTP URLs 397 In HTTP, URLs are opaque identifiers under the control of the server. 398 As outlined in [RFC7320], standards cannot usurp this space, since it 399 might conflict with existing resources, and constrain implementation 400 and deployment. 402 In other words, applications that use HTTP MUST NOT associate 403 application semantics with specific URL paths on arbitrary servers. 404 Doing so inappropriately conflates the identity of the resource (its 405 URL) with the capabilities that resource supports, bringing about 406 many of the same interoperability problems that [RFC4367] warns of. 408 For example, specifying that a "GET to the URL /foo retrieves a bar 409 document" is bad practice. Likewise, specifying "The widget API is 410 at the path /bar" violates [RFC7320]. 412 Instead, applications that use HTTP are encouraged to ensure that 413 URLs are discovered at runtime, allowing HTTP-based services to 414 describe their own capabilities. One way to do this is to use typed 415 links [RFC5988] to convey the URIs that are in use, as well as the 416 semantics of the resources that they identify. See Section 4.2 for 417 details. 419 4.3.1. Initial URL Discovery 421 Generally, a client will begin interacting with a given application 422 server by requesting an initial document that contains information 423 about that particular deployment, potentially including links to 424 other relevant resources. 426 Applications that use HTTP SHOULD allow an arbitrary URL to be used 427 as that entry point. For example, rather than specifying "the 428 initial document is at "/foo/v1", they should allow a deployment to 429 use any URL as the entry point for the application. 431 In cases where doing so is impractical (e.g., it is not possible to 432 convey a whole URL, but only a hostname) standard applications that 433 use HTTP can request a well-known URL [RFC5785] as an entry point. 435 4.3.2. URL Schemes 437 Applications that use HTTP will typically use the "http" and/or 438 "https" URL schemes. "https" is preferred to provide authentication, 439 integrity and confidentiality, as well as mitigate pervasive 440 monitoring attacks [RFC7258]. 442 However, application-specific schemes can be defined as well. 444 When defining an URL scheme for an application using HTTP, there are 445 a number of tradeoffs and caveats to keep in mind: 447 o Unmodified Web browsers will not support the new scheme. While it 448 is possible to register new URL schemes with Web browsers (e.g. 449 registerProtocolHandler() in [HTML5] Section 8.7.1.3, as well as 450 several proprietary approaches), support for these mechanisms is 451 not shared by all browsers, and their capabilities vary. 453 o Existing non-browser clients, intermediaries, servers and 454 associated software will not recognise the new scheme. For 455 example, a client library might fail to dispatch the request; a 456 cache might refuse to store the response, and a proxy might fail 457 to forward the request. 459 o Because URLs occur in and are generated in HTTP artefacts 460 commonly, often without human intervention (e.g., in the 461 "Location" response header), it can be difficult to assure that 462 the new scheme is used consistently. 464 o The resources identified by the new scheme will still be available 465 using "http" and/or "https" URLs. Those URLs can "leak" into use, 466 which can present security and operability issues. For example, 467 using a new scheme to assure that requests don't get sent to a 468 "normal" Web site is likely to fail. 470 o Features that rely upon the URL's origin [RFC6454], such as the 471 Web's same-origin policy, will be impacted by a change of scheme. 473 o HTTP-specific features such as cookies [RFC6265], authentication 474 [RFC7235], caching [RFC7234], and CORS [FETCH] might or might not 475 work correctly, depending on how they are defined and implemented. 477 Generally, they are designed and implemented with an assumption 478 that the URL will always be "http" or "https". 480 o Web features that require a secure context 481 [W3C.CR-secure-contexts-20160915] will likely treat a new scheme 482 as insecure. 484 See [RFC7595] for more information about minting new URL schemes. 486 4.3.3. Transport Ports 488 Applications that use HTTP can use the applicable default port (80 489 for HTTP, 443 for HTTPS), or they can be deployed upon other ports. 490 This decision can be made at deployment time, or might be encouraged 491 by the application's specification (e.g., by registering a port for 492 that application). 494 In either case, non-default ports will need to be reflected in the 495 authority of all URLs for that resource; the only mechanism for 496 changing a default port is changing the scheme (see Section 4.3.2). 498 Using a port other than the default has privacy implications (i.e., 499 the protocol can now be distinguished from other traffic), as well as 500 operability concerns (as some networks might block or otherwise 501 interfere with it). Privacy implications SHOULD be documented in 502 Security Considerations. 504 See [RFC7605] for further guidance. 506 4.4. HTTP Methods 508 Applications that use HTTP MUST confine themselves to using 509 registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH. 511 New HTTP methods are rare; they are required to be registered with 512 IETF Review (see [RFC7232]), and are also required to be _generic_. 513 That means that they need to be potentially applicable to all 514 resources, not just those of one application. 516 While historically some applications (e.g., [RFC4791]) has defined 517 non-generic methods, [RFC7231] now forbids this. 519 When it is believed that a new method is required, authors are 520 encouraged to engage with the HTTP community early, and document 521 their proposal as a separate HTTP extension, rather than as part of 522 an application's specification. 524 4.5. HTTP Status Codes 526 Applications that use HTTP MUST only use registered HTTP status 527 codes. 529 As with methods, new HTTP status codes are rare, and required (by 530 [RFC7231]) to be registered with IETF review. Similarly, HTTP status 531 codes are generic; they are required (by [RFC7231]) to be potentially 532 applicable to all resources, not just to those of one application. 534 When it is believed that a new status code is required, authors are 535 encouraged to engage with the HTTP community early, and document 536 their proposal as a separate HTTP extension, rather than as part of 537 an application's specification. 539 Status codes' primary function is to convey HTTP semantics for the 540 benefit of generic HTTP software, not application-specific semantics. 541 Therefore, applications MUST NOT specify additional semantics or 542 refine existing semantics for status codes. 544 In particular, specifying that a particular status code has a 545 specific meaning in the context of an application is harmful, as 546 these are not generic semantics, since the consumer needs to be in 547 the context of the application to understand them. 549 Furthermore, applications using HTTP MUST NOT re-specify the 550 semantics of HTTP status codes, even if it is only by copying their 551 definition. They MUST NOT require specific reason phrases to be 552 used; the reason phrase has no function in HTTP, and is not 553 guaranteed to be preserved by implementations. The reason phrase is 554 not carried in the [RFC7540] message format. 556 Typically, applications using HTTP will convey application-specific 557 information in the message body and/or HTTP header fields, not the 558 status code. 560 Specifications sometimes also create a "laundry list" of potential 561 status codes, in an effort to be helpful. The problem with doing so 562 is that such a list is never complete; for example, if a network 563 proxy is interposed, the client might encounter a "407 Proxy 564 Authentication Required" response; or, if the server is rate limiting 565 the client, it might receive a "429 Too Many Requests" response. 567 Since the list of HTTP status codes can be added to, it's safer to 568 refer to it directly, and point out that clients SHOULD be able to 569 handle all applicable protocol elements gracefully (i.e., falling 570 back to the generic "n00" semantics of a given status code; e.g., 571 "499" can be safely handled as "400" by clients that don't recognise 572 it). 574 4.6. HTTP Header Fields 576 Applications that use HTTP MAY define new HTTP header fields, 577 following the advice in [RFC7231], Section 8.3.1. 579 Typically, using HTTP header fields is appropriate in a few different 580 situations: 582 o Their content is useful to intermediaries (who often wish to avoid 583 parsing the body), and/or 585 o Their content is useful to generic HTTP software (e.g., clients, 586 servers), and/or 588 o It is not possible to include their content in the message body 589 (usually because a format does not allow it). 591 If none of these motivations apply, using a header field is NOT 592 RECOMMENDED. 594 New header fields MUST be registered, as per [RFC7231] and [RFC3864]. 596 It is RECOMMENDED that header field names be short (even when HTTP/2 597 header compression is in effect, there is an overhead) but 598 appropriately specific. In particular, if a header field is specific 599 to an application, an identifier for that application SHOULD form a 600 prefix to the header field name, separated by a "-". 602 For example, if the "example" application needs to create three 603 headers, they might be called "example-foo", "example-bar" and 604 "example-baz". Note that the primary motivation here is to avoid 605 consuming more generic header names, not to reserve a portion of the 606 namespace for the application; see [RFC6648] for related 607 considerations. 609 The semantics of existing HTTP header fields MUST NOT be re-defined 610 without updating their registration or defining an extension to them 611 (if allowed). For example, an application using HTTP cannot specify 612 that the "Location" header has a special meaning in a certain 613 context. 615 See Section 4.8 for requirements regarding header fields that carry 616 application state (e.g,. Cookie). 618 4.7. Defining Message Payloads 620 There are many potential formats for payloads; for example, JSON 621 [RFC8259] and XML [W3C.REC-xml-20081126]. Best practices for their 622 use are out of scope for this document. 624 Applications SHOULD register distinct media types for each format 625 they define; this makes it possible to identify them unambiguously 626 and negotiate for their use. See [RFC6838] for more information. 628 4.8. Authentication and Application State 630 Applications that use HTTP MAY use stateful cookies [RFC6265] to 631 identify a client and/or store client-specific data to contextualise 632 requests. 634 If it is only necessary to identify clients, applications that use 635 HTTP MAY use HTTP authentication [RFC7235]; if either of the Basic 636 [RFC7617] or Digest [RFC7616] authentication schemes is used, it MUST 637 NOT be used with the 'http' URL scheme. 639 In either case, it is important to carefully specify the scoping and 640 use of these mechanisms; if they expose sensitive data or 641 capabilities (e.g., by acting as an ambient authority), exploits are 642 possible. Mitigations include using a request-specific token to 643 assure the intent of the client. 645 Applications MUST NOT make assumptions about the relationship between 646 separate requests on a single transport connection; doing so breaks 647 many of the assumptions of HTTP as a stateless protocol, and will 648 cause problems in interoperability, security, operability and 649 evolution. 651 4.9. Co-Existing with Web Browsing 653 Even if there is not an intent for an application that uses HTTP to 654 be used with a Web browser, its resources will remain available to 655 browsers and other HTTP clients. 657 This means that all such applications need to consider how browsers 658 will interact with them, particularly regarding security. 660 For example, if an application's state can be changed using a POST 661 request, a Web browser can easily be coaxed into making that request 662 by a HTML form on an arbitrary Web site. 664 Or, if a resource reflects data from the request into a response, 665 that can be used to perform a Cross-Site Scripting attack on Web 666 browsers directed to it. 668 This is only a small sample of the kinds of issues that applications 669 using HTTP must consider. Generally, the best approach is to 670 consider the application _as_ a Web application, and to follow best 671 practices for their secure development. 673 A complete enumeration of such practices is out of scope for this 674 document. External resources are numerous; e.g., 675 https://www.owasp.org/index.php/OWASP_Guide_Project [4]. 677 4.10. Co-Existing with Other Applications 679 Because the origin [RFC6454] is how many HTTP capabilities are 680 scoped, applications also need to consider how deployments might 681 interact with other applications (including Web browsing) on the same 682 origin. 684 For example, if Cookies [RFC6265] are used to carry application 685 state, they will be sent with all requests to the origin by default, 686 unless scoped by path, and the application might receive cookies from 687 other applications on the origin. This can lead to security issues, 688 as well as collisions in cookie name. 690 As a result, when specifying the use of Cookies, HTTP authentication 691 [RFC7235], or other origin-wide HTTP mechanisms, applications using 692 HTTP SHOULD NOT mandate the use of a particular identifier, but 693 instead let deployments configure them. 695 Note that dedicating a hostname to a single application is not a 696 solution to the issues above; see [RFC7320]. 698 Modern Web browsers constrain the ability of content from one origin 699 to access resources from another, to avoid the "confused deputy" 700 problem. As a result, applications that wish to expose cross-origin 701 data to browsers will need to implement [W3C.REC-cors-20140116]. 703 5. IANA Considerations 705 This document has no requirements for IANA. 707 6. Security Considerations 709 Section 4.8 discusses the impact of using stateful mechanisms in the 710 protocol as ambient authority, and suggests a mitigation. 712 Section 4.3.2 requires support for 'https' URLs, and discourages the 713 use of 'http' URLs, to provide authentication, integrity and 714 confidentiality, as well as mitigate pervasive monitoring attacks. 716 Section 4.9 highlights the implications of Web browsers' capabilities 717 on applications that use HTTP. 719 Applications that use HTTP in a manner that involves modification of 720 implementations - for example, requiring support for a new URL 721 scheme, or a non-standard method - risk having those implementations 722 "fork" from their parent HTTP implementations, with the possible 723 result that they do not benefit from patches and other security 724 improvements incorporated upstream. 726 7. References 728 7.1. Normative References 730 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 731 Requirement Levels", BCP 14, RFC 2119, 732 DOI 10.17487/RFC2119, March 1997, 733 . 735 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 736 Procedures for Message Header Fields", BCP 90, RFC 3864, 737 DOI 10.17487/RFC3864, September 2004, 738 . 740 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 741 DOI 10.17487/RFC5988, October 2010, 742 . 744 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 745 DOI 10.17487/RFC6454, December 2011, 746 . 748 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 749 "Deprecating the "X-" Prefix and Similar Constructs in 750 Application Protocols", BCP 178, RFC 6648, 751 DOI 10.17487/RFC6648, June 2012, 752 . 754 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 755 Specifications and Registration Procedures", BCP 13, 756 RFC 6838, DOI 10.17487/RFC6838, January 2013, 757 . 759 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 760 Protocol (HTTP/1.1): Message Syntax and Routing", 761 RFC 7230, DOI 10.17487/RFC7230, June 2014, 762 . 764 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 765 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 766 DOI 10.17487/RFC7231, June 2014, 767 . 769 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 770 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 771 DOI 10.17487/RFC7232, June 2014, 772 . 774 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 775 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 776 RFC 7233, DOI 10.17487/RFC7233, June 2014, 777 . 779 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 780 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 781 RFC 7234, DOI 10.17487/RFC7234, June 2014, 782 . 784 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 785 Protocol (HTTP/1.1): Authentication", RFC 7235, 786 DOI 10.17487/RFC7235, June 2014, 787 . 789 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 790 "Transport Layer Security (TLS) Application-Layer Protocol 791 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 792 July 2014, . 794 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 795 RFC 7320, DOI 10.17487/RFC7320, July 2014, 796 . 798 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 799 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 800 DOI 10.17487/RFC7540, May 2015, 801 . 803 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 804 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 805 May 2017, . 807 [W3C.REC-cors-20140116] 808 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 809 Web Consortium Recommendation REC-cors-20140116, January 810 2014, . 812 7.2. Informative References 814 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 815 . 817 [HTML5] WHATWG, "HTML - Living Standard", n.d., 818 . 820 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 821 RFC 793, DOI 10.17487/RFC0793, September 1981, 822 . 824 [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol 825 Specification", STD 8, RFC 854, DOI 10.17487/RFC0854, May 826 1983, . 828 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 829 STD 9, RFC 959, DOI 10.17487/RFC0959, October 1985, 830 . 832 [RFC2821] Klensin, J., Ed., "Simple Mail Transfer Protocol", 833 RFC 2821, DOI 10.17487/RFC2821, April 2001, 834 . 836 [RFC4367] Rosenberg, J., Ed. and IAB, "What's in a Name: False 837 Assumptions about DNS Names", RFC 4367, 838 DOI 10.17487/RFC4367, February 2006, 839 . 841 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 842 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 843 DOI 10.17487/RFC4791, March 2007, 844 . 846 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 847 Uniform Resource Identifiers (URIs)", RFC 5785, 848 DOI 10.17487/RFC5785, April 2010, 849 . 851 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 852 DOI 10.17487/RFC6265, April 2011, 853 . 855 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 856 RFC 6455, DOI 10.17487/RFC6455, December 2011, 857 . 859 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 860 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 861 2014, . 863 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 864 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 865 2014, . 867 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 868 and Registration Procedures for URI Schemes", BCP 35, 869 RFC 7595, DOI 10.17487/RFC7595, June 2015, 870 . 872 [RFC7605] Touch, J., "Recommendations on Using Assigned Transport 873 Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605, 874 August 2015, . 876 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 877 Digest Access Authentication", RFC 7616, 878 DOI 10.17487/RFC7616, September 2015, 879 . 881 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 882 RFC 7617, DOI 10.17487/RFC7617, September 2015, 883 . 885 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 886 Interchange Format", STD 90, RFC 8259, 887 DOI 10.17487/RFC8259, December 2017, 888 . 890 [W3C.CR-secure-contexts-20160915] 891 West, M., "Secure Contexts", World Wide Web Consortium CR 892 CR-secure-contexts-20160915, September 2016, 893 . 895 [W3C.REC-xml-20081126] 896 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 897 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 898 Edition)", World Wide Web Consortium Recommendation REC- 899 xml-20081126, November 2008, 900 . 902 7.3. URIs 904 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 906 [2] http://httpwg.github.io/ 908 [3] https://github.com/httpwg/http-extensions/labels/bcp56bis 910 [4] https://www.owasp.org/index.php/OWASP_Guide_Project 912 Appendix A. Changes from RFC3205 914 RFC3205 captured the Best Current Practice in the early 2000's, based 915 on the concerns facing protocol designers at the time. Use of HTTP 916 has changed considerably since then, and as a result this document is 917 substantially different. As a result, the changes are too numerous 918 to list individually. 920 Author's Address 922 Mark Nottingham 924 Email: mnot@mnot.net 925 URI: https://www.mnot.net/