Content Security Policy: Embedded Enforcement

Editor’s Draft,

This version:
https://w3c.github.io/webappsec-cspee/
Latest published version:
https://www.w3.org/TR/csp-embedded-enforcement/
Previous Versions:
Version History:
https://github.com/w3c/webappsec-csp/commits/master/embedded/index.src.html
Feedback:
public-webappsec@w3.org with subject line “[csp-embedded-enforcement] … message topic …” (archives)
Editor:
(Google Inc.)
Participate:
File an issue (open issues)
Tests:
web-platform-tests content-security-policy/embedded-enforcement/ (ongoing work)

Abstract

This document defines a mechanism by which a web page can embed a nested browsing context if and only if it agrees to enforce a particular set of restrictions upon itself.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Changes to this document may be tracked at https://github.com/w3c/webappsec.

The (archived) public mailing list public-webappsec@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “csp-embedded-enforcement” in the subject, preferably like this: “[csp-embedded-enforcement] …summary of comment…

This document was produced by the Web Application Security Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 15 September 2020 W3C Process Document.

1. Introduction

This section is not normative.

Content Security Policy is a great defense against cross-site scripting attacks, allowing developers to harden their own sites against injection of malicious script, style, and other resource types. It does not, however, give developers the ability to apply restrictions to third-party content loaded in via iframe. Allowing CSP to apply directly to these third-party contexts would be dangerous; CSP gives quite granular control over resource loading, and it’s very possible to introduce vulnerabilities into an otherwise secure page by denying it access to particular scripts. We’ve seen these kinds of issues in past features such as X-XSS-Protection, so we must be careful to avoid reintroducing them in a new form.

That said, it would be quite useful to be able to place restrictions upon widgets, advertisements, and other kinds of third-party content. This document proposes a mechanism which relies on an explicit opt-in from the embedded content, which ought to make it possible for widgets to cooperate with their embedders to negotiate a reasonable set of restrictions.

In short, the embedder proposes a Content Security Policy by setting an attribute on an iframe element. This policy is transmitted along with the HTTP request for the framed content in an HTTP request header (Sec-Required-CSP). If the embedded content can accept that policy, it can enforce it by returning a Content-Security-Policy or Allow-CSP-From header along with the response.

If the response contains a policy at least as strict as the policy which the embedder requested, or accepts the embedder-provided policy, then the user agent will render the embedded content. If no such assertion is present, the response will be blocked.

1.1. Examples

MegaCorp Inc. wishes to ensure that the advertisements that run on its various publications are locked down to include script from trusted origins that have been audited for safety. They can do so by including the advertisement via an iframe element with a csp attribute:
<iframe src="https://advertisements-r-us.example.com/ad1.cfm"
        csp="script-src https://trusted-cdn.example.com/">
</iframe>

This will generate a request to advertisements-r-us.example.com that has a Sec-Required-CSP header, as follows:

GET / HTTP/1.1
Host: advertisements-r-us.example.com
...
Sec-Required-CSP: script-src https://trusted-cdn.example.com/
...

