]> Cloudflare

ot-ietf@thibault.uk

Web and Internet Transport HTTP not-yet This document describes a method for clients using to advertise their signing keys. It defines a key directory format based on JWKS as defined in , as well as new HTTP Method Context to allow for in-band key discovery. 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 HTTP mailing list (), which is archived at . Source for this draft and an issue tracker can be found at .

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

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 when, and only when, they appear in all capitals, as shown here.

Configuration The key directory is served as a JSON Web Key Set (JWKS) as defined in . The "alg" parameter are restricted to algorithm registered against HTTP Signature Algorithms Section of 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.

HTTP Method Context Signature-Agent A service sending signed requests as defined in 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 .

Header Field Definition The Signature-Agent header field is an Item Structured Header . Its value MUST be a String containing a . The ABNF is: 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 . 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

Security Considerations

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.

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

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.

Access Patterns Verifiers accessing key directories may reveal information about signature verification patterns. Directory servers should avoid logging personally identifiable information from directory requests.

IANA Considerations This section contains considerations for IANA.

Well-Known 'http-message-signatures-directory' URI This document updates the "Well-Known URIs" Registry with the following values. 'http-message-signatures-directory' Well-Known URI

URI Suffix	Change Controller	Reference	Status	Related information
http-message-signatures-directory	IETF	[this document]	permanent	None

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.

"application/http-message-signatures-directory" 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

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

References Normative References 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. This document describes a mechanism for creating, encoding, and verifying digital signatures or message authentication codes over components of an HTTP message. This mechanism supports use cases where the full HTTP message may not be known to the signer and where the message may be transformed (e.g., by intermediaries) before reaching the verifier. This document also describes a means for requesting that a signature be applied to a subsequent HTTP message in an ongoing HTTP exchange. n.d. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields that wish to use a common syntax that is more restrictive than traditional HTTP field values. Section 1.1.1 of RFC 3986 defines URI syntax as "a federated and extensible naming system wherein each scheme's specification may further restrict the syntax and semantics of identifiers using that scheme." In other words, the structure of a URI is defined by its scheme. While it is common for schemes to further delegate their substructure to the URI's owner, publishing independent standards that mandate particular forms of substructure in URIs is often problematic. This document provides guidance on the specification of URI substructure in standards. This document obsoletes RFC 7320 and updates RFC 3986. n.d. 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. Informative References A new URL scheme, "data", is defined. It allows inclusion of small data items as "immediate" data, as if it had been included externally. [STANDARDS-TRACK]

Examples

Key Directory on example.com

Request with HTTP Signature-Agent This extend the examples from .

Acknowledgments TODO acknowledge.