]> Akamai Technologies

rsalz@akamai.com

Akamai Technologies

mbishop@evequefou.be

Transloadit

marius@transloadit.com

Web and Internet Transport Building Blocks for HTTP APIs Redirecting HTTP requests to HTTPS, a common pattern for human-facing web resources, can be an anti-pattern for authenticated HTTP API traffic. This document discusses the pitfalls and makes deployment recommendations for authenticated HTTP APIs. It does not specify a protocol. 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 . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction It is a common pattern for HTTP servers to prefer serving resources over HTTPS. Because HTTPS uses TLS, clients receive authentication of the server and confidentiality of the resource bodies supplied by the server. In order to implement this preference, HTTP servers often listen for unencrypted requests and respond with a 3XX status code directing the client to the equivalent resource over an encrypted connection. For unauthenticated web browsing, this is a reasonable user experience bridge. Users often type bare hostnames (not URIs) into a user agent; if the user agent defaults to an unencrypted connection, the server can correct this default and require the use of encryption. This pattern is so well established that many HTTP server and intermediary implementations have a prominently displayed option to enable it automatically. When client authentication is used, more care must be taken. The client's initial request may include a Bearer token or other credential (such as a Cookie); once the request has been sent on the network, any passive attacker who can see the traffic can acquire this credential and use it. If the server performs a redirect in this situation, it does not mitigate exposure of the credential. Further, because the request will ultimately succeed if the client follows the redirect, an application developer or user who accidentally configures an unencrypted API endpoint will not necessarily notice the misconfiguration. This document describes actions API servers and clients should take in order to safeguard credentials. These recommendations are not directed at resources where no authentication is used. Some have wondered if this document is really necessary. After all, we have been telling people not to send passwords and such in the clear for decades. Regrettably, this lesson seems to be largely forgotten by those developing Web-based APIs. The blog post that motivated this document, , did a spot-check in May, 2024, and found over two dozen websites that were vulnerable to the issues listed here.

Conventions and Definitions Although this document is not an IETF Standards Track publication, it adopts the conventions for normative language to provide clarity of instructions to the implementer. 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.

Server Recommendations

Pre-Connection Redirects Various mechanisms exist to inform clients that unencrypted requests to a server are never appropriate:

• HTTP Strict Transport Security (HSTS) informs clients who make a successful connection over HTTPS that secure connections are a requirement in the future.
• HTTPS DNS records inform clients at connection time to use only secure connections to the indicated server.

Neither mechanism is foolproof. An attacker with control of the network or the DNS server could block resolution of HTTPS records on a client connecting to a new server, while HSTS requires a successful prior connection to the server and relies on the client to implement persistent storage of the HSTS directive. Used together, however, both approaches make clients less likely to send any requests over an insecure channel. HTTP API servers with authenticated endpoints SHOULD employ both mechanisms.

Connection Blocking If an API request succeeds despite having an unencrypted endpoint configured, the developer or user is less likely to notice the misconfiguration. Where possible, it is advantageous for such a misconfiguration to fail immediately so that the error can be noticed and corrected. HTTP API servers MAY induce such an early failure by not accepting unencrypted connections, e.g. on port 80. This makes it impossible for a client to send a credential over an insecure channel to the authentic server, as no such channel can be opened. HTTP API servers MAY alternatively restrict connections on port 80 to network sources which are more trusted, such as a VPN or virtual network interface. However, this mitigation is limited against active network attackers, who can impersonate the HTTP API server and accept the client's insecure connection attempt.

Credential Restriction Whenever possible, credentials should include an indicator to clients that the credential is restricted to secure contexts. For example, Cookie-based authentication SHOULD include the Secure attribute described in . Bearer tokens MAY use the format described in to indicate the expected usage to the client.

