]> Mozilla

mt@lowentropy.net

Applications and Real-Time Building Blocks for HTTP APIs Internet-Draft HTTP clients rarely make use of the Date header field when making requests. This document describes considerations for using the Date header field in requests. A method is described for correcting erroneous in Date request header fields that might arise from differences in client and server clocks. The risks of applying that correction technique are discussed. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Building Blocks for HTTP APIs Working Group mailing list (), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction Many HTTP requests are timeless. That is, the contents of the request are not bound to a specific point in time. Thus, the use of the HTTP Date header field in requests is rare; see . However, in some contexts, it is important that a request only be valid over a small period of time. One such context is when requests are signed , where including a time in a request might prevent a signed request from being reused at another time. Similarly, some uses of OHTTP might depend on the same sort of replay protection. It is possible to make anti-replay protections at servers more efficient if requests from either far in the past or into the future can be rejected. This document describes some considerations for using the Date request header field in . A new type of problem report is defined in for use in rejecting requests with a missing or incorrect Date request header field. explores the consequences of using Date header field in requests when client and server clocks do not agree. A method for recovering from differences in clocks is described in . describes the privacy considerations that apply to this technique.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Date in HTTP Requests Most HTTP clients have no need to use the Date header field in requests. This only changes if it is important that the request not be considered valid at another time. As requests are - by default - trivially copied, stored, and modified by any entity that can read them, the addition of a Date header field is unlikely to be useful in many cases. Signed HTTP requests are one example of where requests might be available to entities that are not permitted to alter their contents. Adding a Date request header field - and signing it - ensures that the request cannot be used at a very different time to what was intended. OHTTP is another example of where capture and replay of a request might be undesirable. Here, a partially trusted intermediary, an oblivious proxy resource, receives encapsulated HTTP requests. Though this entity cannot read or modify these messages, it is able to delay or replay them. The inclusion of a Date header field in these requests might be used to limit the time over which delay or replay is possible. In both cases, the inclusion of a Date request header field might be part of an anti-replay strategy at a server. A simple anti-replay scheme starts by choosing a window of time anchored at the current time. Requests with timestamps that fall within this period are remembered and rejected if they appear again; requests with timestamps outside of this window are rejected. This scheme works for any monotonic value (see for example ) and allows for efficient rejection of duplicate requests with minimal state.

Date Not Acceptable Problem Type A server can send a 400-series status code in response to a request where the Date request header field is either absent or indicates a time that is not acceptable to the server. Including content of type "application/problem+json" (or "application/problem+xml"), as defined in , in that response allows the server to provide more information about the error. This document defines a problem type of "https://iana.org/assignments/http-problem-types#date" for indicating that the Date request header field is missing or incorrect. shows an example response in HTTP/1.1 format.

Example Response

A server MUST include a Date response header field in any responses that use this problem detail type. In processing a Date header field in a request, a server MUST allow for delays in transmitting the request, retransmissions performed by transport protocols, plus any processing that might occur in the client and any intermediaries, and those parts of the server prior to processing the field. Additionally, the Date header field is only capable of expressing time with a resolution of one second. These factors could mean that the value a server receives could be some time in the past. Differences between client and server clocks are likely to be a source of most disagreements between the server time and the time expressed in Date request header field. will explore this problem in more detail and offer some means of handling these disagreements.

Clock Skew Perfect synchronization of client and server clocks is an ideal state that generally only exists in tightly controlled settings. In practice, despite good availability of time services like NTP Internet-connected endpoints often disagree about the time (see for example Section 7.1 of ). The prevalence of clock skew could justify servers being more tolerant of a larger range of values for the Date request header field. This includes accepting times that are a short duration into the future in addition to times in the past. For a server that uses the Date request header field to limit the state kept for anti-replay purposes, the amount of state might be all that determines the range of values it accepts.

Date Correction Even when a server is tolerant of small clock errors, a valid request from a client can be rejected if the client clock is outside of the range of times that a server will accept. A server might also reject a request when the client makes a request without a Date header field. A client can recover from a failure that caused by a bad clock by adjusting the time and re-attempting the request. For a fresh response (see ), the client can re-attempt the request, copying the Date header field from the response into its new request. If the response is stale, the client can add the age of the response to determine the time to use in a re-attempt; see for more. In addition to adjusting for response age, the client can adjust the time it uses based on the elapsed time since it estimates when the response was generated. Note however that if the client retries a request immediately, any additional increment is likely to be less than the one second resolution of the Date header field under most network conditions.

