| Internet-Draft | Registry and Signature Agent card for We | September 2025 |
| Guerreiro & Meunier | Expires 17 March 2026 | [Page] |
This document describes a JSON based format for clients using [DIRECTORY] to advertise information about themselves.¶
This document describes a JSON-based "Signature Agent Card" format for signature agent using [DIRECTORY] to advertise metadata about themselve. This includes identity, purpose, rate expectations, and cryptographic keys. It also establishes an IANA registry for Signature Agent Card parameters, enabling extensible and interoperable discovery of agent information.¶
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-registry.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-meunier-webbotauth-registry/.¶
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.¶
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 17 March 2026.¶
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.¶
Signature Agents are entities that originate or forward signed HTTP requests on behalf of users or services. They include bots developers, platforms providers, and other intermediaries using [DIRECTORY]. These agents often need to identify themselves, and establish trust with origin servers.¶
Today, the mechanisms for doing so are inconsistent: some rely on User-Agent
strings (e.g. MyCompanyBot/1.0), others on IP address lists hosted on file servers (e.g. badbots.com), and still others on out-of-band
definitions (e.g. documentation on docs.example.com/mybot). This diversity makes it difficult for operators and origin servers
to reliably discover and share a Signature Agent’s purpose, contact information, or rate
expectations.
Existing discovery mechanisms, such as [OPENID-CONNECT-DISCOVERY], do not have the necessary
granularity, and pursue different goals.¶
This document introduces a JSON-based "Signature Agent Card" format for Signature Agents, to be published in registries and discovered by servers. It also creates a new IANA registry of "Signature Agent Card Parameters" to ensure extensibility and consistency of future attributes.¶
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.¶
Signature-Agent header is defined in Section 4.1 of [DIRECTORY]. This section describes Signature Agent Card, a JSON object containing parameters describing the Signature Agent.¶
{
"name": "Example Bot",
"contact": "bot-support@example.com",
"logo": "https://example.com/",
"expected-user-agent": "Mozilla/5.0 ExampleBot",
"rfc9309-product-token": "ExampleBot",
"rfc9309-compliance": ["User-Agent", "Allow", "Disallow", "Content-Usage"],
"trigger": "fetcher",
"purpose": "tdm",
"targeted-content": "Cat pictures",
"rate-control": "429",
"rate-expectation": "avg=10rps;max=100rps",
"known-urls": ["/", "/robots.txt", "*.png"],
"keys": {
"kty": "OKP",
"crv": "Ed25519",
"kid": "NFcWBst6DXG-N35nHdzMrioWntdzNZghQSkjHNMMSjw",
"x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs",
"use": "sig",
"nbf": 1712793600,
"exp": 1715385600
}
}
¶
Unless otherwise specified, all parameters in this document are OPTIONAL. Unknown parameters MUST be ignored. All string values are UTF-8.¶
The contact parameter provides an email address or reliable communication
channel.¶
Example * bot-support@example.com * https://example.com/contact¶
The expected-user-agent parameter specifies one or more User-Agent strings as defined in Section 10.1.5 of [HTTP]
or prefix matches. Prefixes MAY use * as a wildcard.¶
Example¶
Mozilla/5.0 ExampleBot¶
The rfc9309-product-token parameter specifies the product token used for
robots.txt directives per Section 2.2.1 of [ROBOTSTXT].¶
Example¶
ExampleBot¶
The rfc9309-compliance parameter lists directives from robots.txt that the
agent implements.¶
Example¶
The purpose parameter describes the intended use of collected data. Values
SHOULD be drawn from a controlled vocabulary, such as [AIPREF-VOCAB].¶
Example¶
The targeted-content parameter specifies the type of data the agent seeks.¶
Example¶
The rate-control parameter indicates how origins can influence the agent’s
request rate.¶
TODO: specify a format¶
Example¶
CrawlDelay in robots.txt (non-standard)¶
Custom tool¶
429 + [RATELIMIT-HEADER]¶
The rate-expectation parameter specifies anticipated request volume or
burstiness.¶
TODO: consider a format such as avg=10rps;max=100rps¶
Example¶
The known-urls parameter lists predictable endpoints accessed by the agent.¶
Example¶
A registry is a list of URLs, each refering to a signature agent card.¶
The URI scheme MUST be one of:¶
https (RECOMMENDED): Points to an HTTPS resource serving a signature agent card¶
http: Points to an HTTP resource serving a signature agent card¶
data: Contains an inline signature agent card¶
Example¶
# An example list of bots https://bot1.example.com/.well-known/signature-agent-card https://crawler2.example.com/.well-known/signature-agent-card # Now the list of platforms https://zerotrust-gateway.example.com/.well-known/signature-agent-card # Below is an inlined card with the data URL scheme data:application/json;,... # Invalid, not defined¶
Below is an Augmented Backus-Naur Form (ABNF) description, as described in [ABNF].¶
The below definition imports http-URI and https-URI from [HTTP], and
dataurl from [DATAURL].¶
registry = *(cardendpointline / emptyline)
cardendpointline = (
http-URI / ; As defined in Section 4.2.1 of RFC 9110
https-URI / ; As defined in Section 4.2.2 of RFC 9110
dataurl ; As defined in Section 3 of RFC 2397
) EOL
comment = "#" *(UTF8-char-noctl / WS / "#")
emptyline = EOL
EOL = *WS [comment] NL ; end-of-line may have
; optional trailing comment
NL = %x0D / %x0A / %x0D.0A
WS = %x20 / %x09
; UTF8 derived from RFC 3629, but excluding control characters
UTF8-char-noctl = UTF8-1-noctl / UTF8-2 / UTF8-3 / UTF8-4
UTF8-1-noctl = %x21 / %x22 / %x24-7F ; excluding control, space, "#"
UTF8-2 = %xC2-DF UTF8-tail
UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail /
%xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail
UTF8-4 = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail /
%xF4 %x80-8F 2UTF8-tail
UTF8-tail = %x80-BF
¶
A signature agent MAY submit their signature agent card to an origin, or the origin MAY manually add them to their local registry.¶
A registry MAY be provided via a GitHub repository, a public file server, or a dedicated endpoint.¶
The registry SHOULD be served over HTTPS.¶
A client application SHOULD validate the directory format and reject malformed entries.¶
Signature Agent Card format defined in Section 3 extends the
format of Signature-Agent header as defined in Section 4.1 of [DIRECTORY].¶
When used for HTTP Message Signatures, and hosted on a well-known URL, Signature
Agent Card MAY be discovered via a Signature-Agent header.¶
Malicious actors may put properties which are not theirs in the registry. Client SHOULD verify signature if they are present.¶
New registrations need to list the following attributes:¶
The name requested (e.g. "useragent"). This name is case sensitive. Names may not match other registered names in a case-insensitive manner unless the Designated Experts state that there is a compelling reason to allow an exception¶
Brief description of the Header Parameter¶
For Standards Track RFCs, list the "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included.¶
Where this parameter is defined¶
Any notes associated with the entry¶
New entries in this registry are subject to the Specification Required registration policy ([RFC8126], Section 4.6). Designated experts need to ensure that the token type is defined to be used for both token issuance and redemption. Additionally, the experts can reject registrations on the basis that they do not meet the security and privacy requirements defined in TODO.¶
This section registers the Signature Agent Card Parameter names defined in Section 3 in this registry.¶
TODO¶
TODO¶
The editor would also like to thank the following individuals (listed in alphabetical order) for feedback, insight, and implementation of this document -¶