]> Cloudflare

ot-ietf@thibault.uk

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 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 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 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 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 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 Dictionary Structured Header as defined in . Its member values MUST be an String Item which contain a . 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+json. The content MAY be base64 encoded as per . If dictonary values are not a valid URI-reference, 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:

@authority

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

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 ignore keys from a directory response that do not have a corresponding valid signature. This validation ensures the integrity of the key set and its association with the intended directory.

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 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, Alex Sandor Major, Eugenio Panero, Lucas Pardue.

Changelog v04

• Change Signature-Agent to a sf-dictionary
• Add req flag on directory response
• Add more contributors

v03

• Remove "purpose" field from web-bot-auth

v02

• Correct typos

v01

• Update content-type from application/http-message-signatures-directory to application/http-message-signatures-directory+json
• Add delegation and chaining examples: full x5c chain, AIA extension, and x5u
• Add inline directory example with data URI
• Fix well-known path in examples

v00

• Initial draft
• Definition of Signature-Agent and its three supported URI https, http, and data.
• Leverages JWKS as a directory fo HTTP Message Signatures
• Well-known and content-type