Building Blocks for HTTP APIs R. Salz Internet-Draft M. Bishop Intended status: Best Current Practice Akamai Technologies Expires: 10 May 2025 M. Kleidl Transloadit 6 November 2024 API Keys and Privacy draft-ietf-httpapi-privacy-00 Abstract Redirecting HTTP requests to HTTPS, a common pattern for human-facing web resources, can be an anti-pattern for authenticated API traffic. This document discusses the pitfalls and makes deployment recommendations for authenticated HTTP APIs. It does not specify a protocol. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://ietf-wg- httpapi.github.io/draft-ietf-httpapi-privacy/draft-ietf-httpapi- privacy.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-httpapi-privacy/. Discussion of this document takes place on the Building Blocks for HTTP APIs Working Group mailing list (mailto:httpapi@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/httpapi/. Subscribe at https://www.ietf.org/mailman/listinfo/httpapi/. Source for this draft and an issue tracker can be found at https://github.com/ietf-wg-httpapi/httpapi-privacy. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Salz, et al. Expires 10 May 2025 [Page 1] Internet-Draft privacy November 2024 Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 10 May 2025. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 2. Server Recommendations . . . . . . . . . . . . . . . . . . . 3 2.1. Pre-Connection Redirects . . . . . . . . . . . . . . . . 3 2.2. Connection Blocking . . . . . . . . . . . . . . . . . . . 4 2.3. Credential Restriction . . . . . . . . . . . . . . . . . 4 2.4. Credential Revocation . . . . . . . . . . . . . . . . . . 5 3. Client Recommendations . . . . . . . . . . . . . . . . . . . 5 3.1. Implement Relevant Protocols . . . . . . . . . . . . . . 5 3.2. Respect Credential Restrictions . . . . . . . . . . . . . 5 3.3. Disallow Insecure by Default . . . . . . . . . . . . . . 5 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 6.2. Informative References . . . . . . . . . . . . . . . . . 6 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 7 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 1. 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. Salz, et al. Expires 10 May 2025 [Page 2] Internet-Draft privacy November 2024 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; 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. 1.1. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Server Recommendations 2.1. Pre-Connection Redirects Various mechanisms exist to inform clients that unencrypted requests to a server are never appropriate: Salz, et al. Expires 10 May 2025 [Page 3] Internet-Draft privacy November 2024 * HTTP Strict Transport Security (HSTS) [RFC6797] informs clients who make a successful connection over HTTPS that secure connections are a requirement in the future. * HTTPS DNS records [RFC9460] 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. Servers with authenticated endpoints SHOULD employ both mechanisms. 2.2. 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. 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. However, this mitigation is limited against active network attackers, who can impersonate the server and accept the client's insecure connection attempt. 2.3. 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 Section 4.1.2.5 of [RFC6265]. Bearer tokens MAY use the format described in [RFC8959] to indicate the expected usage to the client. Salz, et al. Expires 10 May 2025 [Page 4] Internet-Draft privacy November 2024 2.4. Credential Revocation 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, servers need a response for when a valid credential has been received over an insecure channel. Because a difference in behavior would enable attackers to guess and check possible credentials, a 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. When a request is received over an unencrypted channel, the presented credential is potentially compromised. Servers SHOULD revoke such credentials immediately. When the credential is next used over a secure channel, a server MAY return an error that indicates why the credential was revoked. 3. Client Recommendations The following recommendations increase the success rate of the server recommendations above. 3.1. Implement Relevant Protocols Clients SHOULD support and query for HTTPS records [RFC9460] when establishing a connection and SHOULD respect HSTS headers [RFC6797] received from a server. This includes implementing persistent storage of HSTS indications received from the server. 3.2. Respect Credential Restrictions Clients MUST NOT send a Cookie with the Secure attribute [RFC6265] over an insecure channel. Clients MUST NOT send an Authorization header containing a token whose value begins with "secret-token:" over an insecure channel. 3.3. 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. Without such an indication, attempts to send credentials should fail without producing any network traffic. Salz, et al. Expires 10 May 2025 [Page 5] Internet-Draft privacy November 2024 4. Security Considerations This entire document is about security of HTTP API interactions. The behavior recommended in Section 2.4 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. 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. 5. IANA Considerations This document has no IANA actions. 6. References 6.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, DOI 10.17487/RFC6265, April 2011, . [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict Transport Security (HSTS)", RFC 6797, DOI 10.17487/RFC6797, November 2012, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9460] Schwartz, B., Bishop, M., and E. Nygren, "Service Binding and Parameter Specification via the DNS (SVCB and HTTPS Resource Records)", RFC 9460, DOI 10.17487/RFC9460, November 2023, . 6.2. Informative References [BLOG] Viide, J., "Your API Shouldn't Redirect HTTP to HTTPS", May 2024, . Salz, et al. Expires 10 May 2025 [Page 6] Internet-Draft privacy November 2024 [RFC8959] Nottingham, M., "The "secret-token" URI Scheme", RFC 8959, DOI 10.17487/RFC8959, January 2021, . Acknowledgments We are grateful to Joachim Viide for his [BLOG] blog posting that brought up the issue. Authors' Addresses Rich Salz Akamai Technologies Email: rsalz@akamai.com Mike Bishop Akamai Technologies Email: mbishop@evequefou.be Marius Kleidl Transloadit Email: marius@transloadit.com Salz, et al. Expires 10 May 2025 [Page 7]