CSP 1.1: Reworking the experimental script interface.
authorMike West <mkwst@google.com>
Tue, 17 Jul 2012 13:35:20 -0500
changeset 138bff58d373917
parent 137 aa560a7c046c
child 139 b574fbf95a50
CSP 1.1: Reworking the experimental script interface.

Based on discussion from public-webappsec in June[1], this patch changes the
experimental script interface from a one-method-does-everything API into one
with specific methods for each of the pieces of information that the API makes
available.

It also reads better: "Does the document's security policy allow eval?" ->
`document.securityPolicy.allowsEval()`. Nice.

[1]: http://lists.w3.org/Archives/Public/public-webappsec/2012Jun/0003.html
csp-specification.dev.html
     1.1 --- a/csp-specification.dev.html	Thu Jul 12 21:30:56 2012 -0700
     1.2 +++ b/csp-specification.dev.html	Tue Jul 17 13:35:20 2012 -0500
     1.3 @@ -652,10 +652,10 @@
     1.4        </section>
     1.5  
     1.6        <section>
     1.7 -        <h3>Script Interfaces</h3>
     1.8 +        <h3>Script Interfaces (Experimental)</h3>
     1.9  
    1.10          <section>
    1.11 -          <h4>Document (Experimental)</h4>
    1.12 +          <h4>Document</h4>
    1.13  
    1.14            <dl title="partial interface Document" class="idl">
    1.15              <dt>readonly attribute SecurityPolicy securityPolicy</dt>
    1.16 @@ -664,34 +664,143 @@
    1.17          </section>
    1.18  
    1.19          <section>
    1.20 -          <h4>SecurityPolicy (Experimental)</h4>
    1.21 +          <h4>SecurityPolicy</h4>
    1.22  
    1.23 -          <p>Let the <var>active CSP policies</var> be the set of CSP policies
    1.24 +          <p>Let the <dfn>active CSP policies</dfn> be the set of CSP policies
    1.25            the user agent is currently enforcing for the associated
    1.26            document.</p>
    1.27  
    1.28            <dl title="interface SecurityPolicy" class="idl">
    1.29 -            <dt>readonly attribute boolean active</dt>
    1.30 -            <dd>Whether the set of <var>active CSP policies</var> is
    1.31 -            non-empty.</dd>
    1.32 +            <dt>readonly attribute DOMString[] reportURIs</dt>
    1.33 +            <dd>An array consisting of the union of the <var>set of report
    1.34 +            URIs</var> for all the <a href="#dfn-active-csp-policies">active CSP
    1.35 +            policies</a>.</dd>
    1.36  
    1.37 -            <dt>readonly attribute DOMString[] reportURIs</dt>
    1.38 -            <dd>An array consisting of the union of the <a
    1.39 -            href="#dfn-set-of-report-uris">set of report URIs</a> for all the
    1.40 -            <var>active CSP policies</var>.</dd>
    1.41 +            <dt>bool allowsEval()</dt>
    1.42 +            <dd>Returns the logical <code>and</code> of whether the source
    1.43 +            expression <code>'unsafe-eval'</code> is present in the
    1.44 +            <a href="#dfn-allowed-script-sources">allowed script sources</a>
    1.45 +            of each of the <a href="#dfn-active-csp-policies">active CSP
    1.46 +            policies</a>.</dd>
    1.47  
    1.48 -            <dt>bool isWhitelisted(DOMString directive, DOMString value)</dt>
    1.49 -            <dd>Returns <code>true</code> if the set of <var>active CSP
    1.50 -            policies</var> is empty or if none of the <var>active CSP
    1.51 -            policies</var> contains a directive named <var>directive</var>.
    1.52 -            Otherwise, returns the logical <code>and</code> of whether
    1.53 -            the given <var>value</var> "is whitelisted" for the given directive
    1.54 -            in each of the <var>active CSP policies</var> which contain the
    1.55 -            directive.  (See the individual directives in the following section
    1.56 -            for details about what "is whitelisted" means for each
    1.57 -            directive.)</dd>
    1.58 +            <dt>bool allowsInlineScript()</dt>
    1.59 +            <dd>Returns the logical <code>and</code> of whether the source
    1.60 +            expression <code>'unsafe-inline'</code> is present in the
    1.61 +            <a href="#dfn-allowed-script-sources">allowed script sources</a>
    1.62 +            of each of the <a href="#dfn-active-csp-policies">active CSP
    1.63 +            policies</a>.</dd>
    1.64 +
    1.65 +            <dt>bool allowsInlineStyle()</dt>
    1.66 +            <dd>Returns the logical <code>and</code> of whether the source
    1.67 +            expression <code>'unsafe-inline'</code> is present in the
    1.68 +            <a href="#dfn-allowed-style-sources">allowed style sources</a>
    1.69 +            of each of the <a href="#dfn-active-csp-policies">active CSP
    1.70 +            policies</a>.</dd>
    1.71 +
    1.72 +            <dt>bool allowsConnectionTo(DOMString url)</dt>
    1.73 +            <dd>Returns the logical <code>and</code> of whether the provided
    1.74 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
    1.75 +            <a href="#dfn-allowed-connection-targets">allowed connection
    1.76 +            targets</a> of each of the <a href="#dfn-active-csp-policies">active
    1.77 +            CSP policies</a>.</dd>
    1.78 +
    1.79 +            <dt>bool allowsFontFrom(DOMString url)</dt>
    1.80 +            <dd>Returns the logical <code>and</code> of whether the provided
    1.81 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
    1.82 +            <a href="#dfn-allowed-font-sources">allowed font sources</a>
    1.83 +            of each of the <a href="#dfn-active-csp-policies">active CSP
    1.84 +            policies</a>.</dd>
    1.85 +
    1.86 +            <dt>bool allowsFrameFrom(DOMString url)</dt>
    1.87 +            <dd>Returns the logical <code>and</code> of whether the provided
    1.88 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
    1.89 +            <a href="#dfn-allowed-frame-sources">allowed frame sources</a>
    1.90 +            of each of the <a href="#dfn-active-csp-policies">active CSP
    1.91 +            policies</a>.</dd>
    1.92 +
    1.93 +            <dt>bool allowsImageFrom(DOMString url)</dt>
    1.94 +            <dd>Returns the logical <code>and</code> of whether the provided
    1.95 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
    1.96 +            <a href="#dfn-allowed-image-sources">allowed image sources</a>
    1.97 +            of each of the <a href="#dfn-active-csp-policies">active CSP
    1.98 +            policies</a>.</dd>
    1.99 +
   1.100 +            <dt>bool allowsMediaFrom(DOMString url)</dt>
   1.101 +            <dd>Returns the logical <code>and</code> of whether the provided
   1.102 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
   1.103 +            <a href="#dfn-allowed-media-sources">allowed media sources</a>
   1.104 +            of each of the <a href="#dfn-active-csp-policies">active CSP
   1.105 +            policies</a>.</dd>
   1.106 +
   1.107 +            <dt>bool allowsObjectFrom(DOMString url)</dt>
   1.108 +            <dd>Returns the logical <code>and</code> of whether the provided
   1.109 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
   1.110 +            <a href="#dfn-allowed-object-sources">allowed object sources</a>
   1.111 +            of each of the <a href="#dfn-active-csp-policies">active CSP
   1.112 +            policies</a>.</dd>
   1.113 +
   1.114 +            <dt>bool allowsScriptFrom(DOMString url)</dt>
   1.115 +            <dd>Returns the logical <code>and</code> of whether the provided
   1.116 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
   1.117 +            <a href="#dfn-allowed-script-sources">allowed script sources</a>
   1.118 +            of each of the <a href="#dfn-active-csp-policies">active CSP
   1.119 +            policies</a>.</dd>
   1.120 +
   1.121 +            <dt>bool allowsStyleFrom(DOMString url)</dt>
   1.122 +            <dd>Returns the logical <code>and</code> of whether the provided
   1.123 +            <var>url</var> <a href="#matches-a-source-list">matches</a> the
   1.124 +            <a href="#dfn-allowed-style-sources">allowed style sources</a>
   1.125 +            of each of the <a href="#dfn-active-csp-policies">active CSP
   1.126 +            policies</a>.</dd>
   1.127 +
   1.128 +            <dt>bool isActive()</dt>
   1.129 +            <dd>Returns <code>true</code> if the set of
   1.130 +            <a href="#dfn-active-csp-policies">active CSP policies</a> is
   1.131 +            non-empty, and <code>false</code> otherwise.</dd>
   1.132            </dl>
   1.133          </section>
   1.134 +        <section class="informative">
   1.135 +          <h4>Usage</h4>
   1.136 +          <p>The script interface described here serves as a feature detection
   1.137 +          API that developers can use in order to make intelligent decisions
   1.138 +          about code that executes on a page based on the page's active
   1.139 +          policy. This is especially important for developers of libraries or
   1.140 +          frameworks which are meant to be used on a variety of sites in
   1.141 +          unknown contexts.</p>
   1.142 +          <p>A few use-cases follow for illustration:</p>
   1.143 +          <ul>
   1.144 +            <li>
   1.145 +              <p><strong>Does the user agent support CSP?</strong></p>
   1.146 +              <pre>var isCSPSupported = !!document.securityPolicy;</pre>
   1.147 +            </li>
   1.148 +            <li>
   1.149 +              <p><strong>Is a policy active on the current page?</strong> If
   1.150 +              not, perhaps one should be injected via the
   1.151 +              <a href="#html-meta-element--experimental">(experimental)
   1.152 +              <code>meta</code> element</a>.</p>
   1.153 +              <pre>var isCSPActive = document.securityPolicy.isActive();</pre>
   1.154 +            </li>
   1.155 +            <li>
   1.156 +              <p><strong>Can I use <code>new Function();</code> or
   1.157 +              <code>eval()</code>?</strong> Some libraries use these dangerous
   1.158 +              methods for performance optimizations. If they are unavailable,
   1.159 +              the library could gracefully fall back to a less performant (but
   1.160 +              safer) mechanism.</p>
   1.161 +              <pre>var isEvalAvailable = document.securityPolicy.allowsEval();</pre>
   1.162 +            </li>
   1.163 +            <li>
   1.164 +              <p><strong>Can I use <var>library X</var>, hosted on a
   1.165 +              third-party server?</strong> Analytics packages are a good
   1.166 +              example of such third-party packages that a developer might want
   1.167 +              to include if they're allowed. For a library that's hosted on
   1.168 +              <code>https://cdn.example.com/</code> and that includes images
   1.169 +              from <code>https://img.example.com/</code>, the following would
   1.170 +              allow a developer to determine its availability.</p>
   1.171 +              <pre>var isLibraryAvailable = (document.securityPolicy.allowsScriptFrom('https://cdn.example.com/path/to/library.js')
   1.172 +                          &amp;&amp; document.securityPolicy.allowsImageFrom('https://img.example.com/path/to/img.png'));</pre>
   1.173 +            </li>
   1.174 +          </ul>
   1.175 +        </section>
   1.176        </section>
   1.177      </section>
   1.178