Add page on integrity; revise SRI guide by wbamberg · Pull Request #43658 · mdn/content

wbamberg · 2026-04-03T03:17:52Z

We didn't have a standalone page for integrity, and since it's a bit involved and used in more than one element. I thought it was worth creating one.

I've talked about including multiple hash values, and the behavior as I understand it.

TBH I don't understand why anyone would provide more than one hash function rather than just use SHA-512. Maybe I'm missing something?

I haven't systematically rewritten the SRI guide, just made some changes that seemed necessary.

I would be tempted to remove a lot of the detail about "how to generate hashes" and just point people at tools like OpenSSL.

github-actions · 2026-04-03T03:19:28Z

Preview URLs (5 pages)

Flaws (34)

Note! 4 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/HTML/Reference/Attributes
Title: HTML attribute reference
Flaw count: 34

broken_links:
- Link /en-US/docs/Web/HTML/Reference/Attributes/alt doesn't resolve
- Link /en-US/docs/Web/HTML/Reference/Attributes/autoplay doesn't resolve
- Link /en-US/docs/Web/HTML/Reference/Attributes/cite doesn't resolve
- Link /en-US/docs/Web/HTML/Reference/Attributes/colspan doesn't resolve
- Link /en-US/docs/Web/HTML/Reference/Attributes/controls doesn't resolve
- and 29 more flaws omitted

External URLs (4)

URL: /en-US/docs/Web/Security/Defenses/Subresource_Integrity
Title: Subresource Integrity

https://github.com/openssl/openssl/wiki/Binaries (1 time) (Note! This may be a new URL 👀)
https://linux.die.net/man/1/shasum (1 time) (Note! This may be a new URL 👀)
https://srihash.org/ (2 times) (Note! This may be a new URL 👀)
https://www.openssl.org/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-04-10 00:20:12)

files/en-us/web/html/reference/elements/link/index.md

files/en-us/web/html/reference/elements/script/index.md

files/en-us/web/security/defenses/subresource_integrity/index.md

files/en-us/web/html/reference/attributes/integrity/index.md

hamishwillee

Looks good

TBH I don't understand why anyone would provide more than one hash function rather than just use SHA-512. Maybe I'm missing something?

AIUI https://github.com/mdn/content/pull/43658/changes#r3037760065

I haven't systematically rewritten the SRI guide, just made some changes that seemed necessary.
I would be tempted to remove a lot of the detail about "how to generate hashes" and just point people at tools like OpenSSL.

Reasonable. I've suggested at least moving the tools to the end after the integrity policy. Also consisider forward referencing integrity-policy in the subresource integrity doc introduction.

files/en-us/web/html/reference/attributes/integrity/index.md

files/en-us/web/security/defenses/subresource_integrity/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Co-authored-by: wbamberg <will@bootbonnet.ca>

github-actions · 2026-04-06T23:27:54Z

files/en-us/web/html/reference/attributes/integrity/index.md

+
+### Including `integrity` on `<script>` elements
+
+The following {{htmlelement("script")}} element includes an `integrity` attribute containing two values calculated using SHA-384, and two calculated using SHA-512. If the browser supports SHA-512 values (as all current browsers do) then it will only use the SHA-512 values, and if the hash of the script at `https://cdn.example.com/script.js` matches either of them, the browser will load it.


