Internet-Draft HTTP Message Signatures Directory July 2026
Meunier & Major Expires 18 January 2027 [Page]
Workgroup:
Web Bot Auth
Internet-Draft:
draft-meunier-webbotauth-httpsig-directory-latest
Published:
Intended Status:
Standards Track
Expires:
Authors:
T. Meunier
Cloudflare
S. Major
Google

HTTP Message Signatures Directory

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 a new HTTP Method Context 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-webbotauth-httpsig-directory.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-meunier-webbotauth-httpsig-directory/.

Discussion of this document takes place on the Web Bot Auth Working Group mailing list (mailto:web-bot-auth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/web-bot-auth/. Subscribe at https://www.ietf.org/mailman/listinfo/web-bot-auth/.

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/.

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 18 January 2027.

▲

Table of Contents

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 material 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 MUST be served over HTTPS. The directory MUST be served with media type application/http-message-signatures-directory+json.

A verifier 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 where its verification key material can be found. This header field contains a URI and a type parameter that identifies the discovery mechanism.

4.1. Header Field Definition

The Signature-Agent header field is a Dictionary Structured Header as defined in Section 3.2 of [STRUCTURED-HEADERS]. Its member values MUST be String Items that contain a [URI].

The type parameter is a Token Item as defined in Section 3.3.4 of [STRUCTURED-HEADERS]. If the type parameter is absent, its value is directory.

The following type values are defined:

directory

The member value identifies an origin. A verifier resolves the HTTP Message Signatures Directory using the well-known URI registered in Section 7.1 at that origin.

jwks_uri

The member value identifies a JWK Set URI.

cimd

The member value identifies a Client ID Metadata Document [CIMD] URI.

A verifier that does not support a type value MUST ignore that member. A verifier MUST NOT infer the discovery mechanism from the URI path, media type, or response body.

[[ Editor's note: strengthen requirements around jwks_uri and cimd. directory uses a signed well-known to guarantee Section 5 ]]

The URI scheme MUST be https.

[[ Editor's note: earlier versions also allowed http and data URI schemes. A data URI carries inline key material with no authority behind it, which muddied what the directory binding proves. Both are removed for now. ]]

If dictionary values are not valid URI-references, the entire header field MAY be ignored.

5. Security Considerations

5.1. Key rotation

Directory operators SHOULD implement key rotation by including multiple keys in the directory with a different validity period. When rotating keys, operators 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

Verifiers SHOULD cache the directory contents and refresh upon expiration.

Removing a key from the directory deactivates it. Verifiers stop accepting keys once their cached copy expires. The directory's cache lifetime therefore bounds how long a removed key keeps verifying.

[[ Editor's note: Recommendation around lifetime? ]]

5.2. Binding keys to the directory authority

To ensure the authenticity and integrity of the key material provided by the directory, verifiers SHOULD validate the directory's response.

It is RECOMMENDED that a directory server construct and include one HTTP Message Signature per key with the response, as defined in [HTTP-MESSAGE-SIGNATURES]. Each key SHOULD be used to provide one signature. These signatures prove possession of the advertised keys and, by covering @authority, prevent the key set from being re-served under a different authority. They do not confer authority over the serving domain: that comes from the TLS connection alone.

Directory server MUST include the following covered components:

@authority

as defined in Section 2.2.3 of [HTTP-MESSAGE-SIGNATURES]. req flag defined in Section 2.4 of [HTTP-MESSAGE-SIGNATURES] MUST be set.

content-digest

as defined in [DIGEST-FIELDS].

Directory server SHOULD include the following @signature-params as defined in Section 2.3 of [HTTP-MESSAGE-SIGNATURES]

created

as defined in Section 2.3 of [HTTP-MESSAGE-SIGNATURES]

expires

as defined in Section 2.3 of [HTTP-MESSAGE-SIGNATURES]

keyid

MUST be a base64url JWK SHA-256 Thumbprint as defined in Section 3.2 of [JWK-THUMBPRINT] for RSA and EC, and in Appendix A.3 of [JWK-OKP] for ed25519.

tag

MUST be http-message-signatures-directory

Verifiers relying on the domain binding MUST validate these signatures using the keys provided by the directory, validate the Content-Digest field against the response body, and ignore keys that do not have a corresponding valid signature. Verifiers using keys opaquely MAY skip this validation, in which case they obtain no binding. This validation checks the integrity of the key set and binds it to the intended authority.

6. Privacy Considerations

Key directories enable discovery of signing keys which may reveal information about the signing entity. Implementers should consider:

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.

Table 1: 'http-message-signatures-directory' Well-Known URI
URI Suffix Change Controller Reference Status Related information
http-message-signatures-directory IETF this document permanent None

7.2. Media Types

The following entries should be added to the IANA "media types" registry:

  • "application/http-message-signatures-directory+json"

The templates for these entries are listed below and the reference should be this RFC.

7.2.1. "application/http-message-signatures-directory+json" media type

Type name:

application

Subtype name:

http-message-signatures-directory

Required parameters:

N/A

Optional parameters:

N/A

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 Authors' Addresses section

Intended usage:

COMMON

Restrictions on usage:

N/A

Author:

see Authors' Addresses section

Change controller:

IETF

8. Normative References

[CIMD]
Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", Work in Progress, Internet-Draft, draft-ietf-oauth-client-id-metadata-document-02, , <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-02>.
[DIGEST-FIELDS]
Polli, R. and L. Pardue, "Digest Fields", RFC 9530, DOI 10.17487/RFC9530, , <https://www.rfc-editor.org/rfc/rfc9530>.
[HTTP]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <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, , <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, , <https://www.rfc-editor.org/rfc/rfc7517>.
[JWK-OKP]
Liusvaara, I., "CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)", RFC 8037, DOI 10.17487/RFC8037, , <https://www.rfc-editor.org/rfc/rfc8037>.
[JWK-THUMBPRINT]
Jones, M. and N. Sakimura, "JSON Web Key (JWK) Thumbprint", RFC 7638, DOI 10.17487/RFC7638, , <https://www.rfc-editor.org/rfc/rfc7638>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <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, , <https://www.rfc-editor.org/rfc/rfc8941>.
[URI]
Nottingham, M., "URI Design and Ownership", BCP 190, RFC 8820, DOI 10.17487/RFC8820, , <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>.

Appendix A. Examples

A.1. Key Directory on example.com 

GET /.well-known/http-message-signatures-directory HTTP/1.1
Host: example.com
Accept: application/http-message-signatures-directory+json

HTTP/1.1 200 OK
Content-Type: application/http-message-signatures-directory+json
Cache-Control: max-age=86400
{
  "keys": [{
    "kty": "OKP",
    "crv": "Ed25519",
    "kid": "NFcWBst6DXG-N35nHdzMrioWntdzNZghQSkjHNMMSjw",
    "x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs",
    "use": "sig",
    "nbf": 1712793600,
    "exp": 1715385600
  }]
}

A.2. Delegation and chaining

Delegation and chaining are out of scope for this document and are expected to be specified separately. Input is welcome on the associated GitHub issue.

[[ Editor's note: earlier versions carried informative delegation examples using x5c, AIA, and x5u. They suggested verifier behaviour this document does not define, so they are removed for clarity purposes. Issue 27 tracks a possible separate document. ]]

A.3. 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: my_test="https://directory.test";type=directory
{"hello": "world"}

HTTP/1.1 200 OK
{"message": "good dog"}

Acknowledgments

Marwan Fayed, Maxime Guerreiro, Jonathan Hoyland, Nikhil Kandoi, Akshat Mahajan, Eugenio Panero, Lucas Pardue.

Changelog

draft-meunier-webbotauth-httpsig-directory-01

draft-meunier-webbotauth-httpsig-directory-00

draft-meunier-http-message-signatures-directory-05

draft-meunier-http-message-signatures-directory-04

draft-meunier-http-message-signatures-directory-03

draft-meunier-http-message-signatures-directory-02

draft-meunier-http-message-signatures-directory-01

draft-meunier-http-message-signatures-directory-00

Authors' Addresses

Thibault Meunier
Cloudflare
Sandor Major
Google