Skip to main content

External Resource Integrity

Summary​

The External Resource Target defined in this document is a Content Attestation (CA) property for assuring the integrity of external resource files such as images, videos, etc. While it can assure the integrity of the resource referenced by a URL, it is limited to URLs that return the same byte sequence as a response regardless of the user agent.

note

We plan to receive feedback on this target from the companies participating in the pilot experiments. We may add better methods in the future while monitoring the status of updates to related specifications.

Reference: Consideration of a method to enable verification when using CDN with image processing

Scope​

  • It targets static files.
  • Dynamic resources generated by JavaScript etc. are outside the scope of this document.
  • This does not apply to videos delivered with Adaptive Bitrate Streaming. Only videos delivered as a single video file are supported.
  • Resources that are rendered via CSS, such as the background-image CSS property or the content CSS property, are outside the scope of this document.
  • Dynamic resources through content negotiation are outside the scope of this document.

Terminology​

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

  • Content Attestation (CA)

External Resource Target Form​

It must be a JSON object. Below is an example of an External Resource Target:

{
  "type": "ExternalResourceTargetIntegrity",
  "integrity": "sha256-OYP9B9EPFBi1vs0dUqOhSbHmtP+ZSTsUv2/OjSzWK0w="
}

The following properties are defined:

  • type: REQUIRED. It MUST be ExternalResourceTargetIntegrity.
  • integrity: REQUIRED. It MUST be the sriString data type. For available hash functions, it MUST conform to Hash Algorithm. Example: sha256-4HLmAAYVRClrk+eCIrI1Rlf5/IKK0+wGoYjRs9vzl7U=

How to set it up​

Specify the same value as the integrity property for the integrity attribute of the HTML element.

Example​

Below is an example of referencing the source and img elements from an External Resource Target:

External Resource Target:

[
  {
    "type": "ExternalResourceTargetIntegrity",
    "integrity": "sha256-4HLmAAYVRClrk+eCIrI1Rlf5/IKK0+wGoYjRs9vzl7U="
  },
  {
    "type": "ExternalResourceTargetIntegrity",
    "integrity": "sha256-t7WZSGxDdqGvGg/FLw6wk9KFQy5StT1MquCf/htwjBo= sha256-4HLmAAYVRClrk+eCIrI1Rlf5/IKK0+wGoYjRs9vzl7U="
  }
]

In this case, add the integrity attribute to the HTML source element and img element of the web page as follows:

<picture>
  <source
    srcset="image.jpg"
    media="(min-width: 400px)"
    integrity="sha256-4HLmAAYVRClrk+eCIrI1Rlf5/IKK0+wGoYjRs9vzl7U="
  />
  <img
    src="https://cdn.example.com/image.jpg"
    integrity="sha256-t7WZSGxDdqGvGg/FLw6wk9KFQy5StT1MquCf/htwjBo= sha256-4HLmAAYVRClrk+eCIrI1Rlf5/IKK0+wGoYjRs9vzl7U="
  />
</picture>

Below is an example of referencing a video element from an External Resource Target.

External Resource Target:

[
  {
    "type": "ExternalResourceTargetIntegrity",
    "integrity": "sha256-OYP9B9EPFBi1vs0dUqOhSbHmtP+ZSTsUv2/OjSzWK0w= sha256-zc3KMRPJkbv6p7sOq5Di/CNe+4XyqBBuiKjzP3A3NP0="
  },
  {
    "type": "ExternalResourceTargetIntegrity",
    "integrity": "sha256-zc3KMRPJkbv6p7sOq5Di/CNe+4XyqBBuiKjzP3A3NP0="
  }
]

In this case, add the integrity attribute to the HTML source element and video element of the web page as follows:

<video
  integrity="sha256-OYP9B9EPFBi1vs0dUqOhSbHmtP+ZSTsUv2/OjSzWK0w= sha256-zc3KMRPJkbv6p7sOq5Di/CNe+4XyqBBuiKjzP3A3NP0="
  poster="https://cdn.example.com/poster.jpg"
>
  <source
    src="https://cdn.example.com/video.mp4"
    integrity="sha256-OYP9B9EPFBi1vs0dUqOhSbHmtP+ZSTsUv2/OjSzWK0w="
    type="video/mp4"
  />
  <source
    src="https://cdn.example.com/video.webm"
    integrity="sha256-zc3KMRPJkbv6p7sOq5Di/CNe+4XyqBBuiKjzP3A3NP0="
    type="video/webm"
  />
</video>
note

In this case, the external resource specified in the src attribute is validated, but the external resource specified in the poster attribute is not validated. Specifications for making external resources specified in the poster attribute verifiable are under consideration.

Below is an example of referencing an a element from an External Resource Target.

External Resource Target:

[
  {
    "type": "ExternalResourceTargetIntegrity",
    "integrity": "sha256-Ip3vuwzubwJnOlzeKQ0Gc+daDcMc7EOYnIqypOyn4bs="
  }
]

In this case, add the integrity attribute to the HTML a element of the web page as follows:

<a
  href="https://cdn.example.com/document.pdf"
  integrity="sha256-Ip3vuwzubwJnOlzeKQ0Gc+daDcMc7EOYnIqypOyn4bs="
  type="application/pdf"
  >PDF</a
>

Validation Process​

  1. Searches for elements whose integrity HTML attribute contains the same value as the integrity property.
    • If no elements are found, it may be treated as a verification failure.
  2. Retrieves resources corresponding to the elements identified in step 1.
  3. Validate the result and its 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.
Implementation Notes

As described in SRI Section 5.3, in order to prevent an attacker from inferring the content of a cross-origin resource in violation of the Same-Origin Policy by using a known or precomputed hash, when using the SRI validation result to determine the loadability of the cross-origin resource, ensure beforehand that the cross-origin resource is explicitly shared with the request initiator using the CORS protocol.

How to identify element location​

Searches for elements whose integrity HTML attribute exactly matches the integrity property.

info

Care must be taken to ensure that both the integrity property and the integrity HTML attribute have the same value in the following cases:

  • The value of the integrity property consists of two or more SRI hashes
  • Whitespace or line break characters are used in the integrity HTML attribute value for readability

References​