HTMLTrust: Cryptographically Signed Sections of HTML

1.1. Scope

This document specifies:¶

• The canonicalization algorithm that transforms an HTML subtree into a byte string suitable for hashing (Section 4).¶

• The signing payload binding (Section 5).¶

• The encoding of hashes and signatures on the wire (Section 6).¶

• An IANA-style registry of signature and hash algorithms (Section 7).¶

• Key resolution mechanisms for the signer identifier (Section 8).¶

• The HTTP API exposed by a federated trust directory (Section 10).¶

• The endorsement document format (Section 11).¶

• The verification procedure that a verifier MUST follow (Section 12).¶

This document does not specify the HTML element, its DOM interface, parsing behavior, rendering, user-agent UI, or accessibility considerations. Those are defined in [HTMLTRUST-W3C].¶

1.2. Related Work and Adjacent Efforts

HTMLTrust composes with rather than replaces several existing web-platform mechanisms. Subresource Integrity [SRI] provides byte-level integrity for fetched subresources and does not attest to authorship. Signed HTTP Exchanges [SXG] sign complete HTTP responses bound to an origin, at response granularity rather than per-region authorship. C2PA Content Credentials [C2PA] provides provenance metadata for media assets through sidecars; HTMLTrust extends an analogous goal to in-document HTML text regions, in band rather than via sidecars. XML Digital Signatures [XMLDSIG] attempted full structural signing of XML; its operational fragility across implementations informs the deliberately narrow semantic-subset signing specified in Section 4.¶

DomainKeys Identified Mail [RFC6376] provided the operational template of separating cryptographic verification from policy-driven trust decision. JSON Web Signature [RFC7515] and HTTP Message Signatures [RFC9421] are used as building blocks for endorsement signing (Section 11.2) and directory submission authentication (Section 10.8) respectively. The W3C Decentralized Identifiers specification [W3C.did-core] supplies one of the key-resolution methods defined in Section 8.1.¶

Several active W3C Community Groups address concerns adjacent to HTMLTrust. The Credible Web Community Group [CREDIBLE-WEB] has produced the Credibility Signals catalog and hosts research on reputation graphs, credibility scoring, and originator-profile mechanisms; the Originator Profile initiative [ORIGINATOR-PROFILE] presented to that group in August 2024 is an independent author-attestation effort whose goals overlap with this work. The Decentralized Fact-checking and Provenance Organization Community Group [DEFACTO] researches decentralized provenance for text-based content, with architectural overlap with the endorsement and trust-directory model defined in Sections 10 and 11. The AI Content Disclosure Community Group [AI-CONTENT-DISCLOSURE] is defining structured syntax for declaring AI-authored content under emerging regulatory regimes; HTMLTrust's claim namespace, defined in the companion [HTMLTRUST-W3C], is intended to compose with such disclosure metadata when carried inside a signed section. The Credentials Community Group [CREDENTIALS-CG] is the originating community for [W3C.did-core] and the Verifiable Credentials work, both used as building blocks. The Anti-Fraud Community Group [ANTIFRAUD-CG] addresses web-platform mitigations for fraudulent content delivery, an adjacent threat surface to author impersonation.¶

1.3. 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.¶

4.1. Inputs

The input to canonicalization is a DOM subtree rooted at the signed section element. For the purposes of this document, the subtree is treated as the abstract tree defined by the HTML Living Standard parser applied to the source octets. A verifier MUST use that parser model, or an implementation with the same tokenization, tree-construction, and character-reference behavior. A live DOM is suitable only when it is the parser snapshot before script-driven mutation; a post-mutation DOM is a different verification input and MUST be reported as such by the W3C processing model.¶

A verifier that operates on bytes (for example, a crawler verifying without instantiating a DOM) MUST produce the same result as a DOM-aware verifier on the same source octets.¶

The signed document URL is the final response URL after redirects. The base URL used to resolve signed href and src values is the document base URL computed by the HTML Standard from the accepted source snapshot, with the signed document URL as its fallback base URL. Runtime mutation of the document URL or a base element MUST NOT change the base URL of an existing source-snapshot result. A verifier operating outside a browser MUST receive the signed document URL and MUST apply the same HTML base-URL algorithm. The location in the signing object is derived from the signed document URL, not from the document base URL.¶

Portable-profile validation is performed on the source octets and parser diagnostics before the recovered DOM tree is accepted as verification input. A verifier MUST retain enough tokenizer and tree-construction diagnostics to detect the rejected cases in Section 4.1.1. A DOM that has already discarded duplicate attributes or repaired malformed markup is insufficient by itself. If the source octets are unavailable, verification MUST fail with "source-refetch-failed". If the verifier cannot produce the required parser diagnostics from available source, it MUST fail with "parser-profile-unsupported". It MUST NOT treat a live or reconstructed DOM as portable input.¶

In particular, HTML character references are resolved by the parse model before text normalization (Section 4.4). A byte-oriented implementation MUST decode the full set of HTML5 named character references, matched case-sensitively (Ω and ω are distinct). This document requires character references in signed content to be semicolon-terminated and does not define canonical behavior for the legacy unterminated forms. Numeric character references are decoded using the HTML5 rules: a value of zero, a value greater than U+10FFFF, or a surrogate code point (U+D800..U+DFFF) becomes U+FFFD, and a C1 control in the range U+0080..U+009F maps through the standard windows-1252 replacement table. The abbreviated "common entity" tables shipped by some early implementations are NOT conforming.¶

4.2. Walk and text extraction

The canonicalizer performs a depth-first, document-order traversal of the subtree. At each node:¶

• If the node is a Text node, its data contributes to the canonical content per Section 4.4.¶

• If the node is an Element, the canonicalizer:¶

  1. Determines whether the element is included, excluded, or boundary- producing per Section 4.3.¶

  2. If included, emits any signed semantic attribute records for the element per Section 4.3.2.¶

  3. If included, recurses into its children.¶

  4. If the element produces a block boundary (Section 4.5), emits the boundary marker after the recursion result.¶

• If the node is a Comment, ProcessingInstruction, or DocumentType, it is ignored and contributes nothing.¶

A signed section element MAY itself be a descendant of another signed section element. The inner element and its subtree are canonicalized independently; from the outer element's perspective, the inner element contributes its canonical content as if it were a transparent block- producing element.¶

4.3. Element categories

Elements are partitioned into three categories.¶

@attr ":" element-local-name ":" attribute-name ":" escaped-value "\n"

4.4. Text normalization

For each Text node included in the walk, its data is normalized as follows, in order:¶

1. Apply Unicode Normalization Form NFKC ([UNICODE-NFC]).¶

2. Strip the formatting characters defined in Section 4.4.2.¶

3. Apply the whitespace mapping defined in Section 4.4.3.¶

4. Apply the punctuation normalizations defined in Section 4.4.4.¶

4.5. Block structure

A boundary-producing element (Section 4.3.3) emits a single U+000A LINE FEED character after its descendants have contributed their text. The br element emits a single U+000A LINE FEED character at its position.¶

After the entire subtree has been walked, the resulting byte sequence is trimmed: leading and trailing runs of U+000A and U+0020 are removed, and runs of two or more U+000A in a row are collapsed to a single U+000A.¶

The result is a UTF-8 byte string.¶

4.6. Canonical claims

In-band claim metadata is carried by <meta> elements that appear as direct children of the signed section element, as required by [HTMLTRUST-W3C]. Claim <meta> elements located at greater depth do not participate.¶

Every direct child <meta> element of a signed section is a claim. A claim <meta> element MUST have both a name attribute and a content attribute. If any direct child claim <meta> is missing either attribute, verification MUST fail with "claim-malformed". If the normalized name is the empty string, verification MUST fail with "claim-malformed".¶

For each claim <meta> element:¶

1. The name attribute value is processed as plain text per Section 4.4 (NFKC, formatting strip, whitespace collapse).¶

2. The content attribute value is processed identically.¶

3. The pair is serialized as¶

   escaped-name : escaped-content \n¶

   where : is U+003A COLON and \n is U+000A LINE FEED. Escaping is applied after normalization: U+005C REVERSE SOLIDUS becomes \\, U+003A COLON becomes \:, and U+000A LINE FEED becomes \n. Normalization currently maps line feeds to spaces, but the explicit rule keeps the record grammar injective if a future normalization profile admits them.¶

