idnits 2.17.00 (12 Aug 2021) /tmp/idnits6106/draft-ietf-httpbis-bcp56bis-10.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 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 (7 March 2021) is 439 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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) == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-14 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-httpbis-semantics' == Outdated reference: A later version (-10) exists of draft-ietf-httpbis-rfc6265bis-07 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-14 == Outdated reference: draft-ietf-httpbis-header-structure has been published as RFC 8941 -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft 7 March 2021 4 Obsoletes: 3205 (if approved) 5 Intended status: Best Current Practice 6 Expires: 8 September 2021 8 Building Protocols with HTTP 9 draft-ietf-httpbis-bcp56bis-10 11 Abstract 13 HTTP is often used as a substrate for other application protocols to 14 create HTTP-based APIs. This document specifies best practices for 15 writing specifications that use HTTP to define new application 16 protocols, especially when they are defined for diverse 17 implementation and broad deployment (e.g., in standards efforts). 19 Note to Readers 21 _RFC EDITOR: please remove this section before publication_ 23 Discussion of this draft takes place on the HTTP working group 24 mailing list (ietf-http-wg@w3.org), which is archived at 25 https://lists.w3.org/Archives/Public/ietf-http-wg/ 26 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 28 Working Group information can be found at http://httpwg.github.io/ 29 (http://httpwg.github.io/); source code and issues list for this 30 draft can be found at https://github.com/httpwg/http- 31 extensions/labels/bcp56bis (https://github.com/httpwg/http- 32 extensions/labels/bcp56bis). 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on 8 September 2021. 50 Copyright Notice 52 Copyright (c) 2021 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 57 license-info) in effect on the date of publication of this document. 58 Please review these documents carefully, as they describe your rights 59 and restrictions with respect to this document. Code Components 60 extracted from this document must include Simplified BSD License text 61 as described in Section 4.e of the Trust Legal Provisions and are 62 provided without warranty as described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 68 2. Is HTTP Being Used? . . . . . . . . . . . . . . . . . . . . . 4 69 2.1. Non-HTTP Protocols . . . . . . . . . . . . . . . . . . . 5 70 3. What's Important About HTTP . . . . . . . . . . . . . . . . . 5 71 3.1. Generic Semantics . . . . . . . . . . . . . . . . . . . . 6 72 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6 73 3.3. Rich Functionality . . . . . . . . . . . . . . . . . . . 7 74 4. Best Practices for Specifying the Use of HTTP . . . . . . . . 8 75 4.1. Specifying the Use of HTTP . . . . . . . . . . . . . . . 8 76 4.2. Specifying Server Behaviour . . . . . . . . . . . . . . . 9 77 4.3. Specifying Client Behaviour . . . . . . . . . . . . . . . 10 78 4.4. Specifying URLs . . . . . . . . . . . . . . . . . . . . . 11 79 4.4.1. Discovering an Application's URLs . . . . . . . . . . 11 80 4.4.2. Considering URI Schemes . . . . . . . . . . . . . . . 12 81 4.4.3. Transport Ports . . . . . . . . . . . . . . . . . . . 13 82 4.5. Using HTTP Methods . . . . . . . . . . . . . . . . . . . 14 83 4.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 14 84 4.5.2. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 15 85 4.6. Using HTTP Status Codes . . . . . . . . . . . . . . . . . 16 86 4.6.1. Redirection . . . . . . . . . . . . . . . . . . . . . 17 87 4.7. Specifying HTTP Header Fields . . . . . . . . . . . . . . 18 88 4.8. Defining Message Payloads . . . . . . . . . . . . . . . . 19 89 4.9. Leveraging HTTP Caching . . . . . . . . . . . . . . . . . 20 90 4.9.1. Freshness . . . . . . . . . . . . . . . . . . . . . . 20 91 4.9.2. Stale Responses . . . . . . . . . . . . . . . . . . . 21 92 4.9.3. Caching and Application Semantics . . . . . . . . . . 21 93 4.9.4. Varying Content Based Upon the Request . . . . . . . 22 94 4.10. Handling Application State . . . . . . . . . . . . . . . 22 95 4.11. Client Authentication . . . . . . . . . . . . . . . . . . 23 96 4.12. Co-Existing with Web Browsing . . . . . . . . . . . . . . 23 97 4.13. Maintaining Application Boundaries . . . . . . . . . . . 25 98 4.14. Using Server Push . . . . . . . . . . . . . . . . . . . . 25 99 4.15. Allowing Versioning and Evolution . . . . . . . . . . . . 26 100 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 101 6. Security Considerations . . . . . . . . . . . . . . . . . . . 27 102 6.1. Privacy Considerations . . . . . . . . . . . . . . . . . 27 103 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 104 7.1. Normative References . . . . . . . . . . . . . . . . . . 28 105 7.2. Informative References . . . . . . . . . . . . . . . . . 29 106 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 32 108 1. Introduction 110 HTTP [I-D.ietf-httpbis-semantics] is often used as a substrate for 111 applications other than Web browsing; this is sometimes referred to 112 as creating "HTTP-based APIs", "REST APIs" or just "HTTP APIs". This 113 is done for a variety of reasons, including: 115 * familiarity by implementers, specifiers, administrators, 116 developers and users, 118 * availability of a variety of client, server and proxy 119 implementations, 121 * ease of use, 123 * availability of Web browsers, 125 * reuse of existing mechanisms like authentication and encryption, 127 * presence of HTTP servers and clients in target deployments, and 129 * its ability to traverse firewalls. 131 These protocols are often ad hoc; they are intended for only 132 deployment by one or a few servers, and consumption by a limited set 133 of clients. As a result, a body of practices and tools has arisen 134 around defining HTTP-based APIs that favours these conditions. 136 However, when such an application has multiple, separate 137 implementations, is deployed on multiple uncoordinated servers, and 138 is consumed by diverse clients -- as is often the case for HTTP APIs 139 defined by standards efforts -- tools and practices intended for 140 limited deployment can become unsuitable. 142 This is largely because implementations (both client and server) will 143 implement and evolve at different paces, and because deployments will 144 often have different features and versions available. As a result, 145 the designers of such an HTTP-based API will need to more carefully 146 consider how extensibility of the service will be handled and how 147 different deployment requirements will be accommodated. 149 More generally, an application protocol using HTTP faces a number of 150 design decisions, including: 152 * Should it define a new URI scheme? Use new ports? 154 * Should it use standard HTTP methods and status codes, or define 155 new ones? 157 * How can the maximum value be extracted from the use of HTTP? 159 * How does it coexist with other uses of HTTP -- especially Web 160 browsing? 162 * How can interoperability problems and "protocol dead ends" be 163 avoided? 165 This document contains best current practices for the specification 166 of such applications. Section 2 defines when it applies; Section 3 167 surveys the properties of HTTP that are important to preserve, and 168 Section 4 conveys best practices for the specifying them. 170 It is written primarily to guide IETF efforts to define application 171 protocols using HTTP for deployment on the Internet, but might be 172 applicable in other situations. Note that the requirements herein do 173 not necessarily apply to the development of generic HTTP extensions. 175 1.1. Notational Conventions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in BCP 180 14 [RFC2119] [RFC8174] when, and only when, they appear in all 181 capitals, as shown here. 183 2. Is HTTP Being Used? 185 Different applications have different goals when using HTTP. The 186 requirements in this document apply when a specification defines an 187 application that: 189 * uses the transport port 80 or 443, or 190 * uses the URI scheme "http" or "https", or 192 * uses an ALPN protocol ID [RFC7301] that generically identifies 193 HTTP (e.g., "http/1.1", "h2", "h2c"), or 195 * updates or modifies the IANA registries defined for HTTP. 197 Additionally, when a specification is using HTTP, all of the 198 requirements of the HTTP protocol suite are in force (in particular, 199 [I-D.ietf-httpbis-semantics], but also other specifications as 200 appropriate). 202 Note that this document is intended to apply to applications, not 203 generic extensions to HTTP, which follow the requirements in the 204 relevant specification. Furthermore, it is intended for applications 205 defined by IETF specifications, although other standards 206 organisations are encouraged to adhere to its requirements. 208 2.1. Non-HTTP Protocols 210 A specification might not use HTTP according to the criteria above 211 and still define an application that relies upon HTTP in some manner. 212 For example, an application might wish to avoid re-specifying parts 213 of the message format, but change other aspects of the protocol's 214 operation; or, it might want to use a different set of methods. 216 Doing so brings more freedom to modify protocol operations, but loses 217 at least a portion of the benefits outlined above, as most HTTP 218 implementations won't be easily adaptable to these changes, and as 219 the protocol diverges from HTTP, the benefit of mindshare will be 220 lost. 222 Such specifications MUST NOT use HTTP's URI schemes, transport ports, 223 ALPN protocol IDs or IANA registries; rather, they are encouraged to 224 establish their own. 226 3. What's Important About HTTP 228 This section examines the characteristics of the HTTP protocol that 229 are important to consider when using HTTP to define an application 230 protocol. 232 3.1. Generic Semantics 234 Much of the value of HTTP is in its generic semantics -- that is, the 235 protocol elements defined by HTTP are potentially applicable to every 236 resource, not specific to a particular context. Application-specific 237 semantics are best expressed in message content and in header fields, 238 not status codes or methods -- although the latter do have generic 239 semantics that relate to application state. 241 This generic/application-specific split allows a HTTP message to be 242 handled by software (e.g., HTTP servers, intermediaries, client 243 implementations, and caches) without understanding the specific 244 application. It also allows people to leverage their knowledge of 245 HTTP semantics without special-casing them for a particular 246 application. 248 Therefore, applications that use HTTP MUST NOT re-define, refine or 249 overlay the semantics of generic protocol elements such as methods, 250 status codes or existing header fields. Instead, they should focus 251 their specifications on protocol elements that are specific to that 252 application; namely their HTTP resources. 254 When writing a specification, it's often tempting to specify exactly 255 how HTTP is to be implemented, supported and used. However, this can 256 easily lead to an unintended profile of HTTP's behaviour. For 257 example, it's common to see specifications with language like this: 259 A `POST` request MUST result in a `201 Created` response. 261 This forms an expectation in the client that the response will always 262 be "201 Created", when in fact there are a number of reasons why the 263 status code might differ in a real deployment; for example, there 264 might be a proxy that requires authentication, or a server-side 265 error, or a redirection. If the client does not anticipate this, the 266 application's deployment is brittle. 268 See Section 4.2 for more details. 270 3.2. Links 272 Another common practice is assuming that the HTTP server's name space 273 (or a portion thereof) is exclusively for the use of a single 274 application. This effectively overlays special, application-specific 275 semantics onto that space, precludes other applications from using 276 it. 278 As explained in [RFC8820], such "squatting" on a part of the URL 279 space by a standard usurps the server's authority over its own 280 resources, can cause deployment issues, and is therefore bad practice 281 in standards. 283 Instead of statically defining URI components like paths, it is 284 RECOMMENDED that applications using HTTP define and use links, to 285 allow flexibility in deployment. 287 Using runtime links in this fashion has a number of other benefits -- 288 especially when an application is to have multiple implementations 289 and/or deployments (as is often the case for those that are 290 standardised). 292 For example, navigating with a link allows a request to be routed to 293 a different server without the overhead of a redirection, thereby 294 supporting deployment across machines well. 296 It also becomes possible to "mix and match" different applications on 297 the same server, and offers a natural mechanism for extensibility, 298 versioning and capability management, since the document containing 299 the links can also contain information about their targets. 301 Using links also offers a form of cache invalidation that's seen on 302 the Web; when a resource's state changes, the application can change 303 its link to it so that a fresh copy is always fetched. 305 3.3. Rich Functionality 307 HTTP offers a number of features to applications, such as: 309 * Message framing 311 * Multiplexing (in HTTP/2) 313 * Integration with TLS 315 * Support for intermediaries (proxies, gateways, Content Delivery 316 Networks) 318 * Client authentication 320 * Content negotiation for format, language, and other features 322 * Caching for server scalability, latency and bandwidth reduction, 323 and reliability 325 * Granularity of access control (through use of a rich space of 326 URLs) 328 * Partial content to selectively request part of a response 330 * The ability to interact with the application easily using a Web 331 browser 333 Applications that use HTTP are encouraged to utilise the various 334 features that the protocol offers, so that their users receive the 335 maximum benefit from it, and to allow it to be deployed in a variety 336 of situations. This document does not require specific features to 337 be used, since the appropriate design tradeoffs are highly specific 338 to a given situation. However, following the practices in Section 4 339 is a good starting point. 341 4. Best Practices for Specifying the Use of HTTP 343 This section contains best practices for specifying the use of HTTP 344 by applications, including practices for specific HTTP protocol 345 elements. 347 4.1. Specifying the Use of HTTP 349 When specifying the use of HTTP, an application should use 350 [I-D.ietf-httpbis-semantics] as the primary reference; it is not 351 necessary to reference all of the specifications in the HTTP suite 352 unless there are specific reasons to do so (e.g., a particular 353 feature is called out). 355 Because it is a hop-by-hop protocol, a HTTP connection can be handled 356 by implementations that are not controlled by the application; for 357 example, proxies, CDNs, firewalls and so on. Requiring a particular 358 version of HTTP makes it difficult to use in these situations, and 359 harms interoperability. Therefore, it is RECOMMENDED that 360 applications using HTTP not specify a minimum version of HTTP to be 361 used. 363 However, if an application's deployment would benefit from the use of 364 a particular version of HTTP (for example, HTTP/2's multiplexing), 365 this ought be noted. 367 Applications using HTTP MUST NOT specify a maximum version, to 368 preserve the protocol's ability to evolve. 370 When specifying examples of protocol interactions, applications 371 should document both the request and response messages, with complete 372 header sections, preferably in HTTP/1.1 format. For example: 374 GET /thing HTTP/1.1 375 Host: example.com 376 Accept: application/things+json 377 User-Agent: Foo/1.0 379 HTTP/1.1 200 OK 380 Content-Type: application/things+json 381 Content-Length: 500 382 Server: Bar/2.2 384 [payload here] 386 4.2. Specifying Server Behaviour 388 The most effective way to specify an application's server-side HTTP 389 behaviours is in terms of the following protocol elements: 391 * Media types [RFC6838], often based upon a format convention such 392 as JSON [RFC8259], 394 * HTTP header fields, as per Section 4.7, and 396 * The behaviour of resources, as identified by link relations 397 [RFC8288]. 399 By composing these protocol elements, an application can define a set 400 of resources, identified by link relations, that implement specified 401 behaviours, including: 403 * retrieval of their state using GET, in one or more formats 404 identified by media type; 406 * resource creation or update using POST or PUT, with an 407 appropriately identified request content format; 409 * data processing using POST and identified request and response 410 content format(s); and 412 * Resource deletion using DELETE. 414 For example, an application might specify: 416 Resources linked to with the "example-widget" link relation type are 417 Widgets. The state of a Widget can be fetched in the 418 "application/example-widget+json" format, and can be updated by PUT 419 to the same link. Widget resources can be deleted. 421 The "Example-Count" response header field on Widget representations 422 indicates how many Widgets are held by the sender. 424 The "application/example-widget+json" format is a JSON [RFC8259] 425 format representing the state of a Widget. It contains links to 426 related information in the link indicated by the Link header field 427 value with the "example-other-info" link relation type. 429 Applications can also specify the use of URI Templates [RFC6570] to 430 allow clients to generate URLs based upon runtime data. 432 4.3. Specifying Client Behaviour 434 In general, applications using HTTP ought to align their expectations 435 for client behaviour as closely as possible with that of Web 436 browsers, to avoid interoperability issues when they are used. 438 One way to do this is to define it in terms of [FETCH], since that is 439 the abstraction that browsers use for HTTP. 441 Some client behaviours (e.g., automatic redirect handling) and 442 extensions (e.g., Cookies) are not required by HTTP, but nevertheless 443 have become very common. If their use is not explicitly specified by 444 applications using HTTP, there may be confusion and interoperability 445 problems. In particular: 447 * Redirect handling - Applications need to specify how redirects are 448 expected to be handled; see Section 4.6.1. 450 * Cookies - Applications using HTTP should explicitly reference the 451 Cookie specification [I-D.ietf-httpbis-rfc6265bis] if they are 452 required. 454 * Certificates - Applications using HTTP should specify that TLS 455 certificates are to be checked according to 456 [I-D.ietf-httpbis-semantics], Section 4.3.4 when HTTPS is used. 458 Applications using HTTP MUST NOT require HTTP features that are 459 usually negotiated to be supported by clients. For example, 460 requiring that clients support responses with a certain content- 461 coding ([I-D.ietf-httpbis-semantics], Section 8.4.1) instead of 462 negotiating for it ([I-D.ietf-httpbis-semantics], Section 12.5.3) 463 means that otherwise conformant clients cannot interoperate with the 464 application. Applications can encourage the implementation of such 465 features, though. 467 4.4. Specifying URLs 469 In HTTP, the server resources that clients interact with are 470 identified with URLs [RFC3986]. As [RFC8820] explains, parts of the 471 URL are designed to be under the control of the owner (also known as 472 the "authority") of that server, to give them the flexibility in 473 deployment. 475 This means that in most cases, specifications for applications that 476 use HTTP won't contain its URLs; while it is common practice for a 477 specification of a single-deployment API to specify the path prefix 478 "/app/v1" (for example), doing so in an IETF specification is 479 inappropriate. 481 Therefore, the specification writer needs some mechanism to allow 482 clients to discovery an application's URLs. Additionally, they need 483 to specify what URL scheme(s) the application should be used with, 484 and whether to use a dedicated port, or reuse HTTP's port(s). 486 4.4.1. Discovering an Application's URLs 488 Generally, a client will begin interacting with a given application 489 server by requesting an initial document that contains information 490 about that particular deployment, potentially including links to 491 other relevant resources. Doing so assures that the deployment is as 492 flexible as possible (potentially spanning multiple servers), allows 493 evolution, and also gives the application the opportunity to tailor 494 the 'discovery document' to the client. 496 There are a few common patterns for discovering that initial URL. 498 The most straightforward mechanism for URL discovery is to configure 499 the client with (or otherwise convey to it) a full URL. This might 500 be done in a configuration document, or through another discovery 501 mechanism. 503 However, if the client only knows the server's hostname and the 504 identity of the application, there needs to be some way to derive the 505 initial URL from that information. 507 An application cannot define a fixed prefix for its URL paths; see 508 [RFC8820]. Instead, a specification for such an application can use 509 one of the following strategies: 511 * Register a Well-Known URI [RFC8615] as an entry point for that 512 application. This provides a fixed path on every potential server 513 that will not collide with other applications. 515 * Enable the server authority to convey a URL Template [RFC6570] or 516 similar mechanism for generating a URL for an entry point. For 517 example, this might be done in a configuration document or other 518 artefact. 520 Once the discovery document is located, it can be fetched, cached for 521 later reuse (if allowed by its metadata), and used to locate other 522 resources that are relevant to the application, using full URIs or 523 URL Templates. 525 In some cases, an application may not wish to use such a discovery 526 document; for example, when communication is very brief, or when the 527 latency concerns of doing so precludes the use of a discovery 528 document. These situations can be addressed by placing all of the 529 application's resources under a well-known location. 531 4.4.2. Considering URI Schemes 533 Applications that use HTTP will typically employ the "http" and/or 534 "https" URI schemes. "https" is RECOMMENDED to provide 535 authentication, integrity and confidentiality, as well as mitigate 536 pervasive monitoring attacks [RFC7258]. 538 However, application-specific schemes can also be defined. When 539 defining an URI scheme for an application using HTTP, there are a 540 number of tradeoffs and caveats to keep in mind: 542 * Unmodified Web browsers will not support the new scheme. While it 543 is possible to register new URI schemes with Web browsers (e.g. 544 registerProtocolHandler() in [HTML], as well as several 545 proprietary approaches), support for these mechanisms is not 546 shared by all browsers, and their capabilities vary. 548 * Existing non-browser clients, intermediaries, servers and 549 associated software will not recognise the new scheme. For 550 example, a client library might fail to dispatch the request; a 551 cache might refuse to store the response, and a proxy might fail 552 to forward the request. 554 * Because URLs occur in HTTP artefacts commonly, often being 555 generated automatically (e.g., in the "Location" response header 556 field), it can be difficult to assure that the new scheme is used 557 consistently. 559 * The resources identified by the new scheme will still be available 560 using "http" and/or "https" URLs. Those URLs can "leak" into use, 561 which can present security and operability issues. For example, 562 using a new scheme to assure that requests don't get sent to a 563 "normal" Web site is likely to fail. 565 * Features that rely upon the URL's origin [RFC6454], such as the 566 Web's same-origin policy, will be impacted by a change of scheme. 568 * HTTP-specific features such as cookies 569 [I-D.ietf-httpbis-rfc6265bis], authentication 570 [I-D.ietf-httpbis-semantics], caching [I-D.ietf-httpbis-cache], 571 HSTS [RFC6797], and CORS [FETCH] might or might not work 572 correctly, depending on how they are defined and implemented. 573 Generally, they are designed and implemented with an assumption 574 that the URL will always be "http" or "https". 576 * Web features that require a secure context [SECCTXT] will likely 577 treat a new scheme as insecure. 579 See [RFC7595] for more information about minting new URI schemes. 581 4.4.3. Transport Ports 583 Applications can use the applicable default port (80 for HTTP, 443 584 for HTTPS), or they can be deployed upon other ports. This decision 585 can be made at deployment time, or might be encouraged by the 586 application's specification (e.g., by registering a port for that 587 application). 589 If a non-default port is used, it needs to be reflected in the 590 authority of all URLs for that resource; the only mechanism for 591 changing a default port is changing the URI scheme (see 592 Section 4.4.2). 594 Using a port other than the default has privacy implications (i.e., 595 the protocol can now be distinguished from other traffic), as well as 596 operability concerns (as some networks might block or otherwise 597 interfere with it). Privacy implications should be documented in 598 Security Considerations. 600 See [RFC7605] for further guidance. 602 4.5. Using HTTP Methods 604 Applications that use HTTP MUST confine themselves to using 605 registered HTTP methods such as GET, POST, PUT, DELETE, and PATCH. 607 New HTTP methods are rare; they are required to be registered in the 608 HTTP Method Registry with IETF Review (see 609 [I-D.ietf-httpbis-semantics]), and are also required to be generic. 610 That means that they need to be potentially applicable to all 611 resources, not just those of one application. 613 While historically some applications (e.g., [RFC4791]) have defined 614 non-generic methods, [I-D.ietf-httpbis-semantics] now forbids this. 616 When authors believe that a new method is required, they are 617 encouraged to engage with the HTTP community early, and document 618 their proposal as a separate HTTP extension, rather than as part of 619 an application's specification. 621 4.5.1. GET 623 GET is the most common and useful HTTP method; its retrieval 624 semantics allow caching, side-effect free linking and underlies many 625 of the benefits of using HTTP. 627 A common use of GET is to perform queries, often using the query 628 component of the URL; this is a familiar pattern from Web browsing, 629 and the results can be cached, improving efficiency of an often 630 expensive process. 632 In some cases, however, GET might be unwieldy for expressing queries, 633 because of the limited syntax of the URI; in particular, if binary 634 data forms part of the query terms, it needs to be encoded to conform 635 to URI syntax. 637 While this is not an issue for short queries, it can become one for 638 larger query terms, or ones which need to sustain a high rate of 639 requests. Additionally, some HTTP implementations limit the size of 640 URLs they support -- although modern HTTP software has much more 641 generous limits than previously (typically, considerably more than 642 8000 octets, as required by [I-D.ietf-httpbis-semantics]. 644 In these cases, an application using HTTP might consider using POST 645 to express queries in the request's content; doing so avoids encoding 646 overhead and URL length limits in implementations. However, in doing 647 so it should be noted that the benefits of GET such as caching and 648 linking to query results are lost. Therefore, applications using 649 HTTP that feel a need to allow POST queries ought consider allowing 650 both methods. 652 Applications should not change their state or have other side effects 653 that might be significant to the client, since implementations can 654 and do retry HTTP GET requests that fail. Note that this does not 655 include logging and similar functions; see 656 [I-D.ietf-httpbis-semantics], Section 9.2.1. 658 Finally, note that while HTTP allows GET requests to have content 659 syntactically, this is done only to allow parsers to be generic; as 660 per [I-D.ietf-httpbis-semantics], Section 9.3.1, content on a GET has 661 no meaning, and will be either ignored or rejected by generic HTTP 662 software. 664 4.5.2. OPTIONS 666 The OPTIONS method was defined for metadata retrieval, and is used 667 both by WebDAV [RFC4918] and CORS [FETCH]. Because HTTP-based APIs 668 often need to retrieve metadata about resources, it is often 669 considered for their use. 671 However, OPTIONS does have significant limitations: 673 * It isn't possible to link to the metadata with a simple URL, 674 because OPTIONS is not the default GET method. 676 * OPTIONS responses are not cacheable, because HTTP caches operate 677 on representations of the resource (i.e., GET and HEAD). If 678 OPTIONS responses are cached separately, their interaction with 679 HTTP cache expiry, secondary keys and other mechanisms needs to be 680 considered. 682 * OPTIONS is "chatty" - always separating metadata out into a 683 separate request increases the number of requests needed to 684 interact with the application. 686 * Implementation support for OPTIONS is not universal; some servers 687 do not expose the ability to respond to OPTIONS requests without 688 significant effort. 690 Instead of OPTIONS, one of these alternative approaches might be more 691 appropriate: 693 * For server-wide metadata, create a well-known URI [RFC8615], or 694 using an already existing one if it's appropriate (e.g., HostMeta 695 [RFC6415]). 697 * For metadata about a specific resource, create a separate resource 698 and link to it using a Link response header field or a link 699 serialised into the response's content. See [RFC8288]. Note that 700 the Link header field is available on HEAD responses, which is 701 useful if the client wants to discover a resource's capabilities 702 before they interact with it. 704 4.6. Using HTTP Status Codes 706 HTTP status codes convey semantics both for the benefit of generic 707 HTTP components -- such as caches, intermediaries, and clients -- and 708 applications themselves. However, applications can encounter a 709 number of pitfalls in their use. 711 First, status codes are often generated by components other the the 712 application itself. This can happen, for example, when network 713 errors are encountered, a captive portal, proxy or Content Delivery 714 Network is present, when a server is overloaded, or it thinks it is 715 under attack. They can even be generated by generic client software 716 when certain error conditions are encountered. As a result, if an 717 application assigns specific semantics to one of these status codes, 718 a client can be misled about its state, because the status code was 719 generated by a generic component, not the application itself. 721 Furthermore, mapping application errors to individual HTTP status 722 codes one-to-one often leads to a situation where the finite space of 723 applicable HTTP status codes is exhausted. This, in turn, leads to a 724 number of bad practices -- including minting new, application- 725 specific status codes, or using existing status codes even though the 726 link between their semantics and the application's is tenuous at 727 best. 729 Instead, applications using HTTP should define their errors to use 730 the most applicable status code, making generous use of the general 731 status codes (200, 400 and 500) when in doubt. Importantly, they 732 should not specify a one-to-one relationship between status codes and 733 application errors, thereby avoiding the exhaustion issue outlined 734 above. 736 To distinguish between multiple error conditions that are mapped to 737 the same status code, and to avoid the misattribution issue outlined 738 above, applications using HTTP should convey finer-grained error 739 information in the response's message content and/or header fields. 740 [RFC7807] provides one way to do so. 742 Because the set of registered HTTP status codes can expand, 743 applications using HTTP should explicitly point out that clients 744 ought to be able to handle all applicable status codes gracefully 745 (i.e., falling back to the generic "n00" semantics of a given status 746 code; e.g., "499" can be safely handled as "400" by clients that 747 don't recognise it). This is preferable to creating a "laundry list" 748 of potential status codes, since such a list won't be complete in the 749 foreseeable future. 751 Applications using HTTP MUST NOT re-specify the semantics of HTTP 752 status codes, even if it is only by copying their definition. It is 753 RECOMMENDED they require specific reason phrases to be used; the 754 reason phrase has no function in HTTP, is not guaranteed to be 755 preserved by implementations, and is not carried at all in the HTTP/2 756 [RFC7540] message format. 758 Applications MUST only use registered HTTP status codes. As with 759 methods, new HTTP status codes are rare, and required (by 760 [I-D.ietf-httpbis-semantics]) to be registered with IETF Review. 761 Similarly, HTTP status codes are generic; they are required (by 762 [I-D.ietf-httpbis-semantics]) to be potentially applicable to all 763 resources, not just to those of one application. 765 When authors believe that a new status code is required, they are 766 encouraged to engage with the HTTP community early, and document 767 their proposal as a separate HTTP extension, rather than as part of 768 an application's specification. 770 4.6.1. Redirection 772 The 3xx series of status codes specified in 773 [I-D.ietf-httpbis-semantics], Section 15.4 direct the user agent to 774 another resource to satisfy the request. The most common of these 775 are 301, 302, 307 and 308, all of which use the Location response 776 header field to indicate where the client should send the request to. 778 There are two ways that this group of status codes differ: 780 * Whether they are permanent or temporary. Permanent redirects can 781 be used to update links stored in the client (e.g., bookmarks), 782 whereas temporary ones can not. Note that this has no effect on 783 HTTP caching; it is completely separate. 785 * Whether they allow the redirected request to change the request 786 method from POST to GET. Web browsers generally do change POST to 787 GET for 301 and 302; therefore, 308 and 307 were created to allow 788 redirection without changing the method. 790 This table summarises their relationships: 792 +=============================+===========+===========+ 793 | | Permanent | Temporary | 794 +=============================+===========+===========+ 795 | Allows changing the request | 301 | 302 | 796 | method from POST to GET | | | 797 +-----------------------------+-----------+-----------+ 798 | Does not allow changing the | 308 | 307 | 799 | request method | | | 800 +-----------------------------+-----------+-----------+ 802 Table 1 804 As noted in [I-D.ietf-httpbis-semantics], a user agent is allowed to 805 automatically follow a 3xx redirect that has a Location response 806 header field, even if they don't understand the semantics of the 807 specific status code. However, they aren't required to do so; 808 therefore, if an application using HTTP desires redirects to be 809 automatically followed, it needs to explicitly specify the 810 circumstances when this is required. 812 Applications using HTTP are encouraged to specify that 301 and 302 813 responses change the subsequent request method from POST (but no 814 other method) to GET, to be compatible with browsers. Generally, 815 when a redirected request is made, its header fields are copied from 816 the original request's. However, they can be modified by various 817 mechanisms; e.g., sent Authorization ([I-D.ietf-httpbis-semantics]) 818 and Cookie ([I-D.ietf-httpbis-rfc6265bis]) header fields will change 819 if the origin (and sometimes path) of the request changes. An 820 application using HTTP should specify if any request header fields 821 that it defines need to be modified or removed upon a redirect; 822 however, this behaviour cannot be relied upon, since a generic client 823 (like a browser) will be unaware of such requirements. 825 4.7. Specifying HTTP Header Fields 827 Applications often define new HTTP header fields. Typically, using 828 HTTP header fields is appropriate in a few different situations: 830 * The field is useful to intermediaries (who often wish to avoid 831 parsing message content), and/or 833 * The field is useful to generic HTTP software (e.g., clients, 834 servers), and/or 836 * It is not possible to include their values in the message content 837 (usually because a format does not allow it). 839 When the conditions above are not met, it is usually better to convey 840 application-specific information in other places; e.g., the message 841 content or the URL query string. 843 New header fields MUST be registered, as per 844 [I-D.ietf-httpbis-semantics]. 846 See [I-D.ietf-httpbis-semantics], Section 16.3.2 for guidelines to 847 consider when minting new header fields. 848 [I-D.ietf-httpbis-header-structure] provides a common structure for 849 new header fields, and avoids many issues in their parsing and 850 handling; it is RECOMMENDED that new header fields use it. 852 It is RECOMMENDED that header field names be short (even when field 853 compression is used, there is an overhead) but appropriately 854 specific. In particular, if a header field is specific to an 855 application, an identifier for that application can form a prefix to 856 the header field name, separated by a "-". 858 For example, if the "example" application needs to create three 859 headers, they might be called "example-foo", "example-bar" and 860 "example-baz". Note that the primary motivation here is to avoid 861 consuming more generic field names, not to reserve a portion of the 862 namespace for the application; see [RFC6648] for related 863 considerations. 865 The semantics of existing HTTP header fields MUST NOT be re-defined 866 without updating their registration or defining an extension to them 867 (if allowed). For example, an application using HTTP cannot specify 868 that the "Location" header field has a special meaning in a certain 869 context. 871 See Section 4.9 for the interaction between headers and HTTP caching; 872 in particular, request header fields that are used to "select" a 873 response have impact there, and need to be carefully considered. 875 See Section 4.10 for considerations regarding header fields that 876 carry application state (e.g., Cookie). 878 4.8. Defining Message Payloads 880 There are many potential formats for payloads; for example, JSON 881 [RFC8259], XML [XML], and CBOR [RFC7049]. Best practices for their 882 use are out of scope for this document. 884 Applications should register distinct media types for each format 885 they define; this makes it possible to identify them unambiguously 886 and negotiate for their use. See [RFC6838] for more information. 888 4.9. Leveraging HTTP Caching 890 HTTP caching [I-D.ietf-httpbis-cache] is one of the primary benefits 891 of using HTTP for applications; it provides scalability, reduces 892 latency and improves reliability. Furthermore, HTTP caches are 893 readily available in browsers and other clients, networks as forward 894 and reverse proxies, Content Delivery Networks and as part of server 895 software. 897 Even when an application using HTTP isn't designed to take advantage 898 of caching, it needs to consider how caches will handle its 899 responses, to preserve correct behaviour when one is interposed 900 (whether in the network, server, client, or intervening 901 infrastructure). 903 4.9.1. Freshness 905 Assigning even a short freshness lifetime ([I-D.ietf-httpbis-cache], 906 Section 4.2) -- e.g., 5 seconds -- allows a response to be reused to 907 satisfy multiple clients, and/or a single client making the same 908 request repeatedly. In general, if it is safe to reuse something, 909 consider assigning a freshness lifetime. 911 The most common method for specifying freshness is the max-age 912 response directive ([I-D.ietf-httpbis-cache], Section 5.2.2.9). The 913 Expires header field ([I-D.ietf-httpbis-cache], Section 5.3) can also 914 be used, but it is not necessary; all modern cache implementations 915 support Cache-Control, and specifying freshness as a delta is usually 916 more convenient and less error-prone. 918 In some situations, responses without explicit cache freshness 919 directives will be stored and served using a heuristic freshness 920 lifetime; see [I-D.ietf-httpbis-cache], Section 4.2.2. As the 921 heuristic is not under control of the application, it is generally 922 preferable to set an explicit freshness lifetime, or make the 923 response explicitly uncacheable. 925 If caching of a response is not desired, the appropriate response 926 directive is "Cache-Control: no-store". This only need be sent in 927 situations where the response might be cached; see 928 [I-D.ietf-httpbis-cache], Section 3. Note that "Cache-Control: no- 929 cache" allows a response to be stored, just not reused by a cache 930 without validation; it does not prevent caching (despite its name). 932 For example, this response cannot be stored or reused by a cache: 934 HTTP/1.1 200 OK 935 Content-Type: application/example+xml 936 Cache-Control: no-store 938 [content] 940 4.9.2. Stale Responses 942 Authors should understand that stale responses (e.g., with "Cache- 943 Control: max-age=0") can be reused by caches when disconnected from 944 the origin server; this can be useful for handling network issues. 946 If doing so is not suitable for a given response, the origin should 947 use "Cache-Control: must-revalidate". See [I-D.ietf-httpbis-cache], 948 Section 4.2.4, and also [RFC5861] for additional controls over stale 949 content. 951 Stale responses can be refreshed by assigning a validator, saving 952 both transfer bandwidth and latency for large responses; see 953 [I-D.ietf-httpbis-semantics]. 955 4.9.3. Caching and Application Semantics 957 When an application has a need to express a lifetime that's separate 958 from the freshness lifetime, this should be conveyed separately, 959 either in the response's content or in a separate header field. When 960 this happens, the relationship between HTTP caching and that lifetime 961 need to be carefully considered, since the response will be used as 962 long as it is considered fresh. 964 In particular, application authors need to consider how responses 965 that are not freshly obtained from the origin server should be 966 handled; if they have a concept like a validity period, this will 967 need to be calculated considering the age of the response (see 968 [I-D.ietf-httpbis-cache], Section 4.2.3). 970 One way to address this is to explicitly specify that all responses 971 be fresh upon use. 973 4.9.4. Varying Content Based Upon the Request 975 If an application uses a request header field to change the 976 response's headers or content, authors should point out that this has 977 implications for caching; in general, such resources need to either 978 make their responses uncacheable (e.g., with the "no-store" cache- 979 control directive defined in [I-D.ietf-httpbis-cache], 980 Section 5.2.2.3) or send the Vary response header field 981 ([I-D.ietf-httpbis-semantics], Section 12.5.5) on all responses from 982 that resource (including the "default" response). 984 For example, this response: 986 HTTP/1.1 200 OK 987 Content-Type: application/example+xml 988 Cache-Control: max-age=60 989 ETag: "sa0f8wf20fs0f" 990 Vary: Accept-Encoding 992 [content] 994 can be stored for 60 seconds by both private and shared caches, can 995 be revalidated with If-None-Match, and varies on the Accept-Encoding 996 request header field. 998 4.10. Handling Application State 1000 Applications can use stateful cookies [I-D.ietf-httpbis-rfc6265bis] 1001 to identify a client and/or store client-specific data to 1002 contextualise requests. 1004 When used, it is important to carefully specify the scoping and use 1005 of cookies; if the application exposes sensitive data or capabilities 1006 (e.g., by acting as an ambient authority), exploits are possible. 1007 Mitigations include using a request-specific token to assure the 1008 intent of the client. 1010 Applications MUST NOT make assumptions about the relationship between 1011 separate requests on a single transport connection; doing so breaks 1012 many of the assumptions of HTTP as a stateless protocol, and will 1013 cause problems in interoperability, security, operability and 1014 evolution. 1016 4.11. Client Authentication 1018 Applications can use HTTP authentication [I-D.ietf-httpbis-semantics] 1019 to identify clients. The Basic authentication scheme [RFC7617] MUST 1020 NOT be used unless the underlying transport is authenticated, 1021 integrity-protected and confidential (e.g., as provided the "HTTPS" 1022 URI scheme, or another using TLS). The Digest scheme [RFC7616] MUST 1023 NOT be used unless the underlying transport is similarly secure, or 1024 the chosen hash algorithm is not "MD5". 1026 With HTTPS, clients might also be authenticated using certificates 1027 [RFC5246]. 1029 When used, it is important to carefully specify the scoping and use 1030 of authentication; if the application exposes sensitive data or 1031 capabilities (e.g., by acting as an ambient authority), exploits are 1032 possible. Mitigations include using a request-specific token to 1033 assure the intent of the client. 1035 4.12. Co-Existing with Web Browsing 1037 Even if there is not an intent for an application to be used with a 1038 Web browser, its resources will remain available to browsers and 1039 other HTTP clients. 1041 This means that all such applications that use HTTP need to consider 1042 how browsers will interact with them, particularly regarding 1043 security. 1045 For example, if an application's state can be changed using a POST 1046 request, a Web browser can easily be coaxed into cross-site request 1047 forgery (CSRF) from arbitrary Web sites. 1049 Or, if content returned from the application's resources is under 1050 control of an attacker (for example, part of the request is reflected 1051 in the response, or the response contains external information that 1052 might be under the control of the attacker), a cross-site scripting 1053 (XSS) attack is possible, whereby an attacker can inject code into 1054 the browser and access data and capabilities on that origin. 1056 This is only a small sample of the kinds of issues that applications 1057 using HTTP must consider. Generally, the best approach is to 1058 consider the application actually as a Web application, and to follow 1059 best practices for their secure development. 1061 A complete enumeration of such practices is out of scope for this 1062 document, but some considerations include: 1064 * Using an application-specific media type in the Content-Type 1065 header field, and requiring clients to fail if it is not used. 1067 * Using X-Content-Type-Options: nosniff [FETCH] to assure that 1068 content under attacker control can't be coaxed into a form that is 1069 interpreted as active content by a Web browser. 1071 * Using Content-Security-Policy [CSP] to constrain the capabilities 1072 of active content (such as HTML [HTML]), thereby mitigating Cross- 1073 Site Scripting attacks. 1075 * Using Referrer-Policy [REFERRER-POLICY] to prevent sensitive data 1076 in URLs from being leaked in the Referer request header field. 1078 * Using the 'HttpOnly' flag on Cookies to assure that cookies are 1079 not exposed to browser scripting languages 1080 [I-D.ietf-httpbis-rfc6265bis]. 1082 * Avoiding use of compression on any sensitive information (e.g., 1083 authentication tokens, passwords), as the scripting environment 1084 offered by Web browsers allows an attacker to repeatedly probe the 1085 compression space; if the attacker has access to the path of the 1086 communication, they can use this capability to recover that 1087 information. 1089 Depending on how they are intended to be deployed, specifications for 1090 applications using HTTP might require the use of these mechanisms in 1091 specific ways, or might merely point them out in Security 1092 Considerations. 1094 An example of a HTTP response from an application that does not 1095 intend for its content to be treated as active by browsers might look 1096 like this: 1098 HTTP/1.1 200 OK 1099 Content-Type: application/example+json 1100 X-Content-Type-Options: nosniff 1101 Content-Security-Policy: default-src 'none' 1102 Cache-Control: max-age=3600 1103 Referrer-Policy: no-referrer 1105 [content] 1107 If an application has browser compatibility as a goal, client 1108 interaction ought to be defined in terms of [FETCH], since that is 1109 the abstraction that browsers use for HTTP; it enforces many of these 1110 best practices. 1112 4.13. Maintaining Application Boundaries 1114 Because the origin [RFC6454] is how many HTTP capabilities are 1115 scoped, applications also need to consider how deployments might 1116 interact with other applications (including Web browsing) on the same 1117 origin. 1119 For example, if Cookies [I-D.ietf-httpbis-rfc6265bis] are used to 1120 carry application state, they will be sent with all requests to the 1121 origin by default, unless scoped by path, and the application might 1122 receive cookies from other applications on the origin. This can lead 1123 to security issues, as well as collision in cookie names. 1125 One solution to these issues is to require a dedicated hostname for 1126 the application, so that it has a unique origin. However, it is 1127 often desirable to allow multiple applications to be deployed on a 1128 single hostname; doing so provides the most deployment flexibility 1129 and enables them to be "mixed" together (See [RFC8820] for details). 1130 Therefore, applications using HTTP should strive to allow multiple 1131 applications on an origin. 1133 To enable this, when specifying the use of Cookies, HTTP 1134 authentication realms [I-D.ietf-httpbis-semantics], or other origin- 1135 wide HTTP mechanisms, applications using HTTP should not mandate the 1136 use of a particular name, but instead let deployments configure them. 1137 Consideration should be given to scoping them to part of the origin, 1138 using their specified mechanisms for doing so. 1140 Modern Web browsers constrain the ability of content from one origin 1141 to access resources from another, to avoid leaking private 1142 information. As a result, applications that wish to expose cross- 1143 origin data to browsers will need to implement the CORS protocol; see 1144 [FETCH]. 1146 4.14. Using Server Push 1148 HTTP/2 adds the ability for servers to "push" request/response pairs 1149 to clients in [RFC7540], Section 8.2. While server push seems like a 1150 natural fit for many common application semantics (e.g., "fanout" and 1151 publish/subscribe), a few caveats should be noted: 1153 * Server push is hop-by-hop; that is, it is not automatically 1154 forwarded by intermediaries. As a result, it might not work 1155 easily (or at all) with proxies, reverse proxies, and Content 1156 Delivery Networks. 1158 * Server push can have negative performance impact on HTTP when used 1159 incorrectly; in particular, if there is contention with resources 1160 that have actually been requested by the client. 1162 * Server push is implemented differently in different clients, 1163 especially regarding interaction with HTTP caching, and 1164 capabilities might vary. 1166 * APIs for server push are currently unavailable in some 1167 implementations, and vary widely in others. In particular, there 1168 is no current browser API for it. 1170 * Server push is not supported in HTTP/1.1 or HTTP/1.0. 1172 * Server push does not form part of the "core" semantics of HTTP, 1173 and therefore might not be supported by future versions of the 1174 protocol. 1176 Applications wishing to optimise cases where the client can perform 1177 work related to requests before the full response is available (e.g., 1178 fetching links for things likely to be contained within) might 1179 benefit from using the 103 (Early Hints) status code; see [RFC8297]. 1181 Applications using server push directly need to enforce the 1182 requirements regarding authority in [RFC7540], Section 8.2, to avoid 1183 cross-origin push attacks. 1185 4.15. Allowing Versioning and Evolution 1187 It's often necessary to introduce new features into application 1188 protocols, and change existing ones. 1190 In HTTP, backwards-incompatible changes are possible using a number 1191 of mechanisms: 1193 * Using a distinct link relation type [RFC8288] to identify a URL 1194 for a resource that implements the new functionality. 1196 * Using a distinct media type [RFC6838] to identify formats that 1197 enable the new functionality. 1199 * Using a distinct HTTP header field to implement new functionality 1200 outside the message content. 1202 5. IANA Considerations 1204 This document has no requirements for IANA. 1206 6. Security Considerations 1208 Section 4.10 discusses the impact of using stateful mechanisms in the 1209 protocol as ambient authority, and suggests a mitigation. 1211 Section 4.4.2 requires support for 'https' URLs, and discourages the 1212 use of 'http' URLs, to provide authentication, integrity and 1213 confidentiality, as well as mitigate pervasive monitoring attacks. 1215 Section 4.12 highlights the implications of Web browsers' 1216 capabilities on applications that use HTTP. 1218 Section 4.13 discusses the issues that arise when applications are 1219 deployed on the same origin as Web sites (and other applications). 1221 Section 4.14 highlights risks of using HTTP/2 server push in a manner 1222 other than specified. 1224 Applications that use HTTP in a manner that involves modification of 1225 implementations -- for example, requiring support for a new URI 1226 scheme, or a non-standard method -- risk having those implementations 1227 "fork" from their parent HTTP implementations, with the possible 1228 result that they do not benefit from patches and other security 1229 improvements incorporated upstream. 1231 6.1. Privacy Considerations 1233 HTTP clients can expose a variety of information to servers. Besides 1234 information that's explicitly sent as part of an application's 1235 operation (for example, names and other user-entered data), and "on 1236 the wire" (which is one of the reasons https is recommended in 1237 Section 4.4.2), other information can be gathered through less 1238 obvious means -- often by connecting activities of a user over time. 1240 This includes session information, tracking the client through 1241 fingerprinting, and mobile code. 1243 Session information includes things like the IP address of the 1244 client, TLS session tickets, Cookies, ETags stored in the client's 1245 cache, and other stateful mechanisms. Applications are advised to 1246 avoid using session mechanisms unless they are unavoidable or 1247 necessary for operation, in which case these risks needs to be 1248 documented. When they are used, implementations should be encouraged 1249 to allow clearing such state. 1251 Fingerprinting uses unique aspects of a client's messages and 1252 behaviours to connect disparate requests and connections. For 1253 example, the User-Agent request header field conveys specific 1254 information about the implementation; the Accept-Language request 1255 header field conveys the users' preferred language. In combination, 1256 a number of these markers can be used to uniquely identify a client, 1257 impacting its control over its data. As a result, applications are 1258 advised to specify that clients should only emit the information they 1259 need to function in requests. 1261 Finally, if an application exposes the ability to run mobile code, 1262 great care needs to be taken, since any ability to observe its 1263 environment can be used as an opportunity to both fingerprint the 1264 client and to obtain and manipulate private data (including session 1265 information). For example, access to high-resolution timers (even 1266 indirectly) can be used to profile the underlying hardware, creating 1267 a unique identifier for the system. Applications are advised to 1268 avoid allowing the use of mobile code where possible; when it cannot 1269 be avoided, the resulting system's security properties need be 1270 carefully scrutinised. 1272 --- back 1274 # Changes from RFC 3205 1276 [RFC3205] captured the Best Current Practice in the early 2000's, 1277 based on the concerns facing protocol designers at the time. Use of 1278 HTTP has changed considerably since then, and as a result this 1279 document is substantially different. As a result, the changes are 1280 too numerous to list individually. 1282 7. References 1284 7.1. Normative References 1286 [I-D.ietf-httpbis-semantics] 1287 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1288 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1289 httpbis-semantics-14, 12 January 2021, 1290 . 1293 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1294 Requirement Levels", BCP 14, RFC 2119, 1295 DOI 10.17487/RFC2119, March 1997, 1296 . 1298 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1299 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1300 May 2017, . 1302 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1303 "Transport Layer Security (TLS) Application-Layer Protocol 1304 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1305 July 2014, . 1307 [RFC8820] Nottingham, M., "URI Design and Ownership", BCP 190, 1308 RFC 8820, DOI 10.17487/RFC8820, June 2020, 1309 . 1311 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1312 Specifications and Registration Procedures", BCP 13, 1313 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1314 . 1316 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1317 DOI 10.17487/RFC8288, October 2017, 1318 . 1320 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1321 Resource Identifier (URI): Generic Syntax", STD 66, 1322 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1323 . 1325 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 1326 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 1327 . 1329 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1330 DOI 10.17487/RFC6454, December 2011, 1331 . 1333 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 1334 "Deprecating the "X-" Prefix and Similar Constructs in 1335 Application Protocols", BCP 178, RFC 6648, 1336 DOI 10.17487/RFC6648, June 2012, 1337 . 1339 7.2. Informative References 1341 [HTML] WHATWG, "HTML - Living Standard", n.d., 1342 . 1344 [FETCH] WHATWG, "Fetch - Living Standard", n.d., 1345 . 1347 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1348 Interchange Format", STD 90, RFC 8259, 1349 DOI 10.17487/RFC8259, December 2017, 1350 . 1352 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1353 and D. Orchard, "URI Template", RFC 6570, 1354 DOI 10.17487/RFC6570, March 2012, 1355 . 1357 [I-D.ietf-httpbis-rfc6265bis] 1358 West, M. and J. Wilander, "Cookies: HTTP State Management 1359 Mechanism", Work in Progress, Internet-Draft, draft-ietf- 1360 httpbis-rfc6265bis-07, 7 December 2020, 1361 . 1364 [RFC7258] Farrell, S. and H. Tschofenig, "Pervasive Monitoring Is an 1365 Attack", BCP 188, RFC 7258, DOI 10.17487/RFC7258, May 1366 2014, . 1368 [I-D.ietf-httpbis-cache] 1369 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1370 Caching", Work in Progress, Internet-Draft, draft-ietf- 1371 httpbis-cache-14, 12 January 2021, 1372 . 1374 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 1375 Transport Security (HSTS)", RFC 6797, 1376 DOI 10.17487/RFC6797, November 2012, 1377 . 1379 [SECCTXT] West, M., "Secure Contexts", World Wide Web Consortium CR 1380 CR-secure-contexts-20160915, 15 September 2016, 1381 . 1383 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1384 and Registration Procedures for URI Schemes", BCP 35, 1385 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1386 . 1388 [RFC7605] Touch, J., "Recommendations on Using Assigned Transport 1389 Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605, 1390 August 2015, . 1392 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 1393 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 1394 DOI 10.17487/RFC4791, March 2007, 1395 . 1397 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 1398 Authoring and Versioning (WebDAV)", RFC 4918, 1399 DOI 10.17487/RFC4918, June 2007, 1400 . 1402 [RFC6415] Hammer-Lahav, E., Ed. and B. Cook, "Web Host Metadata", 1403 RFC 6415, DOI 10.17487/RFC6415, October 2011, 1404 . 1406 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1407 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1408 . 1410 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1411 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1412 DOI 10.17487/RFC7540, May 2015, 1413 . 1415 [I-D.ietf-httpbis-header-structure] 1416 Nottingham, M. and P. Kamp, "Structured Field Values for 1417 HTTP", Work in Progress, Internet-Draft, draft-ietf- 1418 httpbis-header-structure-19, 3 June 2020, 1419 . 1422 [XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1423 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 1424 Edition)", World Wide Web Consortium Recommendation REC- 1425 xml-20081126, 26 November 2008, 1426 . 1428 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1429 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1430 October 2013, . 1432 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale 1433 Content", RFC 5861, DOI 10.17487/RFC5861, May 2010, 1434 . 1436 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 1437 RFC 7617, DOI 10.17487/RFC7617, September 2015, 1438 . 1440 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 1441 Digest Access Authentication", RFC 7616, 1442 DOI 10.17487/RFC7616, September 2015, 1443 . 1445 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1446 (TLS) Protocol Version 1.2", RFC 5246, 1447 DOI 10.17487/RFC5246, August 2008, 1448 . 1450 [CSP] West, M., "Content Security Policy Level 3", World Wide 1451 Web Consortium WD WD-CSP3-20160913, 13 September 2016, 1452 . 1454 [REFERRER-POLICY] 1455 Eisinger, J. and E. Stark, "Referrer Policy", World Wide 1456 Web Consortium CR CR-referrer-policy-20170126, 26 January 1457 2017, 1458 . 1460 [RFC8297] Oku, K., "An HTTP Status Code for Indicating Hints", 1461 RFC 8297, DOI 10.17487/RFC8297, December 2017, 1462 . 1464 [RFC3205] Moore, K., "On the use of HTTP as a Substrate", BCP 56, 1465 RFC 3205, DOI 10.17487/RFC3205, February 2002, 1466 . 1468 Author's Address 1470 Mark Nottingham 1471 Prahran VIC 1472 Australia 1474 Email: mnot@mnot.net 1475 URI: https://www.mnot.net/