[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

The following {{htmlelement("script")}} element includes an `integrity` attribute containing two values calculated using SHA-384, and two calculated using SHA-512. If the browser supports SHA-512 values (as all current browsers do) then it will only use the SHA-512 values, and if the hash of the script at `https://cdn.example.com/script.js` matches either of them, the browser will load it.

The following {{htmlelement("script")}} element includes an `integrity` attribute containing two values calculated using SHA-384, and two calculated using SHA-512. If the browser supports SHA-512 values (as all current browsers do) then it will only use the SHA-512 values, and if the hash of the script at `https://cdn.example.com/script.js` matches either of them, the browser will load it.

github-actions · 2026-04-06T23:27:55Z

files/en-us/web/security/defenses/subresource_integrity/index.md

+This comes with a risk, in that if an attacker gains control of the third-party host, then they can inject arbitrary malicious content into its files (or replace the files completely). This is referred to as a [supply chain attack](/en-US/docs/Web/Security/Attacks/Supply_chain_attacks).

-Subresource Integrity enables you to mitigate some risks of attacks such as this, by ensuring that the files your web application or web document fetches have been delivered without an attacker having injected any additional content into those files — and without any other changes of any kind at all having been made to those files.
+Subresource Integrity is a defense against attacks such as this, by ensuring that the files your web application fetches have exactly the contents that you expect them to have.


[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

Subresource Integrity is a defense against attacks such as this, by ensuring that the files your web application fetches have exactly the contents that you expect them to have.

Subresource Integrity is a defense against attacks such as this, by ensuring that the files your web application fetches have exactly the contents that you expect them to have.

* origin/fix-43302: Apply agreed suggestions

files/en-us/web/security/defenses/subresource_integrity/index.md

hamishwillee · 2026-04-07T07:57:02Z

files/en-us/web/security/defenses/subresource_integrity/index.md

 ```

-## How browsers handle Subresource Integrity
+In `no-cors` mode, a cross-origin request will succeed even if the owner of the resource does not send the appropriate CORS headers, but the content of the response will not be shared with the requester. So a document can _use_ a resource that it requested using `no-cors`, but isn't able to _read_ it.


This is all much more to my taste.

A suggestion though, is that we could be more explicit about what is to follow - an explanation of the reason no-cors is a problem. That makes it very clear the following information is reasoning not instruction.

So perhaps prefix with something like

Suggested change

In `no-cors` mode, a cross-origin request will succeed even if the owner of the resource does not send the appropriate CORS headers, but the content of the response will not be shared with the requester. So a document can _use_ a resource that it requested using `no-cors`, but isn't able to _read_ it.

Browsers will not allow `no-cors` requests to use subresource integrity to avoid attacks that can use SRI to indirectly determine user information.

In `no-cors` mode, a cross-origin request will succeed even if the owner of the resource does not send the appropriate CORS headers, but the content of the response will not be shared with the requester. So a document can _use_ a resource that it requested using `no-cors`, but isn't able to _read_ it.

Just a thought.

wbamberg · 2026-04-07T15:33:18Z

@codingjoe , I would be happy to know if this fixes #43302 in your opinion. It turned into a more extensive fix than I had expected.

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

codingjoe

Thanks! Yes, that's a great improvement! I left a couple of minor notes. I hope they help. - Joe

files/en-us/web/html/reference/attributes/integrity/index.md

codingjoe · 2026-04-08T08:57:41Z

files/en-us/web/html/reference/attributes/integrity/index.md

+- An identifier for a {{glossary("hash function", "cryptographic hash function")}}. Three hash functions are supported. In increasing order of strength, these are: SHA-256, SHA-384, and SHA-512.
+- The result of hashing the resource contents using the specified hash function.
+
+When the browser downloads a resource with the `integrity` attribute set, it will first select the set of hashes that were generated using the strongest hash function present. That is, if the attribute contains values generated with SHA-256 and SHA-384, it will only use the hashes generated using SHA-384.


Is that the case? I don't remember the standard to detail this. What about caching? If your resource was cached but the browser at the time used SHA-256, will it rehash the cached resource?

Is that what's implied here? https://www.w3.org/TR/sri/#get-the-strongest-metadata

That's my reading of it. Also from https://w3c.github.io/webappsec-subresource-integrity/#agility:

the user agent will choose the strongest hash function in the list, and use that metadata to validate the response (as described below in the § 3.3.2 Parse metadata and § 3.3.3 Get the strongest metadata from set algorithms).

I don't know what happens with caching. I guess the integrity would not be checked again (because the resource has already been fetched) but I don't know.

files/en-us/web/html/reference/attributes/integrity/index.md

codingjoe · 2026-04-08T09:12:21Z

files/en-us/web/html/reference/attributes/integrity/index.md

+
+### Including `integrity` on `<link>` elements
+
+The following {{htmlelement("link")}} element loads a stylesheet and includes an `integrity` attribute containing a single value, calculated using SHA-512.


Sidenote: I'd love to see the spec expand integrity values to hyperlinks (a-tags) and img/picture tags.

How cool would it be if I didn't need to compare hashes every time I downloaded software?

files/en-us/web/security/defenses/subresource_integrity/index.md

github-actions · 2026-04-08T19:11:39Z

This pull request has merge conflicts that must be resolved before it can be merged.

files/en-us/web/html/reference/attributes/integrity/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Add page on integrity; revise SRI guide

8be30b3

github-actions bot added Content:HTML Hypertext Markup Language docs Content:Security Security docs size/m [PR only] 51-500 LoC changed labels Apr 3, 2026

wbamberg marked this pull request as ready for review April 3, 2026 03:28

wbamberg requested review from a team as code owners April 3, 2026 03:28

wbamberg requested review from hamishwillee and removed request for a team April 3, 2026 03:28