The resulting name : content lines are sorted lexically by the UTF-8 byte sequence of the normalized name. Ties on name MUST NOT occur; signers MUST NOT emit two direct child claim <meta> elements whose name attributes normalize to the same value within a single signed section, and verifiers MUST fail with "claim-duplicate" if they encounter such duplicates. The concatenation of the sorted lines is the canonical claims byte string.¶

Normalized claim names are case-sensitive. Only the exact ASCII name signed-at has protocol semantics in v1. Other names, including author and names in the claim: namespace, are signed metadata whose meaning is defined outside the cryptographic verification procedure.¶

The signed-at claim is not special for purposes of the claims hash: it is included in canonical claims like every other direct child claim <meta>. Section 5 also includes the normalized signed-at value as a separate signing-payload field. This deliberate duplicate binding makes the timestamp easy for verifiers and directory indexes to extract without weakening claim integrity.¶

4.7. Opt-out marker (Editor's Note)

Editor's Note: Common runtime decorations (copy-to-clipboard buttons, client-side syntax highlighting, lazy-loaded share widgets) frequently mutate descendants of a signed section after page load. This revision addresses that problem by verifying the original server HTML snapshot in the companion W3C processing model. A future revision might add an author-controlled opt-out marker such as data-htmltrust-ignore="true", but that attribute has no normative effect in this revision. Conforming canonicalizers MUST NOT exclude a subtree solely because it carries that attribute unless operating in an explicit experimental mode.¶

5.1. Profile identifiers and wire attributes

The identifiers fixed by this profile are:¶

The identifiers are case-sensitive ASCII strings. They are protocol identifiers, not implementation version numbers.¶

A v1 signed section MUST carry the profile attribute with the exact value htmltrust-signature-v1 and the signature-scope attribute with one of the exact values url or origin, in addition to keyid, signature, content-hash, and algorithm. Leading or trailing ASCII whitespace in any of these protocol attributes is invalid. There are no default values.¶

A missing required attribute produces incomplete. An unknown profile produces profile-unsupported, and an unknown signature-scope produces scope-unsupported. A verifier MUST select the profile before canonicalization and MUST NOT retry a failed v1 verification with another profile.¶

5.2. Signed-attribute and safe-URL profiles

htmltrust-attrs-v1 contains exactly href, src, alt, and aria-label in the order specified in Section 4.3.2. Adding, removing, reordering, or changing the interpretation of a covered attribute requires a new signed-attribute profile identifier. Implementations MUST NOT extend this set while reporting htmltrust-attrs-v1.¶

For href and src, htmltrust-safe-url-v1 applies before the serialized URL is emitted into canonical content. Its input is the attribute value produced by the accepted HTML parser after input-stream preprocessing and character-reference resolution. Before passing that value to the URL Standard parser, the verifier MUST inspect every code point and reject an ASCII C0 control or U+007F. This order prevents URL preprocessing from silently stripping a tab or line feed. The value is resolved against the source snapshot's document base URL. The result MUST use the https scheme and MUST NOT contain a username or password. Query and fragment components are preserved by URL serialization. Verification does not dereference the URL. A policy violation produces url-policy-violation; a URL parse failure produces attribute-canonicalization-failed.¶

This profile therefore rejects javascript, data, blob, file, mailto, tel, custom schemes, and cleartext http in signed href and src attributes. An implementation MAY define a local-development profile, but it MUST use a different URL-policy identifier and MUST NOT be accepted as htmltrust-safe-url-v1.¶

The profile does not cover srcset, CSS URLs, event-handler attributes, or attributes outside htmltrust-attrs-v1. User interfaces MUST describe the result as verification of the covered content and attributes rather than as whole-document integrity.¶

5.3. Location scope and same-origin replay

The signed document URL is the final response URL after redirects. Public v1 signatures require a URL with an HTTPS tuple origin and no username or password. Host case folding, IDNA A-label conversion, IPv6 syntax, and default-port omission follow the URL Standard.¶

For signature-scope="url", the location is the URL Standard serialization of the signed document URL with its fragment excluded. The path and query are included. A fragment is excluded because it is not sent in an HTTP request. This scope prevents an unchanged section from verifying at a different path or query on the same origin. Authoring tools SHOULD emit url scope.¶

For signature-scope="origin", the location is the URL Standard origin serialization of the signed document URL. This value contains scheme, host, and non-default port, with no path, query, fragment, or credentials. Origin scope explicitly permits replay at another URL on the same origin. Verifiers MUST expose the accepted scope to trust policy and user-interface code so a caller can reject origin-wide signatures.¶

The document's <link rel="canonical">, Open Graph URL, document base URL, and surrounding markup do not select or alter the location. Copying a section to another origin always changes the location. www and apex hosts, CDN aliases, and distinct ports are distinct locations unless they serialize to the same origin under the URL Standard. A URL that cannot produce the required public location produces origin-not-supported.¶

5.4. Timestamp profile

Every v1 section MUST contain exactly one direct-child claim whose normalized name is the ASCII string signed-at. Its normalized content MUST be exactly 20 ASCII characters in this form:¶

YYYY-MM-DDTHH:MM:SSZ

The year is in the range 0001 through 9999. The month, day, hour, minute, and second MUST form a valid Gregorian UTC date and time. Seconds are limited to 00 through 59. Lowercase t or z, UTC offsets, fractional seconds, leap seconds, and trailing whitespace are invalid. This is a deliberately narrow profile of [RFC3339]. A violation produces timestamp-invalid.¶

signed-at is an assertion made by the signer. It proves that the timestamp was covered by the signature, but it does not prove when the signature was created. Freshness limits and future-clock-skew rules are trust-policy decisions and MUST NOT be reported as signature-invalid. A verifier that accepts a signature from a revoked key based on time needs independent evidence, such as an [RFC3161] time-stamp token, an append-only log entry, or a trusted directory first-seen record. Such evidence is evaluated outside the v1 signing payload.¶

5.5. Canonical signing object

The signer constructs this JSON object, with every member present:¶

{
  "algorithm": "ed25519",
  "attributeProfile": "htmltrust-attrs-v1",
  "canonicalizationProfile": "htmltrust-c14n-v1",
  "claimsHash": "sha256:...",
  "contentHash": "sha256:...",
  "context": "https://htmltrust.org/protocol/signed-section",
  "keyid": "https://keys.example/alice.json",
  "location": "https://example.org/article",
  "profile": "htmltrust-signature-v1",
  "scope": "url",
  "signedAt": "2026-08-27T18:00:00Z",
  "urlProfile": "htmltrust-safe-url-v1"
}

The members are defined as follows:¶

algorithm:

The exact algorithm attribute value. The value MUST be a registered algorithm identifier accepted by the verifier.¶

attributeProfile, canonicalizationProfile, profile, urlProfile:

The exact identifiers in Section 5.1. These values are constants for v1 and MUST NOT be copied from attacker-selected markup.¶

claimsHash:

The claims hash recomputed from Section 4.6 using the algorithm selected by contentHash. It is not carried as a separate HTML attribute. The content and claims hash algorithms MUST match.¶

contentHash:

The exact content-hash attribute value after its encoding has been validated as canonical under Section 6.¶

context:

The exact ASCII string https://htmltrust.org/protocol/signed-section. This member separates HTMLTrust signed-section signatures from signatures made for another protocol.¶

keyid:

The exact keyid attribute value after the protocol-attribute validation in Section 5.1. It selects one verification key under Section 8.¶

location:

The location derived by Section 5.3 from the accepted source snapshot's final response URL and the selected scope.¶

scope:

The exact signature-scope attribute value.¶

signedAt:

The normalized signed-at claim content after Section 5.4 validation.¶

The signing payload is the UTF-8 encoding of this object serialized with the JSON Canonicalization Scheme [RFC8785]. The serialized object contains no unknown or optional members in v1. The signature operation in Section 6.3 is applied directly to those bytes.¶

5.6. Algorithm and signer binding

Both algorithm and keyid are inside the signed object. Changing either attribute changes the signing payload and causes signature verification to fail. The resolved key document MUST identify a key suitable for exactly the declared algorithm; a verifier MUST NOT try other algorithms or other keys after a mismatch.¶

A public-key fingerprint is not a v1 payload member. keyid selects one verification method, and the signature already proves possession of the corresponding private key. Key rotation uses a fresh keyid under Section 9. Implementations MAY expose a derived key fingerprint for diagnostics or trust policy, but it does not replace signed keyid binding.¶

5.7. Legacy payloads

The four-field colon-joined payload used by pre-v1 prototypes is not part of htmltrust-signature-v1. An implementation MAY offer an explicitly enabled legacy verifier, but absence of profile MUST NOT trigger it automatically. A legacy success MUST be labeled separately and MUST NOT be reported as a v1 valid result. Migration consists of verifying the legacy artifact under its original rules, canonicalizing the accepted source under v1, and producing a new v1 signature. Re-encoding a legacy signature does not migrate it.¶

6.1. Encoding choice

Binary values on the wire, including hashes, signatures, and raw public keys embedded in HTMLTrust JSON documents, MUST be encoded as canonical, unpadded Base64 using the standard Base64 alphabet in Section 4 of [RFC4648]. This is not base64url: the alphabet includes + and /, and does not use - or _.¶

Producers MUST emit the shortest canonical unpadded Base64 form:¶

• no = padding characters;¶

• no whitespace;¶

• only the characters A-Z, a-z, 0-9, +, and /;¶

• zero-valued unused pad bits as required by [RFC4648].¶

Verifiers MUST reject non-canonical Base64 in signed attributes and signed JSON fields. A verifier determines canonicality by decoding the value, re-encoding the decoded bytes using the rules above, and requiring byte-for-byte equality with the original value. Implementations MAY provide an explicit legacy-tooling mode that accepts padded Base64 or base64url for migration testing, but that mode is non-conforming for normal verification and MUST be distinguishable from conforming verification in diagnostics.¶

Because standard Base64 uses + and /, HTMLTrust values placed in URL paths, query strings, or other URL components MUST be percent-encoded where required by the URL component's grammar. For example, the / character in a content hash path segment is encoded as %2F.¶

Editor's Note: Hex (familiar from git and TLS tooling) and base32 (case-insensitive and easier to transcribe) remain useful diagnostic formats, but they are not wire encodings for this revision. Ecoji [ECOJI] has been proposed; it has been rejected on wire-byte grounds (32-byte SHA-256 digest is 26 emoji = 104 UTF-8 bytes versus 43 Base64 characters) and is noted here for completeness.¶

6.2. Content hash and claims hash

A content hash or claims hash is the concatenation of:¶

1. A hash algorithm identifier from the registry in Section 7.2.¶

2. A single U+003A COLON.¶

3. The Base64-encoded, unpadded hash output.¶

For example, a SHA-256 hash of an empty string is:¶

sha256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU

Verifiers MUST reject a content hash whose algorithm identifier is not in the registry, and MUST reject a content hash whose Base64-decoded length is not the natural output length of the identified algorithm (32 bytes for sha256, 48 bytes for sha384, 64 bytes for sha512).¶

6.3. Signature

The signature attribute carries the Base64-encoded, unpadded output of the signature algorithm given by the algorithm attribute. The byte representation is fixed for each registered algorithm:¶

• For ed25519, the signature is the 64-byte Ed25519 signature defined by [RFC8032] (86 Base64 characters).¶

• For ecdsa-p256, the signature is the 64-byte R || S representation defined for ES256 by [RFC7518]. R and S are unsigned, big-endian, 32-byte integers, left-padded with zero octets when necessary.¶

• For ecdsa-p384, the signature is the 96-byte R || S representation defined for ES384 by [RFC7518]. R and S are unsigned, big-endian, 48-byte integers, left-padded with zero octets when necessary.¶

• For either RSA algorithm, the signature is the big-endian signature integer encoded in exactly the modulus width in octets, as specified by [RFC8017]. rsa-pss-sha256 uses SHA-256, MGF1 with SHA-256, and a 32-octet salt. rsa-pkcs1-sha256 uses RSASSA-PKCS1-v1_5 with SHA-256.¶

ECDSA ASN.1 DER signatures are not valid HTMLTrust signature values. Verifiers MUST reject a signature whose decoded length or representation does not match the selected algorithm before attempting verification.¶

7.1. Signature algorithms

The following identifiers are defined for use in the algorithm attribute of a signed section.¶

The mandatory-to-implement algorithm for both signers and verifiers is ed25519. A verifier MAY accept additional algorithms; a verifier MUST treat an algorithm value not in its accepted set as an "algorithm-not-supported" verification failure, not as a generic failure.¶

The resolved public key type and parameters MUST match the selected identifier exactly. In particular, an ECDSA key on another curve and a key document that names the other registered RSA padding mode are algorithm mismatches. A verifier MUST NOT infer an algorithm from key type or try multiple algorithms after a mismatch.¶

7.2. Hash algorithms

The following identifiers are defined for use in the algorithm prefix of content-hash and claims-hash.¶

The mandatory-to-implement hash algorithm is sha256. The hash algorithm used for content-hash and claims-hash within a single signed section MUST be the same.¶

7.3. Algorithm agility

A future revision of this specification MAY add identifiers via expert review (Section 15). Identifiers MUST NOT be removed once registered; an identifier MAY be marked "deprecated" with normative text recommending non-use. Verifiers SHOULD refuse to verify under a deprecated identifier and SHOULD surface the result as an "algorithm-not-supported" outcome.¶

8.1. DID method resolution

A keyid whose value begins with did: MUST be resolved per the DID Core specification [W3C.did-core] using the DID method indicated by the second URI scheme component. The DID document MUST be retrieved, and the public key MUST be selected from its verificationMethod array.¶

The verifier MUST select a verification method whose type is compatible with the algorithm attribute of the signed section. If multiple verification methods are present, the verifier MUST prefer a method whose id is referenced from the assertionMethod relationship of the DID document; if no such method exists, the verifier MAY use any verification method of compatible type.¶

DID resolution failures (DID document not found, signature on DID document invalid where the method demands one, expired or revoked verification method) MUST be reported as "key-resolution-failed" verification failures.¶

8.2. Direct HTTPS URL

A keyid whose value is an absolute URL with scheme https MUST be resolved by issuing a GET request to that URL. The response MUST have a media type of application/htmltrust-key+json (Section 15) or application/jwk+json per [RFC7517]; verifiers MAY accept application/json for backward compatibility.¶

The retrieved document MUST be one of:¶

• A JSON Web Key per [RFC7517], or¶

• An HTMLTrust key document with the following shape:¶

  {
    "kid": "<string, optional>",
    "algorithm": "<algorithm identifier>",
    "publicKeyEncoding": "spki-der",
    "publicKey": "<unpadded standard Base64 SPKI DER>",
    "expires": "<RFC3339 timestamp, optional>",
    "revoked": <boolean, optional>,
    "revokedAt": "<RFC3339 timestamp, optional>",
    "supersededBy": "<keyid, optional>",
    "previousKeys": ["<keyid>"]
  }
  

  ¶

algorithm, publicKeyEncoding, and publicKey are REQUIRED. The other members shown above are OPTIONAL. Unknown members MUST be ignored for key resolution and MAY be retained by caches or directories.¶

publicKey is the canonical unpadded standard Base64 encoding from Section 6.1 of the DER-encoded SubjectPublicKeyInfo structure defined by [RFC5280]. publicKeyEncoding MUST be exactly spki-der. A verifier MUST reject any other encoding in a conforming HTMLTrust key document with a "malformed-key-document" result. If kid is present, it MUST equal the serialized URL used as keyid; a mismatch is a "key-resolution-failed" result. The algorithm value and the decoded key type and parameters MUST match Section 7.1.¶

For an application/jwk+json response, the JWK kty, crv, and alg members, when applicable, MUST select the same key type, parameters, and algorithm. An absent alg does not authorize algorithm inference; the signed section's algorithm still selects the verification operation.¶

The verifier MUST process expires and revoked according to Section 9. Malformed timestamps, malformed Base64, an invalid SPKI structure, and missing or incorrectly typed required members are "malformed-key-document" results. A well-formed key whose type, curve, or declared algorithm does not match the signed section produces "algorithm-mismatch". A conforming verifier MUST NOT use a PEM compatibility field or silently try a different key encoding.¶

8.3. Trust directory reference

A keyid whose value is an absolute URL pointing at a trust directory's /keys/{id} endpoint (Section 10.6) MUST be resolved by issuing a GET request to that URL. The response format is identical to Section 8.2.¶

The verifier SHOULD consider the trustworthiness of the directory itself before accepting a key resolved this way; directory-based identity centralizes a portion of the trust graph in the directory operator.¶

8.4. Acceptance policy

A verifier MUST permit configuration of which key-resolution methods it accepts and SHOULD default to accepting all three. The verifier MUST NOT privilege any one method over another within its accepted set; selection is determined by the keyid value, not by the verifier.¶

9.1. Key states

A published key is in exactly one of four states from a verifier's perspective:¶

• active -- neither expired nor revoked; usable for verification.¶

• expired -- the key document carries an expires timestamp in the past. The key was retired on schedule. Signatures whose bound signed-at is at or before expires remain cryptographically valid and SHOULD be accepted subject to trust policy; a verifier MUST fail with "key-revoked" if it cannot establish that the signature predates expiry.¶

• revoked -- the key document carries revoked: true. Revocation signals suspected or confirmed key compromise. See Revocation, compromise, and signed-at freshness, below.¶

• superseded -- the key is expired and the publisher has designated a successor (see Rotation and supersession, below). This is the normal rotation end-state.¶

9.2. Rotation and supersession

Publishers SHOULD rotate signing keys periodically. To rotate without invalidating existing content, a publisher:¶

1. Publishes a new key at a fresh keyid and begins signing new content with it.¶

2. Sets an expires timestamp on the old key document at or after the time it stopped signing with that key, and keeps the old key document resolvable so historical signatures continue to verify.¶

3. MAY add a supersededBy field to the old key document whose value is the successor keyid, and a previousKeys array to the new key document listing prior keyids. These fields let a verifier or directory reconstruct an author's key history and attribute an author's older content to the same identity across a rotation.¶

A verifier MUST NOT treat an expired-but-superseded key as a "key-revoked" failure for signatures whose signed-at precedes the expires time; expiry alone is orderly rotation, not compromise.¶

9.3. Revocation, compromise, and signed-at freshness

signed-at (Section 5) is asserted by the signer and, absent an external timestamp authority, can be backdated by whoever holds the private key. This has a direct consequence for compromise handling: a holder of a stolen key can produce signatures bearing any signed-at value, including one predating the compromise. Therefore:¶

• A revoked key document SHOULD carry a revokedAt RFC 3339 timestamp indicating when compromise is believed to have begun.¶

• A conservative verifier MUST treat every signature from a revoked key as untrusted, regardless of its signed-at, because the timestamp is not independently attestable. This is the safe default.¶

• A verifier MAY accept a signature from a revoked key whose signed-at precedes revokedAt ONLY when the signature's timing is corroborated by evidence the verifier trusts and that the key holder could not forge -- for example an [RFC3161] time-stamp token, inclusion in an append-only transparency log, or a directory's first-seen record established before revokedAt. In the absence of such evidence, revocation is all-or-nothing.¶

Verifiers MAY additionally apply a freshness policy that rejects signed-at values implausibly far in the past or future relative to the time of retrieval; such a policy is a trust-layer decision (out of scope for cryptographic verification) and is not part of signature verification.¶

9.4. Key loss and recovery

There is no cryptographic recovery from loss of a signing key: the private key is the identity. A publisher that loses a key (without compromise) SHOULD mark it expired, publish a successor (see Rotation and supersession), and rely on the out-of-band binding between keyid and publisher (the did:web/HTTPS origin, or directory registration and endorsements) to re-establish continuity of identity. Publishers SHOULD therefore keep signing keys recoverable from secure backups precisely because the protocol offers no in-band recovery. Directories and endorsers MAY vouch for a successor key's continuity with the prior identity, but such vouching is a trust-layer signal, not a cryptographic guarantee.¶

10.1. Base URL and discovery

A directory MUST be reachable at an https-scheme base URL. The endpoints below are relative to that base URL.¶

A directory SHOULD also expose a discovery document at the well-known URI [RFC8615] /.well-known/htmltrust (Section 10.2).¶

10.2. GET /.well-known/htmltrust

Returns a JSON metadata document describing the directory's capabilities. The response media type is application/htmltrust-directory+json (provisional; see Section 15).¶

{
  "directory": "https://directory.example/",
  "version": "1",
  "capabilities": {
    "content": true,
    "endorsements": true,
    "keys": true,
    "reputation": true
  },
  "supportedAlgorithms": {
    "signature": ["ed25519", "ecdsa-p256"],
    "hash": ["sha256", "sha384"]
  },
  "supportedProfiles": ["htmltrust-signature-v1"],
  "contact": "operator@directory.example",
  "termsOfService": "https://directory.example/tos"
}

The fields directory, version, capabilities, supportedAlgorithms, and supportedProfiles are REQUIRED. Other fields are OPTIONAL.¶

10.3. GET /content/{hash}

Retrieves the directory's record for a specific content hash. The path parameter is the content hash including the algorithm prefix, percent-encoded as a single path segment (the colon becomes %3A; any / in the Base64 value becomes %2F).¶

A successful response is JSON of the form:¶

{
  "contentHash": "sha256:Zm9vYmFy...",
  "firstSeen": "2026-05-15T12:34:56Z",
  "signers": [
    {
      "profile": "htmltrust-signature-v1",
      "keyid": "did:web:author.example#key-1",
      "algorithm": "ed25519",
      "signedAt": "2026-05-01T10:30:00Z",
      "scope": "url",
      "location": "https://author.example/posts/123",
      "signature": "3q2+7w8NslfJ..."
    }
  ],
  "endorsementCount": 3
}

A directory that does not have a record for the requested hash MUST return 404 Not Found.¶

10.4. POST /content

Submits a record of a signed content occurrence for indexing. The request body is JSON of the form:¶

{
  "profile": "htmltrust-signature-v1",
  "contentHash": "sha256:Zm9vYmFy...",
  "keyid": "did:web:author.example#key-1",
  "algorithm": "ed25519",
  "signedAt": "2026-05-01T10:30:00Z",
  "scope": "url",
  "location": "https://author.example/posts/123",
  "signature": "3q2+7w8NslfJ...",
  "sourceURL": "https://author.example/posts/123",
  "claims": [
    {"name": "author", "content": "Alice Example"},
    {"name": "claim:License", "content": "CC-BY-4.0"},
    {"name": "signed-at", "content": "2026-05-01T10:30:00Z"}
  ]
}

The submission MUST be authenticated by an HTTP Message Signature [RFC9421] from a key the directory can resolve. The directory MUST re-verify the submitted signature against the canonical signing payload (Section 5) before indexing.¶

The profile, algorithm, keyid, scope, location, contentHash, signedAt, and signature members are REQUIRED. sourceURL is the observed occurrence URL. The directory MUST derive a location from sourceURL under the submitted scope and require it to equal location. A directory MUST NOT derive the signed location from canonical-link metadata.¶

The claims array MUST contain the complete set of direct-child claim records used by the signer, including exactly one signed-at record. Each array member MUST contain exactly one string name and one string content. The directory MUST normalize, escape, detect duplicates, sort, and serialize these records exactly as specified in Section 4.6. It MUST derive the claims hash with the hash algorithm selected by contentHash, and it MUST require the normalized signed-at claim value to equal signedAt. A missing, extra, malformed, or duplicate claim causes the submission to fail. The directory MUST use this recomputed claims hash when constructing the Section 5 signing payload; it MUST NOT insert a missing claim or accept a client-supplied claims hash in its place.¶

Successful submission returns 201 Created with a Location header pointing at the resulting /content/{hash} URL. Rejected submissions return 4xx codes per Section 10.9.¶

10.5. GET /content/{hash}/endorsements

Lists endorsements stored for a given content hash. The response is a JSON array of endorsement documents (Section 11), each independently verifiable by the requester. The directory MUST NOT alter the endorsement payloads in a manner that invalidates the endorser's signature.¶

Pagination, if supported, MUST follow the Web Linking conventions of [RFC9110] using Link headers with rel="next".¶

10.6. POST /endorsements

Submits a signed endorsement document (Section 11). The directory MUST:¶

1. Verify the endorser's signature on the endorsement.¶

2. Verify that the endorsement's endorsement field references a content hash for which the directory has a record (or accept new content hashes; this is a directory policy choice).¶

3. Index the endorsement under the content hash for retrieval via Section 10.5.¶

Successful submission returns 201 Created. Endorsements with invalid signatures MUST be rejected with 400 Bad Request.¶

10.7. GET /keys/{id}

Retrieves a public key document for the given directory-issued key identifier. The response is a key document conforming to Section 8.2.¶

Directories that act as convenience registries for less-technical signers expose keys through this endpoint, and signers reference such keys by setting keyid to the full URL of the endpoint, for example https://directory.example/keys/k-abc123.¶

10.8. GET /signers/{id}/reputation

Returns a directory-computed reputation score for a signer. The response is JSON of the form:¶

{
  "keyid": "did:web:author.example",
  "score": 0.72,
  "asOf": "2026-05-15T00:00:00Z",
  "components": ["endorsements", "history", "verified-domain"],
  "methodology": "https://directory.example/methodology"
}

The score is a directory-specific value with no protocol-level semantics; verifiers consume scores from directories that they have been explicitly configured to trust. Different directories MAY produce different scores for the same signer.¶

10.9. Authentication

POST endpoints MUST be authenticated using HTTP Message Signatures [RFC9421] with a key that the directory can resolve via Section 8. The signature input MUST be an RFC 9421 structured field. A conforming directory MUST accept the sig1 label only when its covered-component identifier list includes, in this order, @method, @target-uri, host, date, and content-digest. The legacy (request-target) identifier is an earlier HTTP Signatures convention and MUST NOT be used in a conforming HTMLTrust signature. The @target-uri value MUST be the absolute request target, and host and date MUST be the received HTTP fields. content-digest MUST use the representation from [RFC9530] and MUST cover the exact UTF-8 request body bytes. The signature parameters MUST include created, keyid, and alg; created MUST be within the directory's configured clock-skew window and implementations SHOULD include a nonce to prevent replay of otherwise valid requests.¶

The alg parameter identifies the HTTP Message Signature algorithm profile. For this revision, ed25519 means an Ed25519 signature over the RFC 9421 signature base, encoded as unpadded standard Base64. It is independent of the HTMLTrust signed-section algorithm field. A directory MUST reject a request whose signature base, body digest, or freshness checks do not verify; API keys MAY be offered as a separately documented deployment convenience, but are not a conforming substitute for this authentication profile.¶

GET endpoints SHOULD be accessible without authentication to support public verification. A directory MAY require authentication for specific endpoints subject to its operational policy; in that case unauthenticated requests MUST receive 401 Unauthorized with a WWW-Authenticate header.¶

10.10. Errors

The directory MUST return errors using the problem-details format defined in [RFC9457] (which obsoletes RFC 7807), with media type application/problem+json:¶

{
  "type": "https://htmltrust.org/errors/signature-invalid",
  "title": "Signature verification failed",
  "status": 400,
  "detail": "The submitted signature did not verify against the
  canonical signing payload.",
  "contentHash": "sha256:..."
}

Directories SHOULD apply rate limits per IP, per submitter key, and per content hash, and SHOULD signal exhaustion with 429 Too Many Requests and a Retry-After header.¶

11.1. Document shape

The endorsement document is a JSON object with the following fields.¶

Additional fields MAY be present and SHOULD be preserved by directories. Verifiers MUST ignore fields they do not recognize for purposes of trust decisions, but MUST include them when computing the signed payload (Section 11.2) so that signature verification succeeds.¶

11.2. Canonicalization for signing

The signing payload for an endorsement is the JSON Canonicalization Scheme [RFC8785] serialization of the endorsement document with the signature field omitted. The endorser signs that byte string using the algorithm given by algorithm. Verifiers reproduce the same serialization, omit signature, and verify using the endorser's resolved public key.¶

JSON Canonicalization Scheme is chosen because it is purpose-built for signed JSON, is widely implemented, and avoids the parser- divergence problems that have historically plagued ad-hoc JSON canonicalization. Implementations MUST implement RFC 8785 rather than an object-key sorter layered on the host language's ordinary JSON serializer. In particular, they MUST use RFC 8785's UTF-16 property-name ordering, ECMAScript-compatible number serialization, JSON string serialization rules, and no insignificant whitespace. This includes the required escaping of control characters and rejection of lone UTF-16 surrogate code units. JSON parsers MUST reject duplicate member names before JCS serialization; accepting the last duplicate member is non-conforming. Values that JSON cannot represent under RFC 8259, including NaN and Infinity, MUST be rejected. The signature member is omitted only at the signing step; all other members, including optional and implementation-extension members, remain in the JCS input. A verifier MUST preserve and include unknown members rather than silently dropping them.¶

11.3. Revocation and expiry

An endorsement with an expires value in the past MUST be treated by verifiers as invalid for purposes of any current trust decision. An endorsement with a revokedBy value MUST be treated as superseded; the verifier MAY retrieve the superseding endorsement from the same directory and apply its semantics in place.¶

An endorser MAY publish a revocation endorsement (an endorsement whose claim field names the revoked endorsement's hash and whose revokedBy field references the document being revoked). A directory that holds both MUST serve both in response to GET /content/{hash}/endorsements so that verifiers can observe the revocation chain.¶

11.4. Endorsement of an endorsement

Endorsement documents are themselves content. An endorser MAY in turn endorse another endorser's document by computing the content hash of the endorsement (as canonicalized in Section 11.2) and issuing a new endorsement against that hash. This provides a mechanism for chained reputation without protocol-level signer endorsements.¶

12.1. Step 1: Extract attributes and content

Obtain an accepted source representation under Section 4.1 and validate the portable parser profile before extracting the section. If source cannot be obtained, return "source-refetch-failed". If the source or parser diagnostics cannot establish the portable profile, return "parser-profile-unsupported". If a Section 12.10 resource ceiling is reached, return "resource-limit-exceeded". Stop after any of these failures.¶

Obtain the six required attributes profile, signature-scope, keyid, signature, content-hash, and algorithm, plus the inner content of the signed section. If any required attribute is missing or empty, or if a protocol attribute has leading or trailing ASCII whitespace, the verifier MUST return incomplete and stop.¶

Require profile to equal htmltrust-signature-v1; otherwise return profile-unsupported. Require signature-scope to equal url or origin; otherwise return scope-unsupported. Select the profile before performing canonicalization and do not try a different profile after a later failure.¶

Validate the content-hash and signature encodings against Section 6. A non-canonical Base64 value, an invalid hash shape, or a decoded hash with the wrong natural output length produces "invalid-encoding". If the signature or hash algorithm is not registered or is outside the verifier's accepted set, return "algorithm-not-supported". For Ed25519 and ECDSA, a decoded signature whose length or representation does not match Section 6.3 produces "malformed-signature". RSA signature length is checked after key resolution in Step 6.¶

12.2. Step 2: Canonicalize content; compute and compare content hash

Apply the canonicalization algorithm of Section 4 to the inner content. Compute the hash using the algorithm given by the prefix of the content-hash attribute. Compare the computed hash to the attribute value (excluding the prefix and separator, after Base64 decoding).¶

If URL resolution or another signed-attribute operation cannot produce the canonical value required by Section 4.3.2, the verifier MUST return attribute-canonicalization-failed and stop. If a resolved href or src violates htmltrust-safe-url-v1, return url-policy-violation and stop.¶

If the hashes do not match, the verifier MUST return a "content-hash-mismatch" failure and stop.¶

12.3. Step 3: Canonicalize claims; compute claims hash

Apply Section 4.6 to the claim <meta> element children of the signed section. Compute the hash using the same algorithm as Step 2. Form the claims-hash string per Section 6.2.¶

A missing name or content, or an empty normalized name, produces "claim-malformed". Duplicate normalized names produce "claim-duplicate".¶

Require exactly one normalized claim name equal to signed-at. If it is absent, return claim-missing. Validate its normalized content against Section 5.4; a failure produces timestamp-invalid.¶

12.4. Step 4: Construct signing payload

Derive location from the accepted source snapshot's final response URL and the signature-scope attribute under Section 5.3. If the document URL does not produce an allowed public v1 location, return origin-not-supported.¶

Construct the complete object in Section 5.5 from the validated attributes, the claims hash from Step 3, the derived location, and the normalized signed-at value. Insert the four profile constants from Section 5.1 and the fixed context string. Serialize the object with [RFC8785], then UTF-8 encode the result. Those bytes are the signing payload.¶

A section copied to a location outside its signed scope produces signature-invalid because the verifier constructs a different signed object. The verifier MUST NOT use author-controlled canonical-link metadata as the location.¶

12.5. Step 5: Resolve keyid

Resolve the keyid attribute per Section 8 to obtain a public key and the algorithm it is suitable for. A retrieval or DID-resolution failure produces "key-resolution-failed". A key response that violates the required document schema produces "malformed-key-document". A revoked key, or an expired key that Section 9 does not permit for this signature, produces "key-revoked". The verifier MUST stop after any of these results.¶

If the algorithm associated with the resolved key is incompatible with the algorithm attribute of the signed section, the verifier MUST return an "algorithm-mismatch" failure and stop.¶

12.6. Step 6: Verify signature

Verify the Base64-decoded signature against the signing payload from Step 4 using the public key from Step 5 and the algorithm given by the algorithm attribute. Before RSA verification, require the decoded signature to be exactly the resolved modulus width; otherwise return "malformed-signature". If the cryptographic operation completes and the signature does not verify, return "signature-invalid". The verifier MUST stop after either failure.¶

If the verification succeeds, the verifier MUST return a "valid" cryptographic outcome.¶

12.7. Step 7: Trust decision (out of scope)

The verifier returns the cryptographic outcome to the trust-decision layer (in browsers, the user agent's trust policy; see [HTMLTRUST-W3C]). The trust layer composes endorsement, reputation, and personal-trust-list inputs and MUST NOT alter the cryptographic outcome.¶

12.8. Failure outcomes

The following identifiers are the closed failure vocabulary for this revision. A verifier MAY attach private diagnostic detail, but the cryptographic result MUST use one of these identifiers and MUST never map a listed failure to valid:¶

incomplete, profile-unsupported, scope-unsupported, content-hash-mismatch, claim-missing, claim-malformed, claim-duplicate, timestamp-invalid, attribute-canonicalization-failed, parser-profile-unsupported, url-policy-violation, invalid-encoding, malformed-signature, signature-invalid, key-resolution-failed, malformed-key-document, key-revoked, algorithm-not-supported, algorithm-mismatch, origin-not-supported, resource-limit-exceeded, network-policy-blocked, source-refetch-failed, and directory-unavailable.¶

Failures that occur before a key is resolved MUST NOT trigger signature verification. Network and resource failures MUST NOT be retried without the same finite limits. User-agent integrations MUST expose at most the identifier and a privacy-safe explanation to page scripts.¶

directory-unavailable is reserved for an optional trust-directory consultation in the layer-2 processing model. A layer-1 cryptographic result MUST NOT use that identifier, and directory failure MUST NOT change a valid cryptographic result into an invalid one.¶

12.9. Verifier network fetch policy

This section defines a provisional network model for verifier-initiated fetches. It is expected to be refined as browser, extension, and native verifier implementations mature.¶

Remote key documents and trust-directory endpoints MUST be fetched over HTTPS URLs. Verifiers MUST NOT send cookies, HTTP authentication state, client certificates, or other ambient credentials on key or directory fetches by default. A browser verifier MAY send credentials only for a same-origin source refetch of the document being verified, and only when that refetch is needed to obtain the original server HTML for the [HTMLTRUST-W3C] processing model.¶

Verifier fetches SHOULD send no Referer header. If a platform cannot omit the header, it MUST trim it no less strictly than strict-origin-when-cross-origin.¶

Web-page JavaScript verifiers are subject to the Fetch CORS model and therefore require key and directory servers to opt in with appropriate CORS response headers. Browser extensions, native user agents, crawlers, and command-line verifiers MAY have broader network authority, but they SHOULD apply the same credential, referrer, redirect, timeout, and cache constraints for privacy and interoperability.¶

Verifiers MAY follow HTTPS-to-HTTPS redirects for key and directory fetches subject to a small implementation-defined limit. They MUST NOT follow redirects to non-HTTPS URLs. They SHOULD impose finite timeouts, SHOULD honor HTTP cache semantics [RFC9111], and SHOULD cap cached key freshness when no explicit freshness information is present.¶

Browser verifiers that fetch through the page's fetch context MUST account for service-worker interception. A service worker on the publisher origin MAY intercept a same-origin source refetch; service workers on unrelated origins MUST NOT be allowed to intercept key or directory fetches outside their normal scope. User agents that provide a privileged verification path SHOULD bypass page script and extension mutation when preserving the original response snapshot.¶

Trust-directory consultation MUST be user opt-in. If a directory fetch, key fetch, source refetch, CORS check, redirect policy, timeout, cache validation, or user-permission check fails, the verifier MUST surface a specific failure outcome such as "key-resolution-failed", "directory-unavailable", "source-refetch-failed", or "network-policy-blocked" rather than treating the content as valid.¶

12.10. Resource limits

Verifiers MUST apply finite resource limits before parsing or fetching untrusted input. The following limits are the interoperable baseline for this revision; an implementation MAY choose lower values, but MUST NOT silently continue beyond them:¶

The limits apply independently to source verification, key resolution, and optional directory consultation. A verifier that reaches a limit MUST stop the affected operation, MUST NOT return a valid cryptographic result, and MUST report the machine-readable failure resource-limit-exceeded. It MUST NOT expose the rejected input or canonical bytes to page scripts. An implementation MAY expose the precise limit to privileged diagnostics.¶

13.1. Threat model

This document considers the following adversaries.¶

Passive eavesdropper:

An adversary observing traffic on the network. Out of scope; this threat is addressed by TLS [RFC8446], on which HTMLTrust cryptographic verification does not directly depend.¶

Active rewriter:

An adversary capable of modifying HTML in transit or at a non- origin endpoint. HTMLTrust detects any modification of canonical text or signed semantic attributes inside a signed section. It does not detect modifications to surrounding markup or to non-signed regions; verifiers and trust policies MUST present cryptographic outcomes per signed section, not per document.¶

Origin compromise:

An adversary in control of the publisher origin. Such an adversary can serve content under an origin that the signer's binding permits. Detection requires the signer to publish content hashes to a trust directory or other independent index; the protocol does not prevent the attack in isolation.¶

Key compromise:

An adversary in possession of a signer's private key. HTMLTrust cannot prevent forgery in this case. Mitigations are revocation (Section 8.2, revoked field) and short-lived keys with expires.¶

Replay across origins:

An adversary copying a signed section from one site to another. Both v1 scopes bind an HTTPS tuple origin, so verification on another origin fails.¶

Replay within origin:

An adversary re-publishing signed content at another URL on the same origin. The recommended url scope prevents this by binding the serialized path and query. origin scope permits it as an explicit portability choice; verifiers surface that scope to trust and user-interface policy. A copied section can still be surrounded by hostile unsigned context at its original URL, so scope binding does not establish whole-page integrity.¶

Downgrade:

An adversary inducing a verifier to use a weak algorithm. Mitigated by signing the exact algorithm, key identifier, and profile identifiers, and by the verifier's right to refuse algorithms (Section 7.3). A verifier never retries under a legacy profile after a v1 failure.¶

13.2. Deliberate semantic-subset signing trade-off

This revision signs canonical text plus a small list of semantic attributes (href, src, alt, and aria-label). An adversary in possession of signed material MAY still rewrap it in misleading block-level markup, alter non-covered attributes, or surround it with hostile media without invalidating the cryptographic signature. The HTMLTrust system addresses these residual risks through layered means:¶

• Location binding (Section 5) restricts the signed material to one URL by default, or to one origin after an explicit signer choice.¶

• Trust-directory indexing and external research (out of band, but enabled by the content hash being globally addressable) catches altered surrounding context on mirror sites.¶

• Future revisions MAY define a new signed-attribute profile with broader coverage, addressing a larger subset of context-swapping attacks.¶

The deliberate trade-off is implementational simplicity and cross-implementation stability versus full structural integrity. XML Digital Signatures [XMLDSIG] is the canonical cautionary tale for the latter end of that spectrum.¶

13.3. Claim metadata normalization and duplicate binding

All direct child claim <meta> elements participate in the claims hash. This prevents a metadata sanitizer from silently dropping, reordering, or renaming visible author claims without invalidating the signature, but it also means that sanitizers which remove unknown <meta> elements inside a signed section will break verification. Authoring tools SHOULD place only claims that they intend to sign as direct child <meta> elements and SHOULD keep unrelated machine metadata outside the signed section.¶

The signed-at value is intentionally included twice: once as a normal claim inside the claims hash and once as an explicit signing-payload field. The duplicate binding is not ambiguous because both uses consume the same normalized direct child claim. If the claim is missing, malformed, or duplicated after name normalization, verification fails before signature verification. This keeps timestamp extraction simple for directories and user interfaces while preserving the integrity of the complete claim set.¶

13.4. Revocation latency

Revocation under Section 8.2 depends on the verifier re-fetching the key document. Verifiers cache key documents subject to HTTP cache semantics [RFC9111]; an aggressive cache may serve stale key data after a revoked: true update. Verifiers SHOULD set a relatively short maximum cache age for HTMLTrust key documents (recommended: one hour) and SHOULD honor Cache-Control: no-cache directives from the key-document server.¶

13.5. Algorithm agility risks

The registry in Section 7 is designed to permit new algorithms without breaking deployed verifiers. However, a verifier that accepts the union of all registered algorithms inherits the security of the weakest. Verifiers SHOULD limit their accepted-algorithm set to those required by their threat model and SHOULD log or surface verifications performed under deprecated algorithms.¶

13.6. Side channels

A verifier MUST NOT distinguish verification failure from verification success via observable side channels (timing, network-request differences, console output visible to page scripts). The user-agent processing model in [HTMLTRUST-W3C] specifies the channel through which verification outcomes are exposed; verifiers in non-browser contexts SHOULD follow analogous discipline.¶

14.1. Directory query exposure

Trust-directory queries during endorsement retrieval or reputation lookup reveal the requesting verifier's IP address, request headers, and the content hashes it is interested in. A directory operator that logs queries can derive a fingerprint of the verifier's reading patterns.¶

Mitigations:¶

• Verifiers SHOULD cache directory responses (subject to [RFC9111]) to reduce repeated identical queries.¶

• Verifiers MAY batch endorsement requests for multiple content hashes encountered in the same document.¶

• Verifiers SHOULD support a "no directory" mode that limits the verifier to local cryptographic verification only.¶

• Verifiers MAY use HTTP via Tor or another anonymizing transport for directory queries; directories SHOULD accept anonymized traffic.¶

14.2. Key resolution exposure

Resolving a keyid via the methods of Section 8 reveals the verifier's interest to the key-hosting server. For directory-hosted keys, this collapses into Section 14.1. For DID and direct-URL methods, the exposure is to the signer's chosen identity host.¶

Signers SHOULD NOT publish key documents from origins that would draw inferences from key-fetch traffic that would otherwise be unavailable.¶

14.3. Endorsement disclosure

An endorsement is intentionally public. Endorsers who do not wish their endorsement to be public-facing MUST NOT submit it to a public directory; the protocol does not provide a private- endorsement mechanism.¶

15.1. Media types

The following media types are to be registered in the "Media Types" registry.¶

15.2. Well-known URI

The suffix htmltrust is to be registered in the "Well-Known URIs" registry per [RFC8615].¶

• URI suffix: htmltrust¶

• Change controller: IETF¶

• Specification document: this document, Section 10.2¶

• Related information: identifies trust directory discovery metadata¶

15.3. Signature algorithm registry

IANA is requested to establish a new registry titled "HTMLTrust Signature Algorithms" under a new "HTMLTrust Parameters" group. The registry is policy "Specification Required" per [RFC8126]; the initial contents are those of Section 7.1.¶

Each registration MUST include:¶

• Identifier (the string used in the algorithm attribute)¶

• Algorithm description¶

• Reference¶

• Status: "current" or "deprecated"¶

15.4. Hash algorithm registry

IANA is requested to establish a new registry titled "HTMLTrust Hash Algorithms" under the "HTMLTrust Parameters" group. The registry is policy "Specification Required". The initial contents are those of Section 7.2.¶

Each registration MUST include:¶

• Identifier (the string used as the hash prefix in content-hash values)¶

• Algorithm description¶

• Output length in bytes¶

• Reference¶

• Status: "current" or "deprecated"¶

15.5. HTMLTrust error type prefix

This document does not request an IANA registry for the https://htmltrust.org/errors/... URIs used in problem-details responses (Section 10.9); those URIs are stewarded by the document author and the Community Group.¶

16.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC3339]

Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, <https://www.rfc-editor.org/rfc/rfc3339>.

[RFC4648]

Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/rfc/rfc4648>.

[RFC5280]

Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, <https://www.rfc-editor.org/rfc/rfc5280>.

[RFC6454]

Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, December 2011, <https://www.rfc-editor.org/rfc/rfc6454>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/rfc/rfc7515>.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/rfc/rfc7517>.

[RFC7518]

Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, <https://www.rfc-editor.org/rfc/rfc7518>.

[RFC8017]

Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, "PKCS #1: RSA Cryptography Specifications Version 2.2", RFC 8017, DOI 10.17487/RFC8017, November 2016, <https://www.rfc-editor.org/rfc/rfc8017>.

[RFC8032]

Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017, <https://www.rfc-editor.org/rfc/rfc8032>.

[RFC8126]

Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/rfc/rfc8126>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8615]

Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, <https://www.rfc-editor.org/rfc/rfc8615>.

[RFC8785]

Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, June 2020, <https://www.rfc-editor.org/rfc/rfc8785>.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/rfc/rfc9110>.

[RFC9111]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, <https://www.rfc-editor.org/rfc/rfc9111>.

[RFC9421]

Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP Message Signatures", RFC 9421, DOI 10.17487/RFC9421, February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.

[RFC9457]

Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, <https://www.rfc-editor.org/rfc/rfc9457>.

[RFC9530]

Polli, R. and L. Pardue, "Digest Fields", RFC 9530, DOI 10.17487/RFC9530, February 2024, <https://www.rfc-editor.org/rfc/rfc9530>.

[UNICODE-NFC]

The Unicode Consortium, "Unicode Standard Annex #15: Unicode Normalization Forms", 2023, <https://www.unicode.org/reports/tr15/>.

[W3C.did-core]

W3C, "Decentralized Identifiers (DIDs) v1.0", 2022, <https://www.w3.org/TR/did-core/>.

16.2. Informative References

[AI-CONTENT-DISCLOSURE]

W3C AI Content Disclosure Community Group, "AI Content Disclosure Community Group", 2024, <https://www.w3.org/community/ai-content-disclosure/>.

[ANTIFRAUD-CG]

W3C Anti-Fraud Community Group, "Anti-Fraud Community Group", 2024, <https://www.w3.org/community/antifraud/>.

[C2PA]

Coalition for Content Provenance and Authenticity, "C2PA Technical Specification 2.0", 2024, <https://c2pa.org/specifications/specifications/2.0/specs/C2PA_Specification.html>.

[CREDENTIALS-CG]

W3C Credentials Community Group, "Credentials Community Group", 2024, <https://www.w3.org/community/credentials/>.

[CREDIBLE-WEB]

W3C Credible Web Community Group, "Credible Web Community Group", 2024, <https://credweb.org/>.

[DEFACTO]

W3C DeFacto Community Group, "Decentralized Fact-checking and Provenance Organization (DeFacto) Community Group", 2024, <https://www.w3.org/community/defacto/>.

[ECOJI]

Turner, K., "Ecoji: A base-1024 encoding using emoji", 2018, <https://github.com/keith-turner/ecoji>.

[HTMLTRUST-W3C]

Grey, J., "HTMLTrust: Signed Sections for the Web (W3C Community Group Report)", 2026, <https://htmltrust.org/spec/>.

[ORIGINATOR-PROFILE]

"Originator Profile", 2024, <https://originator-profile.org/>.

[RFC3161]

Adams, C., Cain, P., Pinkas, D., and R. Zuccherato, "Internet X.509 Public Key Infrastructure Time-Stamp Protocol (TSP)", RFC 3161, DOI 10.17487/RFC3161, August 2001, <https://www.rfc-editor.org/rfc/rfc3161>.

[RFC6376]

Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., "DomainKeys Identified Mail (DKIM) Signatures", STD 76, RFC 6376, DOI 10.17487/RFC6376, September 2011, <https://www.rfc-editor.org/rfc/rfc6376>.

[RFC8446]

Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/rfc/rfc8446>.

[SRI]

W3C, "Subresource Integrity", 2023, <https://www.w3.org/TR/SRI/>.

[SXG]

Yasskin, J., "Signed HTTP Exchanges", 2024, <https://datatracker.ietf.org/doc/draft-yasskin-http-origin-signed-responses/>.

[XMLDSIG]

W3C, "XML Signature Syntax and Processing Version 2.0", 2015, <https://www.w3.org/TR/xmldsig-core2/>.

B.1. Test key (Ed25519)

The 32-byte private seed is the ASCII string htmltrust-test-vector-ed25519-01:¶

seed (hex):       68746d6c74727573742d746573742d766563746f722d656432353531392d3031
public key (hex): ae8e474e7921dd51be650dcf6847ab452dee63421339efc3d6b041b2e85f4c19

Public key (SubjectPublicKeyInfo, PEM):¶

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAro5HTnkh3VG+ZQ3PaEerRS3uY0ITOe/D1rBBsuhfTBk=
-----END PUBLIC KEY-----

B.2. Inputs

Final signed document URL: HTTPS://EXAMPLE.COM:443/essays/engines#analysis. The url scope excludes the fragment and produces the signed location https://example.com/essays/engines. The source snapshot's document base URL for resolving relative signed URL attributes is the same URL without the fragment. signed-at is 2026-01-15T12:00:00Z.¶

Signed section (source HTML):¶

<signed-section profile="htmltrust-signature-v1"
                signature-scope="url"
                keyid="https://keys.example/alice-2026.json"
                algorithm="ed25519"
                content-hash="sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8"
                signature="m0ykSPqUWdyZprUAqosOB2IEK2XsKp7auPIWz80/2ht+LwT1LiNcsLL6cn2IkmTZFG9ptLiUHaB1crPJgBw7BA">
<meta name="author" content="Ada Lovelace">
<meta name="signed-at" content="2026-01-15T12:00:00Z">
<meta name="claim:License" content="CC-BY-4.0">
<h1>On Analytical Engines</h1>
<p>The engine weaves algebraic patterns &mdash; just as the loom weaves flowers.</p>
<p>See <a href="/notes/engine">the notes</a> and <img src="/img/ada.png" alt="Portrait of Ada">.</p>
</signed-section>

B.3. Canonical content

The three claim <meta> elements are excluded from content (they contribute to the claims). — decodes and normalizes to -; the relative href/src values resolve against the base URL and serialize with the Web URL serializer. Canonical content (UTF-8, U+000A shown as literal line breaks):¶

On Analytical Engines
The engine weaves algebraic patterns - just as the loom weaves flowers.
See @attr:a:href:https://example.com/notes/engine
the notes and @attr:img:src:https://example.com/img/ada.png
@attr:img:alt:Portrait of Ada
.

Content hash:¶

sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8

B.4. Canonical claims

Sorted lexically by the UTF-8 bytes of the normalized name:¶

author:Ada Lovelace
claim\:License:CC-BY-4.0
signed-at:2026-01-15T12\:00\:00Z

(The serialized string ends with a trailing U+000A after the last record.) Claims hash:¶

sha256:Fk5udwCnu1au8v5oaBsU+aSB5S2zSLqoF0xXO6HrIn4

B.5. Signing payload and signature

Signing object before JCS serialization:¶

{
  "algorithm": "ed25519",
  "attributeProfile": "htmltrust-attrs-v1",
  "canonicalizationProfile": "htmltrust-c14n-v1",
  "claimsHash": "sha256:Fk5udwCnu1au8v5oaBsU+aSB5S2zSLqoF0xXO6HrIn4",
  "contentHash": "sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8",
  "context": "https://htmltrust.org/protocol/signed-section",
  "keyid": "https://keys.example/alice-2026.json",
  "location": "https://example.com/essays/engines",
  "profile": "htmltrust-signature-v1",
  "scope": "url",
  "signedAt": "2026-01-15T12:00:00Z",
  "urlProfile": "htmltrust-safe-url-v1"
}

JCS signing payload, shown on one line:¶

{"algorithm":"ed25519","attributeProfile":"htmltrust-attrs-v1","canonicalizationProfile":"htmltrust-c14n-v1","claimsHash":"sha256:Fk5udwCnu1au8v5oaBsU+aSB5S2zSLqoF0xXO6HrIn4","contentHash":"sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8","context":"https://htmltrust.org/protocol/signed-section","keyid":"https://keys.example/alice-2026.json","location":"https://example.com/essays/engines","profile":"htmltrust-signature-v1","scope":"url","signedAt":"2026-01-15T12:00:00Z","urlProfile":"htmltrust-safe-url-v1"}

Ed25519 signature over that payload, unpadded standard Base64:¶

m0ykSPqUWdyZprUAqosOB2IEK2XsKp7auPIWz80/2ht+LwT1LiNcsLL6cn2IkmTZFG9ptLiUHaB1crPJgBw7BA

C.1. Submitting a content record

Request:¶

POST /content HTTP/1.1
Host: directory.example
Date: Thu, 15 Jan 2026 12:00:00 GMT
Content-Type: application/json
Signature-Input: sig1=("@method" "@target-uri" "host" "date" "content-digest");created=1768478400;keyid="https://keys.example/alice-2026.json";alg="ed25519"
Signature: sig1=:gdWl4N5vUFjVBFg8HDJu49u03bCfSvu/m0A5Ql8omqsoBIbiMXiyyaRQmgBQ7pS7ze7dA0VSx1rD+VbBi2qADg:
Content-Digest: sha-256=:vVnocWvEKyG/MTZYW9GmhC8a+6EE3faenFcdA9UF8Ug:

{
  "profile": "htmltrust-signature-v1",
  "contentHash": "sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8",
  "keyid": "https://keys.example/alice-2026.json",
  "algorithm": "ed25519",
  "signedAt": "2026-01-15T12:00:00Z",
  "scope": "url",
  "location": "https://example.com/essays/engines",
  "signature": "m0ykSPqUWdyZprUAqosOB2IEK2XsKp7auPIWz80/2ht+LwT1LiNcsLL6cn2IkmTZFG9ptLiUHaB1crPJgBw7BA",
  "sourceURL": "https://example.com/essays/engines",
  "claims": [{"name":"author","content":"Ada Lovelace"},{"name":"claim:License","content":"CC-BY-4.0"},{"name":"signed-at","content":"2026-01-15T12:00:00Z"}]
}

Response:¶

HTTP/1.1 201 Created
Location: https://directory.example/content/sha256%3AIVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8
Content-Type: application/htmltrust-content+json

{
  "contentHash": "sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8",
  "firstSeen": "2026-05-15T12:34:56Z",
  "signers": [
    {
      "profile": "htmltrust-signature-v1",
      "keyid": "https://keys.example/alice-2026.json",
      "algorithm": "ed25519",
      "signedAt": "2026-01-15T12:00:00Z",
      "scope": "url",
      "location": "https://example.com/essays/engines",
      "signature": "m0ykSPqUWdyZprUAqosOB2IEK2XsKp7auPIWz80/2ht+LwT1LiNcsLL6cn2IkmTZFG9ptLiUHaB1crPJgBw7BA"
    }
  ],
  "endorsementCount": 0
}

C.2. Submitting an endorsement

Request body (after canonicalization per Section 11.2 and signing):¶

{
  "endorser": "did:web:reviewer.example",
  "endorsement": "sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8",
  "algorithm": "ed25519",
  "timestamp": "2026-05-10T09:00:00Z",
  "claim": "Verified original publication.",
  "expires": "2026-12-31T00:00:00Z",
  "signature": "wRGf14sbPTYebexyPALRMCo122Gaei+wQaQIh/taes/LQWKTQTSW2yBDIOUkBkG/uDGMMU7D1W6AveDClZNPCg"
}

For the endorsement example, the JCS input (the document above with the signature member removed) is:¶

{"algorithm":"ed25519","claim":"Verified original publication.","endorsement":"sha256:IVAwpRTDujszmYf76W497alVTtxGCgtJtQlasiFSCM8","endorser":"did:web:reviewer.example","expires":"2026-12-31T00:00:00Z","timestamp":"2026-05-10T09:00:00Z"}

The Ed25519 signature above is reproducible with the test seed in this appendix. Its canonical payload hash is sha256:sPBnoFyxiTmeBOQHaTyhdJy6prv3jmTdoTZpDXP5xrg.¶