Content Security Policy: Embedded Enforcement

A Collection of Interesting Ideas,

This version:
https://mikewest.github.io/csp-embedded-enforcement/
Editor:
(Google Inc.)

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.

Table of Contents

1. Introduction

This section is not normative.

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 an Embedding-CSP header, as follows:

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

The advertisment will only load if it is delivered with a Content Security Policy which exactly matches the csp attribute’s value. One way to do so is to send the requested policy:

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

The server might want to futher restrict the document, however. Perhaps it wishes to ensure that plugins will not be loaded. It can do so by sending another policy with additional restrictions:

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.

2. Framework

2.1. Specifying a Policy Requirement

Browsing contexts have an iframe security policy attribute, which is null unless otherwise specified.

iframe elements have a csp attribute which specifies the policy that an embedded document must agree to enforce upon itself.

partial interface HTMLIFrameElement {
  attribute DOMString csp;
};

HTMLIFrameElement's csp IDL attribute reflects the value of the element’s csp content attribute.

When an iframe element with a csp attribute has its nested browsing context created (before the intial about:blank Document is created), and when an iframe element’s csp attribute is set or changed while it has a nested browsing context, the user agent must set the nested browsing context’s iframe security policy to the result of executing the parse a serialized policy algorithm on the csp attribute’s value.

During the navigate algorithm, perform the following step after the current step 19. At this point, the user agent has fetched a response which it is about to begin parsing, and redirects have been processed:

  1. If the algorithm in §3.1 Is response blocked by browsing context’s iframe security policy? returns Blocked when executed upon the resource and the browsing context being navigated, abort these steps. The user agent MAY indicate to the user that navigation has been aborted for security reasons.

2.2. The Embedding-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 some requests via an "Embedding-CSP" HTTP request header. The header’s value is represented by the following ABNF [RFC5234]:

Embedding-CSP = serialized-policy

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

Step ~15 of the navigate algorithm needs to be adjusted to add an Embedding-CSP header to a navigational request iff the navigation targets a nested browsing context, and if the browsing context container is an iframe element with a csp attribute. This should be pretty straightforward once the algorithm is rewritten in terms of Fetch, but is a bit tricky today.

3. Algorithms

3.1. Is response blocked by browsing context’s iframe security policy?

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

  1. Let embedding policy be the value of context’s iframe security policy.

  2. Let policy list be the value of response’s policy list.

  3. If the §3.2 Is policy list subsumed under subsuming policy? algorithm returns Subsumed when executed upon policy list and embedding policy, return Allowed.

  4. Return Blocked.

3.2. Is policy list subsumed under subsuming policy?

Given a list of policy objects (policy list), this algorithm returns Subsumed if that list enforces a policy which is an exact match for a given policy object (subsuming policy). It returns Not Subsumed otherwise.

Note: I have delusions of someday defining a real subsumption algorithm which would verify that the policy default-src 'none'; script-src https://example.com is subsumbed under default-src *.example.com (as there is no case in which the latter will block a request that the former would allow). That calculation turns out to be hard, so the current algorithm takes the significantly simpler approach of requiring an exact match.

Note: This is not an efficient algorithm. Implementers are encouraged to implement something a little smarter and faster, with the same behavior.

  1. If subsuming policy is null, return Subsumed.

  2. For each policy in policy list:

    1. If policy’s disposition is not Enforce, set skip to the next policy.

    2. If policy’s directive set is not the same size as subsuming policy’s directive set, skip to the next policy.

    3. For each directive in policy’s directive set:

      1. Let subsuming directive be the directive in subsuming policy’s directive set whose name matches directive’s name, or null if no such directive is present.

      2. If subsuming directive is null, skip to the next policy.

      3. If subsuming directive’s value list is not the same size as directive’s value list, skip to the next policy.

      4. For each token in directive’s value:

        1. If token is not present in subsuming directive’s value, skip to the next policy.

    4. Return Subsumed.

  3. Return Not Subsumed.

Conformance

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.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSP]
Brandon Sterne; Adam Barth. Content Security Policy 1.0. 19 February 2015. NOTE. URL: http://www.w3.org/TR/CSP1/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[DOM-LS]
Document Object Model URL: https://dom.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
[RFC5234]
D. Crocker, Ed.; P. Overell. Augmented BNF for Syntax Specifications: ABNF. January 2008. Internet Standard. URL: https://tools.ietf.org/html/rfc5234

IDL Index

partial interface HTMLIFrameElement {
  attribute DOMString csp;
};

Issues Index

Step ~15 of the navigate algorithm needs to be adjusted to add an Embedding-CSP header to a navigational request iff the navigation targets a nested browsing context, and if the browsing context container is an iframe element with a csp attribute. This should be pretty straightforward once the algorithm is rewritten in terms of Fetch, but is a bit tricky today.