]> Cloudflare

ot-ietf@thibault.uk

Google

ietf@sandormajor.com

Web and Internet Transport Web Bot Auth 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 a new HTTP Method Context 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 Web Bot Auth Working Group mailing list (), which is archived at . Subscribe 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 material 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 served over HTTPS. The directory MUST be served with media type application/http-message-signatures-directory+json. A 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 where its verification key material can be found. This header field contains a URI and a type parameter that identifies the discovery mechanism.

Header Field Definition The Signature-Agent header field is a Dictionary Structured Header as defined in . Its member values MUST be String Items that contain a . The type parameter is a Token Item as defined in . If the type parameter is absent, its value is directory. The following type values are defined:

directory

The member value identifies an origin. For http and https URI values, a client resolves the HTTP Message Signatures Directory using the well-known URI registered in at that origin. For data URI values, the member value contains an inline HTTP Message Signatures Directory.

jwks_uri

The member value identifies a JWK Set URI.

cimd

The member value identifies a Client ID Metadata Document URI.

A client that does not support a type value MUST ignore that member. A client MUST NOT infer the discovery mechanism from the URI path, media type, or response body. The URI scheme MUST be one of:

• https (RECOMMENDED): Points to an HTTPS resource
• http: Points to an HTTP resource
• data: Contains inline key material

When using the data URI scheme with type=directory, the media type MUST be application/http-message-signatures-directory+json. The content MAY be base64 encoded as per . The data URI scheme MUST NOT be used with other type values. If dictionary values are not valid URI-references, the entire header field MAY be ignored.

Security Considerations

Key rotation Clients SHOULD implement key rotation by including multiple keys in the directory with a 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.

Binding keys to the directory authority To ensure the authenticity and integrity of the key material provided by the directory, clients SHOULD validate the directory's response. When a directory server provides a key directory over HTTP or HTTPS, it is RECOMMENDED that it constructs and includes one HTTP Message Signatures per keys with the response, as defined in . Each key SHOULD be used to provide one signature. Directory server SHOULD include the following covered components:

@authority

as defined in . req flag defined in MUST be set.

content-digest

as defined in .

Directory server SHOULD include the following @signature-params as defined in

created

as defined in

expires

as defined in

keyid

MUST be a base64url JWK SHA-256 Thumbprint as defined in for RSA and EC, and in for ed25519.

tag

MUST be http-message-signatures-directory

Clients SHOULD validate these signatures using the keys provided by the directory. Clients SHOULD validate the Content-Digest field against the response body. Clients SHOULD ignore keys from a directory response that do not have a corresponding valid signature. This validation checks the integrity of the key set and binds it to the intended authority.

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+json"

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

"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

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 Okta This specification defines a mechanism through which an OAuth client can identify itself to authorization servers, without prior dynamic client registration or other existing registration. This is through the usage of a URL as a client_id in an OAuth flow, where the URL refers to a document containing the necessary client metadata, enabling the authorization server to fetch the metadata about the client as needed. This document defines HTTP fields that support integrity digests. The Content-Digest field can be used for the integrity of HTTP message content. The Repr-Digest field can be used for the integrity of HTTP representations. Want-Content-Digest and Want-Repr-Digest can be used to indicate a sender's interest and preferences for receiving the respective Integrity fields. This document obsoletes RFC 3230 and the Digest and Want-Digest HTTP fields. 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 defines how to use the Diffie-Hellman algorithms "X25519" and "X448" as well as the signature algorithms "Ed25519" and "Ed448" from the IRTF CFRG elliptic curves work in JSON Object Signing and Encryption (JOSE). This specification defines a method for computing a hash value over a JSON Web Key (JWK). It defines which fields in a JWK are used in the hash computation, the method of creating a canonical form for those fields, and how to convert the resulting Unicode string into a byte sequence to be hashed. The resulting hash value can be used for identifying or selecting the key represented by the JWK that is the subject of the thumbprint. 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] This document provides a set of standard Public Key Cryptography (PKC) test keys that may be used wherever pre-generated keys and associated operations like digital signatures are required. Like the European Institute for Computer Antivirus Research (EICAR) virus test and the Generic Test for Unsolicited Bulk Email (GTUBE) spam test files, these publicly known test keys can be detected and recognised by applications consuming them as being purely for testing purposes without assigning any security properties to them. This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK]

Examples

Key Directory on example.com

Delegation and chaining There are multiple methods to perform delegation and chaining. There are no specific methods that have been favored by implementation so far, should they even support them. It is adviced to consider delegation as experimental for now, and provide input on the associated GitHub issue.

Key Directory on sub.example.com with a delegation from example.com via x5c full certificate chain In this example, example.com key is testECCP256 provided in . Certificate chain is passed via x5c key parameter defined in .

Key Directory on sub.example.com with a delegation from example.com via a leaf certificate and AIA field In this example, example.com key is testECCP256 provided in . Certificate chain is passed via x5c key parameter defined in , and the root certificate is signaled by the presence of an Authority Information Access extension as defined in . The AIA extension is as follow The verifier should validate the signature with the public key in the Signature-Agent, match the public key with the leaf cert, then fetch the root cert from the AIA URI and verify the leaf cert with it.

Key Directory on sub.example.com with a delegation from example.com via x5u field Leveraging x5c imposes that a PEM encoded certificate is present in the returned JWKS. If size is a constraint, or deployment imposes a more dynamic certificate management, directory server may use x5u key parameter defined in .

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

Request with data URI Signature-Agent A Signature-Agent using data URI can be used to communicate an ephemeral keys, as long as there is a chain to a certificate trusted by the origin. In this example, the directory is signed by example.com. The CA is self-signed, even though it MAY be part of an existing PKI.

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

Changelog draft-meunier-webbotauth-httpsig-directory-00

• Rename draft from draft-meunier-http-message-signatures-directory.
• Add typed Signature-Agent discovery with directory, jwks_uri, and cimd; default to directory when no type is present.
• Add Content-Digest to directory response validation.
• Update Signature-Agent examples to use type=directory.
• Fix wording around URI values and directory response signatures.

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

• Add Sandor Major as an author.
• Remove a stale author TODO from the examples.

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

• Change Signature-Agent to a Structured Fields dictionary.
• Add the req flag on directory response signatures.
• Add contributors.

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

• Remove the purpose field from the Web Bot Auth example.

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

• Fix typos.

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

• Change the media type from application/http-message-signatures-directory to application/http-message-signatures-directory+json.
• Add delegation and chaining examples using a full x5c chain, AIA, and x5u.
• Add an inline directory example using a data URI.
• Fix the well-known path in examples.

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

• Initial draft.
• Define Signature-Agent for https, http, and data URI values.
• Use JWKS as a directory for HTTP Message Signatures keys.
• Define the well-known URI and media type.