Disclosure Response Some deployments may not find it feasible to completely block unencrypted connections, whether because the hostname is shared with unauthenticated endpoints or for infrastructure reasons. Therefore, HTTP API servers need a response for when a credential has been received over an insecure channel. HTTP status code 403 (Forbidden) indicates that "the server understood the request but refuses to fulfill it" . While this is generally understood to mean that "the server considers [the credentials] insufficient to grant access," it also states that "a request might be forbidden for reasons unrelated to the credentials." HTTP API servers SHOULD return status code 403 to all requests received over an insecure channel, regardless of the validity of the presented credentials. Because a difference in behavior would enable attackers to guess and check possible credentials, an HTTP API server MUST NOT return a different client response between a valid or invalid credential presented over an insecure connection. Differences in behavior MUST only be visible on subsequent use of the credential over a secure channel.

Credential Revocation When a request is received over an unencrypted channel, the presented credential is potentially compromised. HTTP API servers SHOULD revoke such credentials immediately. When the credential is next used over a secure channel, the server MAY return an error that indicates why the credential was revoked. Credentials in a request can take on different forms. API keys and tokens are simple modes for authentication, but can be abused by attackers to forge requests and hence should be revoked if compromised. Requests can also be authenticated using derived values, where they only include digital signatures or message authentication codes (MACs) derived from credentials but not the credentials themselves. Since an attacker cannot abuse the derived values to forge requests, the server MAY choose to not revoke the credentials in this case.

Client Recommendations The following recommendations increase the success rate of the server recommendations above.

Implement Relevant Protocols Clients SHOULD support and query for HTTPS records when establishing a connection. This gives HTTP API servers an opportunity to provide more complete information about capabilities, some of which are security-relevant. Clients SHOULD respect HSTS headers received from a server. This includes implementing persistent storage of HSTS indications received from the server.

Respect Credential Restrictions Clients MUST NOT send a Cookie with the Secure attribute over an insecure channel. Clients MUST NOT send an Authorization header containing a token whose value begins with "secret-token:" over an insecure channel.

Disallow Insecure by Default When authentication is used, clients SHOULD require an explicit indication from the user or caller that an insecure context is expected which is distinct from the provided URI. Depending on the interface, this might be a UI preference or an API flag. Absent such an indication, clients of HTTP APIs MUST implement and use HTTPS exclusively.

Security Considerations This entire document is about security of HTTP API interactions. The behavior recommended in creates the potential for a denial of service attack where an attacker guesses many possible credentials over an unencrypted connection in hopes of discovering and revoking a valid one. HTTP API servers implementing this mitigation MUST also guard against such attacks, such as by limiting the number of requests before closing the connection and rate-limiting the establishment of insecure connections.

IANA Considerations This document has no IANA actions.

References Normative References This document defines the HTTP Cookie and Set-Cookie header fields. These header fields can be used by HTTP servers to store state (called cookies) at HTTP user agents, letting the servers maintain a stateful session over the mostly stateless HTTP protocol. Although cookies have many historical infelicities that degrade their security and privacy, the Cookie and Set-Cookie header fields are widely used on the Internet. This document obsoletes RFC 2965. [STANDARDS-TRACK] 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. This specification defines a mechanism enabling web sites to declare themselves accessible only via secure connections and/or for users to be able to direct their user agent(s) to interact with given sites only over secure connections. This overall policy is referred to as HTTP Strict Transport Security (HSTS). The policy is declared by web sites via the Strict-Transport-Security HTTP response header field and/or by other means, such as user agent configuration, for example. [STANDARDS-TRACK] This document specifies the "SVCB" ("Service Binding") and "HTTPS" DNS resource record (RR) types to facilitate the lookup of information needed to make connections to network services, such as for HTTP origins. SVCB records allow a service to be provided from multiple alternative endpoints, each with associated parameters (such as transport protocol configuration), and are extensible to support future uses (such as keys for encrypting the TLS ClientHello). They also enable aliasing of apex domains, which is not possible with CNAME. The HTTPS RR is a variation of SVCB for use with HTTP (see RFC 9110, "HTTP Semantics"). By providing more information to the client before it attempts to establish a connection, these records offer potential benefits to both performance and privacy. 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 RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. Informative References This document registers the "secret-token" URI scheme to aid in the identification of authentication tokens.

Acknowledgments We are grateful to Joachim Viide for his blog posting that brought up the issue.