Content Attestation Set Verifier Processing in HTML Documents

Scope

This document concretizes the Verifier Processing Model for the verification of Content Attestation Sets (CAS) in HTML documents, and for the handling of Originator Profile Sets (OPS) as input to that verification. This document defines what the Verifier Processing Model requires of a Verifier Processing Document.

The verification procedure of a CA itself follows the Content Attestation verification process, and the verification procedure of the OPS used to verify a CA follows the Originator Profile Set verification process. This document defines when those verifications start, how long their outcomes remain effective, and how they are presented.

Terminology

For terms not explained in this document, see Terminology, the Verifier Processing Model, and the terminology of Site Profile Verifier Processing in HTML Documents.

In addition, this document uses the following terms:

• Input Dependency: the kind of Document state on which the verification input of a Content Integrity Descriptor depends. Defined in Input Dependency
• Distributor: a party that places the script elements of a CAS and an OPS in a Document. It is not necessarily the same as the issuer of the CA or the holder of an OP contained in the OPS

Discovery

Identifying the Target

The verification targets are the CAs contained in a CAS linked to the Document by a script element.

An OPS is not a verification target but a material used to verify CAs (input scope). For a Document with no CAS and only an OPS linked to it, a verifier does not treat the OPS as a verification target.

note

An OPS has no information that binds it to a Document. A Site Profile is bound to an origin by the allowedOrigin property of its Website Profile, and a CA is bound to the URL of a web page by its allowedUrl property, whereas an OPS is signed public data that can be placed in any Document. Verifying only an OPS and presenting it as the originator of the Document would make users believe it is verified, even though no one has verified the binding between the Document and the originator.

Discovery Trigger

A verifier MUST start discovering a CAS when a script element whose type attribute is application/ca-set+json is inserted into the Document. Insertion by the parser and insertion by a script are not distinguished. Deprecated media types are handled as described in Media Types.

note

Using insertion as the trigger lets the same rule handle Documents built by the parser and Documents built by scripts. A distributor can control when verification starts through the time at which it inserts the script element of the CAS.

Resolution

Retrieval Routes

A CAS and an OPS are obtained either by embedding in the content of a script element or by external reference through the src attribute.

The verification input of a Content Integrity Descriptor is obtained by the method defined for each type.

External references through the src attribute, the target resources of ExternalResourceTargetIntegrity, and the id URLs of the image datatype are retrieved according to the Fetch Standard. A verifier MAY use a response stored in the HTTP cache.

Input Scope

The OPs that may be used to verify a CA in a Document are limited to the following (MUST):

• OPSs placed in the same Document
• OPSs the verifier holds in advance
• If the Document is a top-level document, the originators property of the Site Profile of its origin

CPs are verified with the verification keys and OP IDs of CP issuers that the verifier has accepted in advance.

A verifier MUST NOT use an OPS placed in a parent Document or a sibling Document to verify a CA.

"Placed in the same Document" means that it was present in the Document at the time the input snapshot was taken.

A distributor presenting a CA in a Document in a subframe MUST place the OPS needed for its verification in the same Document.

A distributor MUST insert the script element of the OPS needed to verify a CA into the Document by the time verification of that CA starts. Inserting the script element of the OPS before that of the CAS satisfies this requirement.

note

There are two reasons for limiting the input scope to the Document.

One is independence from the embedding context. The same content must not get different verification outcomes depending on which Document it is embedded in. If an OPS of the parent Document could be used, the same advertisement could pass verification on parent page A but not on page B.

The other is preventing input contamination. A malicious parent Document must not be able to place an OPS that wrongly makes a CA in a subframe verified. Conversely, an OPS placed by a malicious subframe must not be used to verify a CA of the parent Document.

note

Under this section, the same content may pass verification when accessed as a top-level document but not when embedded in a subframe, because the originators property of the Site Profile can be used for a top-level document but not for a subframe. This also applies to same-origin subframes. Tests of verifiers should cover both top-level documents and subframes.

Input Dependency

The verification input of a Content Integrity Descriptor depends, per type, on one of the following input dependencies:

Input dependency	Meaning
response	The byte sequence of the fetched resource
parsed DOM	The parsed DOM
rendered result	The rendering result

The input dependencies of the registered types are as follows:

