Text within DOM Integrity

Summary

This document describes a format for ensuring the integrity of the text content contained within target elements.

Terminology

For terms not explained in this document, please see Terminology.

• Content Attestation (CA)

Text within DOM Integrity Format

Below is Text within DOM Integrity format

{
  "type": "TextTargetIntegrity",
  "cssSelector": "<CSS Selector>",
  "integrity": "sha256-GtNUUolQVlwIkQU9JknWkwkhfdiVmHr/BOnLFFHC5jI="
}

JSON Schema

{
  "title": "Text within DOM Integrity",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": ["TextTargetIntegrity"]
    },
    "integrity": {
      "type": "string"
    },
    "cssSelector": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": ["type", "integrity", "cssSelector"]
}

Property

Name	Type	Description
type	string	REQUIRED. It is the type of Content Integrity Descriptor. It MUST be TextTargetIntegrity.
integrity	string	REQUIRED. It MUST be the sriString data type. For available hash functions, it MUST conform to Hash Algorithm. Example: sha256-4HLmAAYVRClrk+eCIrI1Rlf5/IKK0+wGoYjRs9vzl7U=
cssSelector	string	REQUIRED. It MUST be a CSS Selector (Selectors Level 3).

note

CA issuers are RECOMMENDED to specify cssSelector so that the elements that cssSelector matches do not change regardless of dynamic changes to the page. For example, specify a more detailed CSS selector such as #paragraphID or p.rareClassName, rather than just specifying a tag name such as p for cssSelector. If there is no CSS selector that stably and uniquely identifies the target element, it is RECOMMENDED to update the page and design the page so that it is easier to specify an id attribute for the target element.

Validation Process

1. Searches for an element specified by a CSS selector in the cssSelector property. The target element is searched for using the querySelectorAll() method, starting from the root element of the page's document (for example, the <html> element for an HTML document).
   • If there is a syntax error in the cssSelector property, it may be treated as a verification failure (e.g. DOMException SyntaxError).
   • If no elements are found, it may be treated as a verification failure. If null is obtained, converts the target to an empty string.
2. Gets the target element's descendant text content, which is the value of the element's textContent attribute. If null is obtained, converts the target to an empty string ("").
3. Encode all objects into UTF-8. If there are multiple objects, combine their contents.
4. Validate the result and the integrity property using the methods specified in SRI section 3.3.5.
   • If an unsupported hash algorithm is used, it may be treated as a verification failure.

note

Text within DOM Integrity uses the textContent attribute and is different from the innerText attribute. See Differences from innerText - MDN for the main differences between the two.

How to identify element location

Searches for an element specified by the CSS selector in the cssSelector property.