HTTP T. Meunier Internet-Draft Cloudflare Intended status: Standards Track 15 April 2025 Expires: 17 October 2025 HTTP Message Signatures Directory draft-meunier-http-message-signatures-directory-00 Abstract This document describes a method for clients using [HTTP-MESSAGE-SIGNATURES] to advertise their signing keys. It defines a key directory format based on JWKS as defined in Section 5 of [JWK], as well as new HTTP Method Context to allow for in-band key discovery. 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://thibmeu.github.io/http-message-signatures-directory/draft- meunier-http-message-signatures-directory.html. Status information for this document may be found at https://datatracker.ietf.org/doc/ draft-meunier-http-message-signatures-directory/. Discussion of this document takes place on the HTTP mailing list (mailto:ietf-http-wg@w3.org), which is archived at https://lists.w3.org/Archives/Public/ietf-http-wg/. Source for this draft and an issue tracker can be found at https://github.com/thibmeu/http-message-signatures-directory. 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/. Meunier Expires 17 October 2025 [Page 1] Internet-Draft HTTP Message Signatures Directory April 2025 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 17 October 2025. Copyright Notice Copyright (c) 2025 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 3. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 3 4. HTTP Method Context Signature-Agent . . . . . . . . . . . . . 3 4.1. Header Field Definition . . . . . . . . . . . . . . . . . 4 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 5.1. Key rotation . . . . . . . . . . . . . . . . . . . . . . 4 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 4 6.1. Directory Content . . . . . . . . . . . . . . . . . . . . 5 6.2. Access Patterns . . . . . . . . . . . . . . . . . . . . . 5 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 7.1. Well-Known 'http-message-signatures-directory' URI . . . 5 7.2. Media Types . . . . . . . . . . . . . . . . . . . . . . . 5 7.2.1. "application/http-message-signatures-directory" media type . . . . . . . . . . . . . . . . . . . . . . . . 5 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 8.1. Normative References . . . . . . . . . . . . . . . . . . 6 8.2. Informative References . . . . . . . . . . . . . . . . . 7 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 7 A.1. Key Directory on example.com . . . . . . . . . . . . . . 7 A.2. Request with HTTP Signature-Agent . . . . . . . . . . . . 8 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 Meunier Expires 17 October 2025 [Page 2] Internet-Draft HTTP Message Signatures Directory April 2025 1. Introduction [HTTP-MESSAGE-SIGNATURES] allow a signer to generate a signature over an HTTP message, and a verifier to validate it. The specification assumes verifiers have prior knowledge of signers' key material, requiring out-of-band key distribution mechanisms. This creates deployment friction and limits the ability to dynamically verify signatures from previously unknown signers. This document defines: 1. A standardized key directory format based on JWKS for publishing HTTP Message Signatures keys 2. A well-known URI location for discovering these key directories 3. A new HTTP header field enabling in-band key directory location discovery Together, these mechanisms enable key distribution and discovery for HTTP Message Signatures cryptographic material. 2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Configuration The key directory is served as a JSON Web Key Set (JWKS) as defined in Section 5 of [JWK]. The "alg" parameter are restricted to algorithm registered against HTTP Signature Algorithms Section of [HTTP-MESSAGE-SIGNATURES-IANA] The directory SHOULD be server over HTTPS. The directory MUST be served with media type application/http-message-signatures-directory. Client application SHOULD validate the directory format and reject malformed entries. 4. HTTP Method Context Signature-Agent A service sending signed requests as defined in [HTTP-MESSAGE-SIGNATURES] MAY include a Signature-Agent header field to communicate its signing key directory. This header field contains a URI allowing retrieval of an HTTP Message Signatures Directory as defined in Section 3. Meunier Expires 17 October 2025 [Page 3] Internet-Draft HTTP Message Signatures Directory April 2025 4.1. Header Field Definition The Signature-Agent header field is an Item Structured Header [STRUCTURED-HEADERS]. Its value MUST be a String containing a [URI]. The ABNF is: Signature-Agent = sf-string ; Section 3.3.3 of {{STRUCTURED-HEADERS}} The URI scheme MUST be one of: - *https (RECOMMENDED)*: Points to an HTTPS resource serving the key directory - *http*: Points to an HTTP resource serving the key directory - *data*: Contains an inline key directory When using the "data" URI scheme, the media type MUST be application/ http-message-signatures-directory. The content MAY be base64 encoded as per [BASE64]. Multiple Signature-Agent header fields MAY be present in a request. Processors SHOULD use the first valid URI that provides a valid key directory. TODO: for inlining, CBOR Keys could be useful 5. Security Considerations 5.1. Key rotation Clients SHOULD implement key rotation by including multiple keys in the directory with different validity period. When rotating keys, clients SHOULD: 1. Add the new key to the directory before its intended use date 2. Continue to include the old key until its expiration date 3. Remove expired keys from the directory Servers SHOULD cache the directory contents and refresh upon expiration. 6. Privacy Considerations Key directories enable discovery of signing keys which may reveal information about the signing entity. Implementers should consider: Meunier Expires 17 October 2025 [Page 4] Internet-Draft HTTP Message Signatures Directory April 2025 6.1. Directory Content Key directories should only contain keys actively used for signing. Including additional keys or metadata may expose unnecessary information about the signing service. 6.2. Access Patterns Verifiers accessing key directories may reveal information about signature verification patterns. Directory servers should avoid logging personally identifiable information from directory requests. 7. IANA Considerations This section contains considerations for IANA. 7.1. Well-Known 'http-message-signatures-directory' URI This document updates the "Well-Known URIs" Registry [WellKnownURIs] with the following values. +===============+============+===========+===========+=============+ | URI Suffix | Change | Reference | Status | Related | | | Controller | | | information | +===============+============+===========+===========+=============+ | http-message- | IETF | [this | permanent | None | | signatures- | | document] | | | | directory | | | | | +---------------+------------+-----------+-----------+-------------+ Table 1: 'http-message-signatures-directory' Well-Known URI 7.2. Media Types The following entries should be added to the IANA "media types" registry: * "application/http-message-signatures-directory" The templates for these entries are listed below and the reference should be this RFC. 7.2.1. "application/http-message-signatures-directory" media type Type name: application Subtype name: http-message-signatures-directory Required parameters: N/A Optional parameters: N/A Meunier Expires 17 October 2025 [Page 5] Internet-Draft HTTP Message Signatures Directory April 2025 Encoding considerations: "binary" Security considerations: see Section 5 Interoperability considerations: N/A Published specification: this specification Applications that use this media type: Services that implement the signer role for HTTP Message Signatures and verifiers that interact with the signer for the purpose of validating signatures. Fragment identifier considerations: N/A Additional information: Magic number(s): N/A Deprecated alias names for this type: N/A File extension(s): N/A Macintosh file type code(s): N/A Person and email address to contact for further information: see Aut hors' Addresses section Intended usage: COMMON Restrictions on usage: N/A Author: see Authors' Addresses section Change controller: IETF 8. References 8.1. Normative References [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . [HTTP-MESSAGE-SIGNATURES] Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP Message Signatures", RFC 9421, DOI 10.17487/RFC9421, February 2024, . [HTTP-MESSAGE-SIGNATURES-IANA] "HTTP Message Signatures", n.d., . [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Meunier Expires 17 October 2025 [Page 6] Internet-Draft HTTP Message Signatures Directory April 2025 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [STRUCTURED-HEADERS] Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, . [URI] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 8820, DOI 10.17487/RFC8820, June 2020, . [WellKnownURIs] "Well-Known URIs", n.d., . 8.2. Informative References [BASE64] Masinter, L., "The "data" URL scheme", RFC 2397, DOI 10.17487/RFC2397, August 1998, . Appendix A. Examples A.1. Key Directory on example.com GET /.well-known/bar HTTP/1.1 Host: example.com Accept: application/http-message-signatures-directory HTTP/1.1 200 OK Content-Type: application/http-message-signatures-directory Cache-Control: max-age=86400 { "keys": { "kty": "OKP", "crv": "Ed25519", "kid": "NFcWBst6DXG-N35nHdzMrioWntdzNZghQSkjHNMMSjw", "x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs", "use": "sig", "nbf": 1712793600, "exp": 1715385600 } } Meunier Expires 17 October 2025 [Page 7] Internet-Draft HTTP Message Signatures Directory April 2025 A.2. Request with HTTP Signature-Agent This extend the examples from Appendix B of [HTTP-MESSAGE-SIGNATURES]. POST /foo?param=Value&Pet=dog HTTP/1.1 Host: example.com Signature-Agent: https://directory.test {"hello": "world"} HTTP/1.1 200 OK {"message": "good dog"} Acknowledgments TODO acknowledge. Author's Address Thibault Meunier Cloudflare Email: ot-ietf@thibault.uk Meunier Expires 17 October 2025 [Page 8]