type	Input dependency	Verifiable point
ExternalResourceTargetIntegrity	response	Completion of the retrieval of the target resource
HtmlTargetIntegrity	parsed DOM	When the readiness of the Document becomes interactive
TextTargetIntegrity	parsed DOM	When the readiness of the Document becomes interactive
VisibleTextTargetIntegrity (deprecated)	rendered result	When the readiness of the Document becomes complete

Input dependencies are used to determine when verification starts, invalidation, and reuse.

Verification

Applicable Verifications

The applicable verifications for a CA are as follows. The parenthesized text is the unit by which each verification is identified.

• For the VC of the CA, verification of VCs conforming to the OP VC Data Model, excluding verification of the image datatype (per CA)
• Validation of allowedUrl (per CA)
• Verification of the Content Integrity Descriptor (per target)
• For each VC of the OPS containing the OP of the CA's issuer, verification of VCs conforming to the OP VC Data Model, excluding verification of the image datatype (per VC)
• Verification of the image datatype (per property of the image datatype)

The order of verification processing follows the Content Attestation verification process and the Originator Profile Set verification process.

If the Document is a top-level document and the OP of the CA's issuer is obtained from the originators property of the Site Profile, a verifier MAY use the verification outcome of the SP instead of verifying that OP again, but only if the outcome state of that SP is Verified. In that case, the verification scope of the CA's verification outcome includes the verification scope of the SP's verification outcome used.

An OPS can contain VCs in multiple languages in its annotations and media properties (Originator Profile Set internationalization). If the verifier narrows down the VCs to verify by language, the verification scope of that outcome includes only some of the applicable verifications.

note

Narrowing down the VCs to verify by language yields, for the same originator, verification outcomes with different verification scopes depending on the user's language settings. The presentation requirements allow users to distinguish them.

Evaluating allowedUrl

The "URL of the web page on which the CA is presented" in validation of allowedUrl is the document's URL at the time the input snapshot was taken (MUST).

When Verification Starts

A verifier MUST NOT start verification of a CA until all of the following are satisfied:

• The script element of the CAS containing the CA has been inserted into the Document. In the case of an external reference through the src attribute, its retrieval has completed
• For the script elements of OPSs inserted into the Document that are external references through the src attribute, their retrieval has completed
• For every target of the CA, the input dependency has reached its verifiable point

A verifier takes the input snapshot at the time verification starts. In this document, "the time the input snapshot was taken" refers to the time verification starts.

If, at that point, any target does not pass verification of its Content Integrity Descriptor, including the case where no element matches the target, the outcome state of the CA is Failed.

A distributor that builds the verification target with scripts MUST insert the script element of the CAS into the Document after finishing that building.

note

The verifiable point of an input dependency is a point that can be observed mechanically from the lifecycle of the Document. Whether building by scripts has finished cannot be observed mechanically, so it is indicated by the time at which the distributor inserts the script element of the CAS. This prevents content that is still being built from being presented as tampered.

note

The rel="expect" value of the HTML link element is a mechanism that blocks rendering until the specified element is parsed. Using it as a means for a distributor to indicate the verifiable point of an input dependency per element is under consideration.

Retention

Binding of the Verification Outcome

The verification outcome of a CA is bound to the Document and its input snapshot.

The verification input of a single CA MUST be a single input snapshot of a single Document. A single verification outcome MUST NOT be derived from input that spans multiple Documents.

Input Identity

Input identity of the verification input of a CA is determined by all of the following:

• The Document is the same
• The CAS containing the CA is the same under the identity for each retrieval route
• The OPSs used for verification are the same under the identity for each retrieval route
• The input dependencies of all targets have not changed
• allowedUrl also matches the current document's URL
• The verifier continues to accept the verification keys and OP IDs of the CP issuers used for verification

The identity of a CAS and an OPS is determined per retrieval route as follows. The input scope is as defined in Input Scope regardless of the retrieval route.

• Embedding: the script element remains in the Document, and its content is the same
• External reference: the script element remains in the Document, the URL of the src attribute is the same, and the retrieved content is the same
• OPSs the verifier holds in advance: the verifier continues to hold and accept the same OPS
• The originators property of the Site Profile: input identity of the verification outcome of the SP used is maintained

Invalidation

