HTTP Message Signatures Directory
draft-meunier-http-message-signatures-directory-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Thibault Meunier | ||
| Last updated | 2025-04-15 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-meunier-http-message-signatures-directory-00
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,
<https://www.rfc-editor.org/rfc/rfc9110>.
[HTTP-MESSAGE-SIGNATURES]
Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP
Message Signatures", RFC 9421, DOI 10.17487/RFC9421,
February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.
[HTTP-MESSAGE-SIGNATURES-IANA]
"HTTP Message Signatures", n.d.,
<https://www.iana.org/assignments/http-message-signature/
http-message-signature.xhtml>.
[JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015,
<https://www.rfc-editor.org/rfc/rfc7517>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
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, <https://www.rfc-editor.org/rfc/rfc8174>.
[STRUCTURED-HEADERS]
Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
<https://www.rfc-editor.org/rfc/rfc8941>.
[URI] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 8820, DOI 10.17487/RFC8820, June 2020,
<https://www.rfc-editor.org/rfc/rfc8820>.
[WellKnownURIs]
"Well-Known URIs", n.d.,
<https://www.iana.org/assignments/well-known-uris/well-
known-uris.xhtml>.
8.2. Informative References
[BASE64] Masinter, L., "The "data" URL scheme", RFC 2397,
DOI 10.17487/RFC2397, August 1998,
<https://www.rfc-editor.org/rfc/rfc2397>.
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]