The advertisement server parses this request header, decides that it’s acceptable, and adds a header to the response, informing the user agent that it will adhere to the restrictions imposed by its embedder (https://example.com):

HTTP/1.1 200 OK
...
Allow-CSP-From: https://example.com
The advertisement server in the example above could also accept the restrictions by emitting its own Content-Security-Policy header that’s at least as strong as the policy which the embedder requires. For example, it might wish to ensure that no plugins are loaded, regardless of what the embedder allows. It can do so by emitting a policy that includes the embedder’s restrictions, and adds more on top:
HTTP/1.1 200 OK
...
Content-Security-Policy: script-src https://trusted-cdn.example.com/; object-src 'none'

Since the policy asserted by the response allows strictly fewer requests than the policy required by the request, the frame loads successfully.

Note that the server could also deliver two policies, one which mirrors the restrictions of the embedder exactly, another which tightens them:

HTTP/1.1 200 OK
...
Content-Security-Policy: script-src https://trusted-cdn.example.com/, object-src 'none'

The "," in the Content-Security-Policy header’s value splits the string into two serialized policies, each of which is enforced. The user agent verifies that one of the policies delivered with the response matches the requirement, and since additional policies can only make the effective policy for the page more restrictive, allows the frame to load successfully.

2. Framework

At a high level, this document describes a mechanism by which an embedee can opt-into a set of restrictions specified by its embedder. The mechanism involves a few steps:

  1. The embedder specifies a required policy via a csp attribute on an iframe element. This is described in more detail in § 2.1 <iframe>'s csp attribute.

  2. That attribute’s value will be sent along with any navigation request that targets the iframe's nested browsing context in a Sec-Required-CSP HTTP request header. This header is described in more detail in § 2.2 The Sec-Required-CSP HTTP Request Header.

  3. The server can examine the Sec-Required-CSP header to determine whether it wishes to accept the required policy.If so, it can implicitly opt-in by sending a Content-Security-Policy header in the response that contains a policy which is at least as strong as the required policy, or explicitly opt-in by sending an Allow-CSP-From header in the response that enables the embedding origin to set whatever policy it wishes. The explicit mechanism is straightforward, described in § 2.3 The Allow-CSP-From HTTP Response Header. The implicit mechanism is quite complicated, and comprises the entire § 3 Implicit Policy Acceptance section.

    If the server doesn’t wish to accept the required policy, it can return an explicit error, or simply return the usual data without either a matching Content-Security-Policy header or an Allow-CSP-From header. In this case, the user agent will block the response. This integration with HTML’s navigate algorithm is described in § 2.4 Integration with HTML, and the blocking mechanism is spelled out in § 4.1 Is response to request blocked by context’s required CSP?.

2.1. <iframe>'s csp attribute

iframe elements have a csp attribute, which specifies the policy that an embedded document must agree to enforce upon itself. For example, the following HTML would load https://embedee.example.com/, and ensure that object-src 'none' was enforced upon it:

<iframe src="https://embedee.example.com/" csp="object-src 'none'">
</iframe>

A string (value) is a valid attribute value for a given element (element)'s csp content attribute if all of the following statements are true:

  1. value is not the empty string.

  2. value matches the serialized-policy ABNF grammar defined in [CSP].

  3. One of the following statements is true:

    1. element’s node document's browsing context's required CSP is null.

    2. The result of parsing value as "enforce" is subsumed by element’s node document's browsing context's required CSP.

  4. The result of parsing value as "enforce" has a directive set that does not contain any of the following directives:

The following strings are valid values for the csp attribute, as they’re valid CSP grammar:
  • script-src 'none'

  • script-src 'self'; object-src 'none'; sandbox

  • not-a-directive https://whatever.not-a-tld

Note: We consider the last item valid even though it doesn’t express a meaningful policy in order to remain forward-compatible with future CSP syntax.

The following, on the other hand, do not match the CSP syntax, and would not be considered valid attribute values:

  • script-src *\nInjected-Header: XSS!

  • 💩

Note: We need to be careful about the values we allow in the csp attribute, as its contents will end up reflected as an HTTP request header. This concern is discussed in a little more detail in § 5.4 Header Injection.

iframe's csp content attribute has a corresponding IDL attribute, defined by the following WebIDL grammar [WEBIDL]:

HTMLIFrameElement/csp

In only one current engine.

FirefoxNoneSafariNoneChrome61+
Opera48+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android61+Android WebView61+Samsung Internet8.0+Opera Mobile45+
partial interface HTMLIFrameElement {
  [CEReactions] attribute DOMString csp;
};

The csp IDL attribute must reflect the element’s csp content attribute.

Upstream this to all the HTMLs.

2.2. The Sec-Required-CSP HTTP Request Header

In order to ensure that the embedded resource can decide whether or not it is willing to adhere to the embedder’s requirements, the policy expressed in an iframe's csp attribute is communicated along with affected navigation requests via a "Sec-Required-CSP" HTTP request header. The header’s value is represented by the following ABNF [RFC5234]:

Sec-Required-CSP = serialized-policy

A user agent MUST NOT send more than one HTTP response header field named "Sec-Required-CSP", and any such header MUST NOT contain more than one serialized-policy.

Servers MUST process only the first policy in the first such header received. As discussed in § 5.5 Header Reflection, servers SHOULD also carefully consider the implications of simply reflecting a policy back to a client. If the server wishes to simply accept an embedder’s requirements, the Allow-CSP-From header is a safer choice.

This header is set as part of HTML’s navigate algorithm (see § 2.4 Integration with HTML for details on the hook that calls the following algorithm):

To set the Sec-Required-CSP header for a given request (request), run the following steps:
  1. If request is not a navigation request, return.

  2. Let requirement be request’s client’s responsible browsing context’s required CSP.

  3. If requirement is null, return.

  4. Assert: requirement is a serialized CSP, matching the serialized-policy grammar defined in [CSP].

  5. Append a header named "Sec-Required-CSP" with a value of requirement to request’s header list.

2.3. The Allow-CSP-From HTTP Response Header

An embedee can opt-into accepting a policy specified by an embedder by responding with a "Allow-CSP-From" HTTP response header. The header’s value is represented by the following ABNF [RFC5234]:

Allow-CSP-From = origin-or-null / wildcard

2.4. Integration with HTML

  1. iframe elements have a csp attribute, defined in § 2.1 <iframe>'s csp attribute.

  2. Each browsing context has a required CSP, defined in § 2.4.1 Browsing Context’s Required CSP.

  3. Add the following after step 10 of HTML’s navigate algorithm:

    1. Set browsingContext's required CSP.

    Upstream this to WHATWG’s HTML.

    W3C’s HTML’s navigation algorithm is wildly divergent from WHATWG’s at this point. Upstream something to that document once things are reconciled. <https://github.com/w3c/html/issues/584>

  4. Add the following to the list of error conditions in step 1 of HTML’s process a navigate response algorithm:

    Upstream this to WHATWG’s HTML.

    W3C’s HTML is not based on Fetch, and does not have a process a navigate response algorithm into which to hook. <https://github.com/w3c/html/issues/584>

  5. Add the following after step 5 of HTML’s process a navigate fetch algorithm:

    1. Set request's "Sec-Required-CSP" header.

    Upstream this to WHATWG’s HTML.

    W3C’s HTML is not based on Fetch, and does not have a process a navigate fetch algorithm into which to hook. <https://github.com/w3c/html/issues/584>

2.4.1. Browsing Context’s Required CSP

Each browsing context has a required CSP, which is either null or a serialized CSP. The value is set during the navigate algorithm, and will not change until the browsing context’s active document changes.

The following algorithm will execute at around step 10 of the current navigate algorithm:

To set the required CSP for a given browsing context (context), run the following steps:
  1. If context is a nested browsing context:

    1. If context’s browsing context container has an csp content attribute with a valid attribute value (value), set context’s required CSP to value and return.

    2. Set context’s required CSP to the value of context’s parent browsing context’s required CSP.

    3. Return.

  2. Set context’s required CSP to null.

Upstream a hook to HTML.

3. Implicit Policy Acceptance

An embedee can explicitly accept a policy requirement specified by its embedder by returning an Allow-CSP-From header along with a response. The requirement can also be implicitly accepted by delivering a Content-Security-Policy header that contains a policy (or set of policies) whose net effect is at least as strict as the policy required by the embedder.

"At least as strict", however, isn’t very precise. Simple cases are straightforward: if an embedder requires object-src https://cdn.example.com, the embedee can respond with object-src 'none'. Since every possible resource that would be blocked by the former would also be blocked by the latter (because it allows no objects at all), we wouldn’t block the embedding. CSP’s syntactical complexity makes this a little bit difficult to reason about for more complicated cases. For instance, given script-src 'unsafe-inline' http: 'sha256-abc...def', it might appear that script-src 'unsafe-inline' would be a subset of the required policy. The presence of the hash-source expression, however means that 'unsafe-inline' is ignored in the required policy, so the latter policy would actually allow more than the former, despite appearances.

To formalize the concept a bit, we need a few terms, and more than a few algorithms:

3.1. Intersection

3.1.1. CSP List intersection

The intersection of a CSP list (list) for an origin (origin) is a single Content Security Policy object representing their net effect, produced by the following algorithm:

Note: It isn’t always possible to represent the intersection of multiple policies as a single policy. Consider script-src 'unsafe-inline' and script-src 'nonce-abc', for instance: the former allows only inline script, the latter allows only inline or externalized script with a particular token. The net effect (only inline script with a particular token) cannot be created with a single policy. Dealing with such policies is, for the moment, left as an exercise for the reader.

We shouldn’t make the reader do this exercise.

  1. Let result be a policy object with an empty directive set and a disposition of "enforce".

  2. For each policy in list:

    1. If policy’s disposition is "report", continue.

    2. Set result to the intersection of result and policy for origin.

  3. Return result.

The intersection of the policies created by parsing each item in the following list of serialized CSPs:
«
    "default-src 'self' http://example.com http://example.net;
     connect-src 'none';",
    "connect-src http://example.com/;
     script-src http://example.com/",
    "style-src 'self';
     script-src http://example.com/ http://example.net",
»

is the policy created by parsing the following serialized CSP:

"default-src 'self' http://example.com http://example.net;
 connect-src 'none';
 script-src http://example.com/;
 style-src 'self'"

Each policy specified in the initial list subsumes the intersection.

3.1.2. Policy Intersection

The intersection of two Content Security Policy objects (A and B) for an origin (origin) is a single Content Security Policy object representing their combined effect, produced by the following algorithm:

  1. Assert: A and B both have a disposition of "enforce".

  2. If A’s directive set is empty, return B.

  3. If B’s directive set is empty, return A.

  4. Let policy be a new policy with an empty directive set, and a disposition "enforce".

  5. Let directive names be an empty set.

  6. For each directive in A:

    1. Append directive’s name to directive names.

  7. For each directive in B:

    1. Append directive’s name to directive names.

  8. For each directive name in directive names:

    1. If directive name is "report-uri", "report-to", continue.

    2. Let directive A be the effective directive value for directive name and A.

    3. Let directive B be the effective directive value for directive name and B.

    4. Assert: directive A and directive B are not both null, and either both of their values are source lists, or neither of their values are source lists.

    5. If either directive A or directive B has a value which is not a source list, continue.

      We need to extend this definition to handle things that are not source lists. Also, we should be more precise about this, perhaps by defining a term like "source list directive" that we could check against directive name.

    6. If directive A is null:

      1. Let directive be a new directive with the following properties:

        name

        directive name

        value

        directive B’s value

      2. append a directive to policy’s directive set.

      3. Continue.

    7. If directive B is null:

      1. Let directive be a new directive with the following properties:

        name

        directive name

        value

        directive A’s value

      2. append a directive to policy’s directive set.

      3. Continue.

    8. Let directive value be the intersection of directive A’s value, directive B’s value, directive name, and origin.

    9. Let directive be a new directive with he following properties:

      name

      directive name

      value

      directive value

    10. Append directive to policy’s directive set.

  9. Return policy.

The intersection of the policies obtained by parsing the following serialized CSPs:
"default-src 'self' http://example.com http://example.net;
 connect-src 'none';"

and

"connect-src http://example.com/;
 script-src http://example.com/"

is the policy obtained by parsing the following serialized CSP:

"default-src 'self' http://example.com http://example.net;
 connect-src 'none';
 script-src http://example.com/;

Both of the given policies subsume the intersection. For example, the intersection’s "script-src http://example.com/" is subsumed by the first policy’s "default-src 'self' http://example.com http://example.net" and the second policy’s "script-src http://example.com/".

3.1.3. Source List Intersection

The intersection of two source lists for a directive name (name) and an origin (origin) is a source list representing their net effect. If no such source list exists (for example, https://example.com/ in A and https://not-example.com in B), then the intersection will be the list « 'none' ».

    1. Let effective A be the effective source list for A, name, and origin.

    2. Let effective B be the effective source list for B, name, and origin.

    3. If either effective A or effective B is « 'none' », return « 'none' ».

    4. If effective A is empty, return effective B.

    5. If effective B is empty, return effective A.

    6 Let schemes be an empty set.

    1. Let intersection be an empty source list.

    2. For each expression B in effective B:

      1. If expression B matches the scheme-source grammar and expression B is contained in effective A, then append expression B to schemes.

        Note: Getting the effective source list above means that tokens matching the scheme-source grammar have already been normalized such that "http:"/"ws:" never appears without "https:"/"ws:" also appearing.

    3. For each expression in schemes:

      1. If expression does not match "https:" or schemes does not contain "http:":

        1. If expression does not match "wss:" or schemes does not contain "ws:", append expression to intersection.

    4. For each expression A in effective A:

      1. If expression A matches scheme-source grammar and schemes contains expression A, continue.

      2. For each expression B in effective B:

        1. If at least one of expression A and expression B does not match scheme-source or host-source grammar:

          1. If expression A matches keyword-source grammar and is an ASCII case-insensitive match for expression B, append expression A to intersection.

          2. If expression A matches nonce-source or hash-source grammar and is a case-sensitive match for expression B, append expression A to intersection.

          3. Continue to the next expression B.

        2. If expression B’s scheme-part matches one of the elements in schemes, continue to the next expression B.

        3. If the result of executing § 4.2.1 What is an intersection of two expressions matching scheme-source or host-source grammar A and B? is not null given expression A and expression B, append the result to intersection.

    5. Return intersection.

In these cases, intersection is an intersection for A and B.
A = wss: http://example.com
B = https: wss: 'none'
intersection = wss: https://example.com

The expression "wss:" is present in both policies, so it is present in their intersection. Similarly, "http://example.com" is present in the intersection because it is the only expression subsumed by both "http://example.com" and "https:". Note that "'none'"" is ignored, as it is not the only token in B.

A = http://*.a.com http://*.b.com
B = https://a.com:* http://*.c.com
intersection = https://a.com

Only two sources are similar: "http://*.a.com" in A is similar to "https://a.com:*" in B so the intersection of the two source lists is "https://a.com".

A = 'unsafe-inline' http://example.com:443/page1/html 'nonce-abc'
B = 'unsafe-inline' https://example.com:443/ 'strict-dynamic' 'nonce-abc'
intersection = 'nonce-abc'

Since "strict-dynamic" honors only nonce-source and hash-source expressions, B is effectively "'strict-dynamic' 'nonce-abc'". That is why the intersection is "'nonce-abc'".

3.1.4. Intersection Helpers

3.1.4.1. Effective Directive Value
Given a string (name) and a policy (policy), the effective directive value for name and policy is the value resulting from running the following steps:
  1. Switch on name and execute the associated steps:

    "child-src"
    "connect-src"
    "font-src"
    "img-src"
    "manifest-src"
    "media-src"
    "object-src"
    "script-src"
    "style-src"
    1. If policy’s directive set contains a directive whose name is name, return that directive’s value.

    2. If policy’s directive set contains a directive whose name is "default-src", return that directive’s value.

    3. Return null.

    "frame-src"
    "worker-src"
    1. If policy’s directive set contains a directive whose name is name, return that directive’s value.

    2. If policy’s directive set contains a directive whose name is "child-src", return that directive’s value.

    3. If policy’s directive set contains a directive whose name is "default-src", return that directive’s value.

    4. Return null.

    "base-uri"
    "block-all-mixed-content"
    "default-src"
    "frame-ancestors"
    "form-action"
    "plugin-types"
    "report-uri"
    "require-sri-for"
    "sandbox"
    "upgrade-insecure-requests"
    1. If policy’s directive set contains a directive whose name is name, return that directive’s value.

    2. Return null.

  2. Return null.

3.1.4.2. Effective Source List
Given a source list (list), a string (name), and an origin (origin), the effective source list for list, name, and origin is a simplification of list that expands complex tokens like 'self' and *, and removes ineffective, obviated, or invalid tokens (for instance, 'unsafe-inline' in the presence of a nonce). The result of running the following steps will generally be more verbose than list, but will be significantly simpler to compare:
  1. If list is empty or « 'none' », return « 'none' ».

  2. Let result be an empty source list.

  3. For each expression in list:

    1. If expression is "'self'":

      1. Append the result of executing § 4.2.2 Rewrite 'self' into a host-source expression for origin. given origin to result.

      2. Continue.

    2. If expression matches the keyword-source grammar, and name is not "script-src" or "style-src", continue.

    3. Continue if any of the following statements are true:

    4. If expression is the U+002A ASTERISK character (*):

      1. For each scheme in « "ftp:", "http:", "https:", "ws:", "wss:" »:

        1. Append scheme to result.

      2. Append the concatenation of origin’s scheme and ":" to result.

      3. Continue.

    5. If expression matches the scheme-source grammar:

      1. If expression is "http:", append "https:" to result.

      2. If expression is "ws:", append "wss:" to result.

    6. If expression matches the host-source grammar:

      1. If expression’s scheme-part is "http", append the result of concatenating "https://", expression’s host-part, expression’s port-part, and expression’s path-part to result.

      2. If expression’s scheme-part is "ws", append the result of concatenating "wss://", expression’s host-part, expression’s port-part, and expression’s path-part to result.

    7. Append expression to result.

  4. If result is empty or « 'strict-dynamic' », return « 'none' ».

  5. Return result.

For any directive with origin https://example.test/:

https: wss: 'none' 'self'

The effective source list is "http: wss: https://example.test/". Note that "'none'" is not part of the effective source list because it has no effect when it is not the only source.

For "style-src":

http://example.com 'strict-dynamic' 'nonce-abc'

The effective source list is "http://example.com 'nonce-abc'" since "'strict-dynamic'" is ignored in non-"script-src" directives.

For "script-src":

http://example.com 'strict-dynamic' 'nonce-abc'

The effective source list is "'strict-dynamic' 'nonce-abc'" since "'strict-dynamic'" in "script-src" case does not honor host and scheme source expressions.

3.1.4.3. Source Expression Similarity

A source expression (A) is said to be source-expression similar to another source expression (B) if the two expressions are case-sensitive matches, or if the relevant parts of their grammar match (for example, in the case of scheme-source expressions, the respective scheme-parts must scheme-part match in one direction or the other.

Note: This property is symmetric. That is if A is source-expression similar to B, then B will be source-expression similar to A.

A source expression has a wildcard host if the first character of the source expression’s host-part is an U+002A ASTERISK character (*).

A source expression has a wildcard port if the port-part of the source expression is an U+002A ASTERISK character (*).

  1. If A’s grammar does not match B’s grammar, return "Not Similar".

  2. If A matches the keyword-source, nonce-source, or hash-source grammar:

    1. If A is a case-sensitive match to B, return "Similar".

    2. Return "Not Similar".

  3. Let scheme A be A’s scheme-part, if present, and null otherwise.

  4. Let scheme B be B’s scheme-part, if present, and null otherwise.

  5. If the scheme A does not scheme-part match scheme B, and scheme B does not scheme-part match scheme A, return "Not Similar".

  6. If A or B matches scheme-source grammar, return "Similar".

  7. Let host A be A’s host-part, if present, and null otherwise.

  8. Let host B be B’s host-part, if present, and null otherwise.

  9. Let port A be A’s port-part, if present, and null otherwise.

  10. Let port B be B’s port-part, if present, and null otherwise.

  11. Let path A be A’s path-part, if present, and null otherwise.

  12. Let path B be B’s path-part, if present, and null otherwise.

  13. Return "Not Similar" if any of the following is true:

    1. Both A and B have a wildcard host, but host A is not an ASCII case-insensitive match to host B.

    2. At most one of A and B has a wildcard host, host A does not host-part match host B, and host B does not host-part match host A.

    3. Neither A nor B has a wildcard port, port A does not port-part match port B, and port B does not port-part match port A.

    4. path A does not path-part match path B, and path B does not path-part match path A.

  14. Return "Similar".

A = 'nonce-ch4hvvbHDpv7xCSvXCs3BrNggHdTzxUA'
B = 'nonce-ch4hvvbHDpv7xCSvXCs3BrNggHdTzxUA'

Since both A and B match the nonce-source grammar and A is a case-sensitive match for B, A is similar to B.

A = https://inner.example.com/foo/
B = http://*.example.com/foo/bar/

Since A has a wildcard host, it matches any subdomain which in this case is "inner" so that A is similar to B.

A = http://*.example.com
B = https://example.com:*

Even though A and B’s ports are different, A and B are similar because "http" matches both "http" and a more secure variant "https".

A = http://example.com:80/page1/html
B = https://example.com:443/

In both sources specified ports are defalt ports for the respective schemes and B’s path would match any path, A is similar to B.

A = 'sha256-abc123'
B = 'sha512-cde456'

Even though both A and B match the hash-source grammar, A is not a case-sensitive match for B because the hashes don’t match.

A = http://example.com:80
B = http://example.com:334

In this case, ports of A and B do not match so that the two sources are not similar .

A = http://example.com/page.html
B = http://example.com/index.html

The two sources are not similar because their paths do not match.

Move the remaining intersection algorithms into this section.

3.2. Subsumption

Move all the subsumption algorithms into this section.

4. Algorithms

4.1. Is response to request blocked by context’s required CSP?

Given a response (response), a request (request), and a browsing context (context), this algorithm returns "Allowed" or "Blocked" as appropriate:

  1. Return "Allowed" if either of the following is true:

    1. context is not a nested browsing context.

    2. context’s required CSP is null.

  2. Let required policy be the result of executing Content Security Policy §2.2.1 Parse a serialized CSP on context’s required CSP and "enforce".

  3. If the § 4.2 Does response allow blanket enforcement of policy from request? algorithm returns "Allowed" when executed upon response and request:

    1. Append required policy to response’s CSP list.

    2. Return "Allowed".

  4. Assert: context is a nested browsing context, and response is a cross-origin, network schemed resource.

  5. If the § 4.3 Does subsuming policy subsume policy list given their respective origins? algorithm returns "Subsumes" when executed upon required policy, request’s origin, response’s CSP list, and response’s url’s origin, return "Allowed".

  6. Return "Blocked".

4.2. Does response allow blanket enforcement of policy from request?

Given a response (response), and a request (request), this algorithm returns "Allowed" if the former allows the latter to enforce arbitrary policy, and "Not Allowed" otherwise:

  1. If response’s url’s scheme is a local scheme, return "Allowed".

    Note: The embedder has direct access to same-origin responses, so if it wishes to enforce a policy on that same-origin response, we simply do so.

  2. If response’s url’s origin is the same as request’s origin, return "Allowed".

    Note: Likewise, local scheme responses already inherit their policy from the embedder, so we allow the embedder to tighten that policy via this embedding mechanism.

  3. If response’s header list has a header named Allow-CSP-From (header):

    1. If header’s value is "*", return "Allowed".

    2. If request’s origin, serialized and UTF-8 encoded is header’s value, return "Allowed".

  4. Return "Not Allowed".

4.2.1. What is an intersection of two expressions matching scheme-source or host-source grammar A and B?

Source expression is said to be an intersection of two other expressions matching scheme-source or host-source grammar A and B if it contains the more restrictive scheme-part, host-part, port-part, and path-part of the two.

In these cases, Intersect is an intersection for A and B.
A = https:
B = http:
Intersect = https:
A = http://*.example.com
B = https://example.com:*
Intersect = https://example.com:443
A = http://example.com:80/page1/html
B = https://example.com:443/
Intersect = https://example.com:443/page1/html
A = https:
B = http://example.com
Intersect = https://example.com.
A = https://example.com:*
B = http://*.example.com/page.html
Intersect = https://example.com/page.html

Given two expressions matching the scheme-source or host-source grammar (A and B), return their intersection if A is source-expression similar to B. Otherwise, return null.

  1. If A is not source-expression similar to B, return null.

  2. Let source be an empty string.

  3. Let scheme A be A’s scheme-part, if present, and null otherwise.

  4. Let scheme B be B’s scheme-part, if present, and null otherwise.

  5. Let more secure scheme B be true if scheme A does not scheme-part match scheme B, and false otherwise.

  6. Append scheme A and ":" to source if scheme A is not null and more secure scheme B is false. Otherwise, append scheme B and ":" to source if scheme B is not null.

  7. If both A and B match the scheme-source grammar, return source.

  8. Append "//" to source if it is not empty.

  9. Let host A be A’s host-part, if present, and null otherwise.

  10. Let host B be B’s host-part, if present, and null otherwise.

  11. If host A is not null:

    1. If host B is null, append host A to source. Continue to the next step in the main algorithm.

    2. If A doesn’t match the scheme-source grammar and doesn’t have a wildcard host, append host A to source.

    3. Otherwise, append host B to source.

  12. If host A is null, append host B to source.

  13. Let port A be A’s port-part, if present, and null otherwise.

  14. Let port B be B’s port-part, if present, and null otherwise.

  15. If port A is null, append ":" and port B to source if it is not null.

  16. If port A is not null:

    1. If port B is null, append ":" and port A to source. Continue to the next step in the main algorithm.

    2. If A doesn’t have a wildcard port and more secure scheme B is false, append ":" and port A to source.

    3. Otherwise, append ":" and port B to source.

  17. Let path A be A’s path-part, if present, and null otherwise.

  18. Let path B be B’s path-part, if present, and null otherwise.

  19. If path A is null, append path B to source if it is not null.

  20. If path A is not null:

    1. If path B is null, return the result of appending path A to source.

    2. If path A path-part matches path B, append path A to source.

    3. Otherwise, append path B to source.

  21. Return source.

4.2.2. Rewrite 'self' into a host-source expression for origin.

Given an origin (origin), this algorithm returns a host-source expression that has the same effect as 'self' for that origin:

  1. If origin is an opaque origin, return the empty string.

  2. Return the ASCII serialization of origin.

4.2.3. Does source expression A subsume source expression B?

Given two source expressions A and B, this algorithm returns "Subsumes" if A subsumes B, and returns "Does Not Subsume" otherwise.

  1. Assert: Neither A nor B match the keyword-source grammar.

  2. If both A and B match either host-source or scheme-source grammar:

    1. If Content Security Policy §6.6.2.7 scheme-part matching returns "Does Not Match" given A’s scheme-part (or null if A does not contain a scheme-part) and B’s scheme-part (or null if B does not contain a scheme-part), return "Does Not Subsume".

    2. If A or B matches the scheme-source grammar:

      1. If A matches the scheme-source grammar, return "Subsumes". Otherwise, return "Does Not Subsume".

    3. If B has a wildcard host:

      1. If A doesn’t have a wildcard host, return "Does not Subsume".

      2. Let remaining host B be the result of removing the leading ("*.") from B’s host-part.

      3. If Content Security Policy §6.6.2.8 host-part matching returns "Does Not Match" given A’s host-part and remaining host B, return "Does Not Subsume".

    4. If B doesn’t have a wildcard host and Content Security Policy §6.6.2.8 host-part matching returns "Does Not Match" given A’s host-part and B’s host-part, return "Does Not Subsume".

    5. If A has a wildcard port but B doesn’t have a wildcard port, return "Does Not Subsume".

    6. If A doesn’t have a wildcard port and Content Security Policy §6.6.2.9 port-part matching returns "Does Not Match" given A’s port-part (or null if A does not contain a port-part) and B’s port-part (or null if B does not contain a port-part), return "Does Not Subsume".

    7. If Content Security Policy §6.6.2.10 path-part matching returns "Does Not Match" given A’s path-part (or null if A does not contain a path-part) and B’s path-part (or null if B does not contain a path-part), return "Does Not Subsume".

    8. Return "Subsumes".

  3. If both A and B match the hash-source grammar:

    1. If A is a case-sensitive match to B, return "Subsumes". Otherwise, return "Does Not Subsume".

  4. If both A and B match the nonce-source grammar:

    1. Return "Subsumes".

    Note: Nonce source matching is value-agnostic to prevent a malicious embedder from brute forcing the nonce value with an attack as described in § 5.2 Policy Leakage

  5. Return "Does Not Subsume".

4.2.4. Does source list A subsume source listB given their respective origins and directive names?

Given a source list A with an origin (origin A) and a string (directive A), source list B with an origin (origin B) and a string (directive B), this algorithm returns "Subsumes" if A subsumes B, and returns "Does Not Subsume" otherwise.

A directive contains a given source expression if the expression is contained by its value.

  1. If directive A is not an ASCII case-insensitive match to directive B, return "Does Not Subsume".

  2. If A is empty or B is none, return "Subsumes".

  3. If B is empty or A is none, return "Does Not Subsume".

  4. If directive B is "script-src" and B contains a keyword-source expression "strict-dynamic" but A does not contain it, return "Does Not Subsume".

  5. If directive B is "script-src" or "style-src":

    1. If B contains a keyword-source expression "unsafe-eval" but A does not contain it, return "Does Not Subsume".

    2. If B contains a keyword-source expression "unsafe-hashed-attributes" but A does not contain it, return "Does Not Subsume".

    3. Let type B be "script" if directive B is "script-src" and "style" otherwise. Similarly, let type A be "script" if directive A is "script-src" and "style" otherwise.

    4. If Content Security Policy §6.6.3.2 Does a source list allow all inline behavior for type? returns "Allows" given B with type B, but returns "Does Not Allow" given A with type A, return "Does Not Subsume".

  6. Let list A and list B be empty lists.

  7. For each expression A in A:

    1. If expression A is "self", append a host-source, returned by § 4.2.2 Rewrite 'self' into a host-source expression for origin. given origin A to list A.

    2. If expression A matches the U+002A ASTERISK character (*), append to list A the following scheme-source expressions: "ftp:", "http:", "https:", "ws:", "wss:", and origin A’s scheme.

      1. If directive A is either "img-src" or "media-src", append a scheme-source expression "data:" to list A.

      2. If directive A is "media-src", append a scheme-source expression "blob:" to list A.

      3. Continue to the next expression A.

    3. If expression A does not match keyword-source grammar, append expression A to list A.

  8. For each expression B in B:

    1. If expression B is "self", append a host-source, returned by § 4.2.2 Rewrite 'self' into a host-source expression for origin. given origin B to list B.

    2. If expression B matches the U+002A ASTERISK character (*), append to list B the following scheme-source expressions: "ftp:", "http:", "https:", "ws:", "wss:", and origin B’s scheme.

      1. If directive B is either "img-src" or "media-src", append a scheme-source expression "data:" to list B.

      2. If directive B is "media-src", append a scheme-source expression "blob:" to list B.

      3. Continue to the next expression B.

    3. If expression B does not match keyword-source grammar, append expression B to list B.

  9. If list B is empty, return "Subsumes".

  10. If list A is empty, return "Does Not Subsume".

  11. For each expression B in list B:

    1. If expression B matches the hash-source gramar, or nonce-source grammar, continue to the next expression unless directive A is "script-src" or "style-src".

    2. Let found match be false.

    3. For each expression A in list A:

      1. If § 4.2.3 Does source expression A subsume source expression B? returns "Subsumes" given expression A and expression B, set found match to true. Break out of this inner loop.

    4. If found match is false, return "Does Not Subsume".

  12. Return "Subsumes".

Let directive A and directive B be "script-src". Consider the following examples:
A = "http://example.com 'sha256-xzi4zkCjuC8'"
B = "http://example.com"

Since B does not allow hash-source expressions, but its value is found in A, A subsumes B. It is, however, not true that B subsumes A.

A = "https://example.com 'sha256-xzi4zkCjuC8'"
B = "http://example.com"

In this case, A does not subsume B since "https://example.com" does not subsume "http://example.com".

A = "http://example.com 'sha256-xzi4zkCjuC8'"
B = "http://example.com 'unsafe-inline'"

Since B allows all inline behavior, but A does not, A doesn’t subsume B.

A = "http://example.com 'sha256-xzi4zkCjuC8' 'strict-dynamic'"
B = "http://example.com 'unsafe-inline' 'strict-dynamic'"

Neither A nor B allows all inline behavior. In this case, A subsumes B.

4.2.5. Does policy A subsume policy B given their respective origins?

Given a policy A with an origin (origin A) and a policy B with an origin (origin B), this algorithm returns "Subsumes" if A subsumes B, and returns "Does Not Subsume" otherwise.

  1. If A’s directive set is empty, return "Subsumes".

  2. For each directive A in A’s directive set:

    1. Let directive name be directive A’s name.

    2. If directive name is "default-src", "report-uri", "report-to", continue.

    3. Let effective directive A be the effective directive value for directive name and A.

    4. Let effective directive B be the effective directive value for directive name and B.

    5. If effective directive A is null, continue.

    6. If effective directive B is null, return "Does Not Subsume".

    7. If directive A’s name is "frame-ancestors":

      1. TODO.

    8. If directive A’s name is "plugin-types":

      1. TODO.

    9. If directive A’s name is "sandbox":

      1. TODO.

    10. If directive A’s name is "disown-opener", continue.

    11. Otherwise:

      1. If the result of executing § 4.2.4 Does source list A subsume source listB given their respective origins and directive names? is "Does Not Subsume" given effective directive A, origin A, directive name, effective directive B, origin B, and directive name, return "Does Not Subsume".

    1. Return "Subsumes".

4.3. Does subsuming policy subsume policy list given their respective origins?

Given a policy subsuming policy with an origin (subsuming origin) and a list of policy objects policy list with an origin (origin), this algorithm returns "Subsumes" if subsuming policy subsumes policy list, and returns "Does Not Subsume" otherwise.

  1. If subsuming policy is null, return "Subsumes".

  2. If subsuming policy’s disposition is "report", return "Subsumes".

  3. If subsuming policy’s directive set is empty, return "Subsumes".

  4. If policy list is is empty or null, return "Does Not Subsume".

  5. Let effective policy the result of executing § 3.1.1 CSP List intersection given policy list and origin.

  6. Return the result of executing § 4.2.5 Does policy A subsume policy B given their respective origins? given subsuming policy, subsuming origin, effective policy, and origin.

5. Security and Privacy Considerations

5.1. Policy Enforcement

Embedded documents should be careful to evaluate the proposed Content Security Policy, and not simply to reflect whatever policy an embedder suggests. Doing so may enable a clever attacker to selectively disable pieces of a website’s code which are essential for its own protection.

In particular, documents which do not expect to be embedded should continue to respond to any such request with a Content Security Policy containing an appropriate frame-ancestors directive.

5.2. Policy Leakage

The enforcement mechanism allows a malicious embedder to read a page’s policy cross-origin by brute-forcing its constraints. This could leak interesting data about the page or the user loading the page if the policy contains secret tokens or usernames.

Again, the best defense here is to control the contexts allowed to embed a given resource via an appropriate frame-ancestors directive.

5.3. Data Exfiltration

This feature allows an embedder to send information to a third-party endpoint via the Sec-Required-CSP HTTP header. This doesn’t seem to expose any information that couldn’t be tunneled in the HTTP request itself (via GET parameters, etc), and embedders remain in control over the endpoints to which such requests may be made by enforcing a Content Security Policy with an appropriate child-src directive.

5.4. Header Injection

Spell out the concerns Mario raised in the thread around https://twitter.com/0x6D6172696F/status/810066803653308416.

5.5. Header Reflection

Spell out the concerns Mario raised in the thread around https://twitter.com/0x6D6172696F/status/810066803653308416.

6. Authoring Considerations

6.1. Requiring 'self'

When processing a browsing context’s required CSP, the keyword 'self' refers to the origin of the URL being loaded into the nested browsing context, not to the origin of the document in the source browsing context.

MegaCorp Inc. requires a policy containing 'self' on their page at https://example.com/page.html:
<iframe src="https://advertisements-r-us.example.com/ad1.cfm"
        csp="script-src 'self'">
</iframe>

If the returned CSP is:

Content-Security-Policy: script-src 'self'

Then this iframe element will be loaded.

If, however, the returned CSP is:

Content-Security-Policy: script-src "https://example.com/"

Then this iframe element will not be loaded.

7. IANA Considerations

The permanent message header field registry should be updated with the following registration for the Sec-Required-CSP header: [RFC3864]

Header field name

Sec-Required-CSP

Applicable protocol

http

Status

standard

Author/Change controller

W3C

Specification document

This specification (See § 2.2 The Sec-Required-CSP HTTP Request Header)

Likewise, the registry should be updated with the following registration for the Allow-CSP-From header: [RFC3864]

Header field name

Allow-CSP-From

Applicable protocol

http

Status

standard

Author/Change controller

W3C

Specification document

This specification (See § 2.3 The Allow-CSP-From HTTP Response Header)

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSP]
Mike West. Content Security Policy Level 3. 19 March 2021. WD. URL: https://www.w3.org/TR/CSP3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 11 November 2020. WD. URL: https://www.w3.org/TR/css-values-4/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ENCODING]
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3864]
G. Klyne; M. Nottingham; J. Mogul. Registration Procedures for Message Header Fields. September 2004. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc3864
[RFC5234]
D. Crocker, Ed.; P. Overell. Augmented BNF for Syntax Specifications: ABNF. January 2008. Internet Standard. URL: https://datatracker.ietf.org/doc/html/rfc5234
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WEBIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

partial interface HTMLIFrameElement {
  [CEReactions] attribute DOMString csp;
};

Issues Index

Upstream this to all the HTMLs.
Upstream this to WHATWG’s HTML.
W3C’s HTML’s navigation algorithm is wildly divergent from WHATWG’s at this point. Upstream something to that document once things are reconciled. <https://github.com/w3c/html/issues/584>
Upstream this to WHATWG’s HTML.
W3C’s HTML is not based on Fetch, and does not have a process a navigate response algorithm into which to hook. <https://github.com/w3c/html/issues/584>
Upstream this to WHATWG’s HTML.
W3C’s HTML is not based on Fetch, and does not have a process a navigate fetch algorithm into which to hook. <https://github.com/w3c/html/issues/584>
Upstream a hook to HTML.
We shouldn’t make the reader do this exercise.
We need to extend this definition to handle things that are not source lists. Also, we should be more precise about this, perhaps by defining a term like "source list directive" that we could check against directive name.
Move the remaining intersection algorithms into this section.
Move all the subsumption algorithms into this section.
TODO.
TODO.
TODO.
Spell out the concerns Mario raised in the thread around https://twitter.com/0x6D6172696F/status/810066803653308416.
Spell out the concerns Mario raised in the thread around https://twitter.com/0x6D6172696F/status/810066803653308416.