In addition to the conditions of invalidation in the Verifier Processing Model, a verification outcome MUST be invalidated when any of the following occurs as a change in the verification input:

• The input dependency of any target has changed
• The verification outcome of the SP used for verification has been invalidated
• The verifier no longer accepts a verification key or OP ID of a CP issuer used for verification
• The CAS containing the CA, or an OPS used for verification, is no longer the same under the identity for each retrieval route
• The content of the Document has been replaced by document.open()
• The document's URL has changed through a same-document navigation, and re-evaluation of allowedUrl no longer matches

A verifier MUST re-evaluate allowedUrl when a same-document navigation occurs.

After invalidation, a verifier MAY start verification of the CA again. This produces a new verification outcome.

note

A change in an input dependency means that the result of recomputing the input dependency has changed. Because elements matching a target are searched from the root element of the Document, adding a matching element outside the target subtree is also a change in the input dependency. A rendered result can change through layout changes even if the DOM is the same.

Because constantly recomputing input dependencies has a large impact on browser performance and power consumption, implementations may approximate this by detecting the following changes:

• parsed DOM: changes to the set of elements matching the CSS selector, and changes to the subtrees of the matched elements
• rendered result: the same changes as for the parsed DOM, plus changes to the viewport size and to the visibility of the Document

For the rendered result, this approximation cannot detect layout changes caused by other factors.

Document Lifecycle and Reuse

Event	Handling of the verification outcome
Navigation to another URL	Discover again for the destination Document
Reload	Discover again for the destination Document
same-document navigation	Re-evaluate allowedUrl
document.open()	Invalidate
Restoration from the back/forward cache	Handle according to the input dependency (see below)

On restoration from the back/forward cache, the same Document becomes fully active again, so the identity of the Document is maintained. However, its input dependencies are not necessarily maintained. In addition to the reuse conditions of the Verifier Processing Model, a verifier MAY reuse a verification outcome only if the input dependencies have not changed.

• A target depending on the response: may be reused
• A target depending on the parsed DOM: may be reused if the DOM has not been changed, such as by a pageshow event handler
• A target depending on the rendered result: MUST be verified again, because the rendering result can change if the size or orientation of the viewport changed while the Document was in the back/forward cache

Presentation

In addition to the presentation requirements, the following requirements apply:

• The verification outcome of a CAS in a fenced frame MUST NOT be presented as part of the verification outcome of the embedding Document
• The language of the VCs to present is selected at the time of presentation. The selection SHOULD follow the Lookup scheme in RFC 4647 Section 3

Distributors SHOULD place an OPS that contains VCs treated as the default.

Scope of Disclosure

Verification processing can cause the following network accesses in addition to the retrieval of the Document:

• Resolution: retrieval of a CAS and an OPS referenced by the src attribute
• Resolution: retrieval of the target resource of ExternalResourceTargetIntegrity
• Verification and Presentation: retrieval of the id URL of properties of the image datatype in VCs contained in a CA and an OPS, for their verification and presentation

These can disclose to the accessed origin that the user is using the Document. When a response stored in the HTTP cache is used, the corresponding network access does not occur.

Security Considerations

Input Contamination Across Frames

An implementation that combines OPSs across frames includes materials controlled by others in its verification input, however strictly it defines the unit of combination. The input scope requirements prevent this by confining the verification input to the Document.

Wrongly Presenting Incomplete Verification

Starting verification before the verifiable point of an input dependency can cause legitimate content to be presented as tampered. The requirements on when verification starts are defined to prevent this.

Appendix A. Correspondence with Implementations

This section is non-normative.

For the correspondence of Document identity, lifecycle, and frame types, see Appendix A of Site Profile Verifier Processing in HTML Documents. In addition, the concepts in this document correspond as follows:

This document	Corresponding API
Insertion of a script element into the Document	Changes to childList observed by a MutationObserver with subtree specified
Readiness of the Document	document.readyState and the readystatechange event
Change in an input dependency (parsed DOM)	Changes observed by a MutationObserver on the Document with subtree specified
Change in the viewport size	The resize event
same-document navigation	webNavigation.onHistoryStateUpdated and webNavigation.onReferenceFragmentUpdated of the WebExtensions API
Restoration from the back/forward cache	A pageshow event whose persisted is true
Visibility of the Document	document.visibilityState and the visibilitychange event