Limitations of Date Correction Clients MUST NOT accept the time provided by an arbitrary HTTP server as the basis for system-wide time. Even if the client code in question were able to set the time, altering the system clock in this way exposes clients to attack. The source of system time information needs to be trustworthy as the current time is a critical input to security-relevant decisions, such as whether to accept a server certificate . Use of date correction allows requests that use the correction to be correlated. Limitations on use of date corrections is necessary to ensure privacy. An immediate retry of an identical request with an update Date header field is safe in that it only provides the server with the ability to match the retry to the original request. Anything other than an immediate retry requires careful consideration of the privacy implications. Use of the same date correction for other requests can be used to link those requests to the same client. Using the same date correction is equivalent to connection reuse, cookies, TLS session tickets, or other state a client might carry between requests. Linking requests might be acceptable, but in general only where other forms of linkage already exist. Clients MUST NOT use the time correction from one server when making requests of another server. Using the same date correction across different servers might be used by servers to link client identities and to exchange information via a channel provided by the client. For clients that maintain per-server state, the specific date correction that is used for each server MUST be cleared when removing other state for that server to prevent re-identification. For instance, a web browser that remembers a date correction would forget that correction when removing cookies and other state.

Intermediaries and Date Corrections Some intermediaries, in particular those acting as reverse proxies or gateways, will rewrite the Date header field in responses. This applies especially to responses served from cache, but this might also apply to those that are forwarded directly from an origin server. For responses that are forwarded by an intermediary, changes to the Date response header field will not change how the client corrects its clock. Errors only occur if the clock at the intermediary differs significantly from the clock at the origin server or if the intermediary updates the Date response header field without also adjusting or removing the Age header field on a stale response. Servers that condition their responses on the Date header field SHOULD either ensure that intermediaries do not cache responses (by including a Cache-Control directive of no-store) or designate the response as conditional on the value of the Date request header field (by including the token "date" in a Vary header field).

Security Considerations Including a Date header field in requests reveals information about the client clock. This might be used to identify clients with vulnerability to attacks that depend on incorrect clocks. contains a discussion of the security and privacy concerns associated with date correction.

IANA Considerations IANA are requested to create a new entry in the "HTTP Problem Type" registry established by .

Type URI:

https://iana.org/assignments/http-problem-types#date

Title:

Date Not Acceptable

Recommended HTTP Status Code:

400

Reference:

of this document

References Normative References This document defines a "problem detail" as a way to carry machine- readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs. Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/ietf-wg-httpapi/rfc7807bis. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Adobe Fastly greenbytes GmbH The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. Informative References Adobe Fastly greenbytes GmbH The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC 7235, RFC 7538, RFC 7615, RFC 7694, and portions of RFC 7230. Amazon Bespoke Engineering Digital Bazaar This document describes a mechanism for creating, encoding, and verifying digital signatures or message authentication codes over components of an HTTP message. This mechanism supports use cases where the full HTTP message may not be known to the signer, and where the message may be transformed (e.g., by intermediaries) before reaching the verifier. This document also describes a means for requesting that a signature be applied to a subsequent HTTP message in an ongoing HTTP exchange. Mozilla Cloudflare This document describes a system for the forwarding of encrypted HTTP messages. This allows a client to make multiple requests of a server without the server being able to link those requests to the client or to identify the requests as having come from the same client. Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/unicorn-wg/oblivious-http. This document describes an updated version of the Encapsulating Security Payload (ESP) protocol, which is designed to provide a mix of security services in IPv4 and IPv6. ESP is used to provide confidentiality, data origin authentication, connectionless integrity, an anti-replay service (a form of partial sequence integrity), and limited traffic flow confidentiality. This document obsoletes RFC 2406 (November 1998). [STANDARDS-TRACK] The Network Time Protocol (NTP) is widely used to synchronize computer clocks in the Internet. This document describes NTP version 4 (NTPv4), which is backwards compatible with NTP version 3 (NTPv3), described in RFC 1305, as well as previous versions of the protocol. NTPv4 includes a modified protocol header to accommodate the Internet Protocol version 6 address family. NTPv4 includes fundamental improvements in the mitigation and discipline algorithms that extend the potential accuracy to the tens of microseconds with modern workstations and fast LANs. It includes a dynamic server discovery scheme, so that in many cases, specific server configuration is not required. It corrects certain errors in the NTPv3 design and implementation and includes an optional extension mechanism. [STANDARDS-TRACK] Many application technologies enable secure communication between two entities by means of Internet Public Key Infrastructure Using X.509 (PKIX) certificates in the context of Transport Layer Security (TLS). This document specifies procedures for representing and verifying the identity of application services in such interactions. [STANDARDS-TRACK]

Acknowledgments This document is a result of discussions about how to provide anti-replay protection for OHTTP in which Mark Nottingham, Eric Rescorla, and Chris Wood were instrumental.