servo/tests/wpt/web-platform-tests/content-security-policy
2019-04-11 00:31:30 -04:00
..
base-uri Update web-platform-tests to revision 155daf0c385420faf208b8bd5e319e244ec7f9cc 2018-05-28 11:37:21 -04:00
blob Update web-platform-tests to revision a806d658df3bcc3f05675ad8d08a6e109177c6b0 2018-09-05 22:56:05 -04:00
child-src Update web-platform-tests to revision 14cfa4d648cc1c853b4153268df672d21425f8c1 2017-10-30 18:26:08 -04:00
connect-src Update web-platform-tests to revision 8f8ff0e2a61f2a24996404921fe853cb1fd9b432 2018-09-17 22:59:59 -04:00
default-src Update web-platform-tests to revision a806d658df3bcc3f05675ad8d08a6e109177c6b0 2018-09-05 22:56:05 -04:00
embedded-enforcement Update web-platform-tests to revision c792ea26624bde49b72afce348de07ab72fb9ad7 2018-08-13 23:36:02 -04:00
font-src Update web-platform-tests to revision 8a2ceb5f18911302b7a5c1cd2791f4ab50ad4326 2017-10-12 12:36:21 -04:00
form-action Update web-platform-tests to revision 2d42384cf21efd71843295d319c1bab85b3acf4a 2019-01-11 22:07:24 -05:00
frame-ancestors Update web-platform-tests to revision 4f397167b4ed552a02201c92d363cfaecfe2c7f0 2018-04-27 17:36:30 +02:00
frame-src Update web-platform-tests to revision 14cfa4d648cc1c853b4153268df672d21425f8c1 2017-10-30 18:26:08 -04:00
generic Update web-platform-tests to revision e3d0146264093a389148cc555ee9be69bd75719b 2019-04-11 00:31:30 -04:00
img-src Update web-platform-tests to revision 14cfa4d648cc1c853b4153268df672d21425f8c1 2017-10-30 18:26:08 -04:00
inheritance Update web-platform-tests to revision 614fd870e47c9f4e76291e5af4e32b676c0acac0 2018-12-04 22:20:33 -05:00
inside-worker Update web-platform-tests to revision 58eb04cecbbec2e18531ab440225e38944a9c444 2017-04-22 14:17:10 +02:00
media-src Update web-platform-tests to revision 14cfa4d648cc1c853b4153268df672d21425f8c1 2017-10-30 18:26:08 -04:00
meta Update web-platform-tests to revision a806d658df3bcc3f05675ad8d08a6e109177c6b0 2018-09-05 22:56:05 -04:00
navigate-to Update web-platform-tests to revision 615bb572c95add74ca4fb9fed4af5269a49cf4ef 2018-11-06 22:43:16 -05:00
navigation Update web-platform-tests to revision f26f3ca338953d0c2e8b62c97623f0f0eea430be 2019-01-29 22:36:03 -05:00
nonce-hiding Update web-platform-tests to revision 155daf0c385420faf208b8bd5e319e244ec7f9cc 2018-05-28 11:37:21 -04:00
object-src Update web-platform-tests to revision c2b30ef30749b6a8f2cc832761dfe011e63d5e94 2018-10-05 23:00:35 -04:00
plugin-types Update web-platform-tests to revision 614fd870e47c9f4e76291e5af4e32b676c0acac0 2018-12-04 22:20:33 -05:00
prefetch-src Update web-platform-tests to revision 4a5223502fa660ce03e470af6a61c8bc26c5a8ee 2018-04-23 23:10:53 -04:00
reporting Update web-platform-tests to revision 122a4672fa0dc554a6e7528fa3487fd907c792ee 2019-03-23 23:57:08 -04:00
reporting-api Update web-platform-tests to revision 78f764c05c229883e87ad135c7153051a66e2851 2019-03-06 22:39:43 -05:00
sandbox Update web-platform-tests to revision de3ae39cb59880a8245431e7f09817a2a4dad1a3 2018-06-15 23:11:48 -04:00
script-src Update web-platform-tests to revision 615bb572c95add74ca4fb9fed4af5269a49cf4ef 2018-11-06 22:43:16 -05:00
script-src-attr-elem Update web-platform-tests to revision a806d658df3bcc3f05675ad8d08a6e109177c6b0 2018-09-05 22:56:05 -04:00
securitypolicyviolation Update web-platform-tests to revision 687b6cba3385c4c2ca85f44fe072961e651621b5 2019-04-09 00:21:08 -04:00
style-src Update web-platform-tests to revision 122a4672fa0dc554a6e7528fa3487fd907c792ee 2019-03-23 23:57:08 -04:00
style-src-attr-elem Update web-platform-tests to revision a806d658df3bcc3f05675ad8d08a6e109177c6b0 2018-09-05 22:56:05 -04:00
support Update web-platform-tests to revision 122a4672fa0dc554a6e7528fa3487fd907c792ee 2019-03-23 23:57:08 -04:00
svg Update web-platform-tests to revision a806d658df3bcc3f05675ad8d08a6e109177c6b0 2018-09-05 22:56:05 -04:00
unsafe-eval Update web-platform-tests to revision 14cfa4d648cc1c853b4153268df672d21425f8c1 2017-10-30 18:26:08 -04:00
unsafe-hashes Update web-platform-tests to revision 4adce83d1f2b08fa2e92427c4687d0cf535aee53 2019-01-08 22:40:05 -05:00
worker-src Update web-platform-tests to revision 60220357131c65146444da1f54624d5b54d0975d 2018-07-18 22:07:44 +00:00
META.yml Update web-platform-tests to revision 848ceffad26e92d47ffe790ed8b650906b2c2343 2018-08-10 14:45:43 -04:00
README.css Update web-platform-tests to revision 0d318188757a9c996e20b82db201fd04de5aa255 2015-04-03 23:28:54 +01:00
README.html Update web-platform-tests to revision e3d0146264093a389148cc555ee9be69bd75719b 2019-04-11 00:31:30 -04:00

<!DOCTYPE html>
<html>

<head>
    <title>Introduction to Writing Content Security Policy Tests</title>
    <link rel="stylesheet" type="text/css" href="README.css">
    <link rel="stylesheet" type="text/css" href="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.1/styles/default.min.css">
    <script src="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.1/highlight.min.js"></script>
    <script>
        hljs.initHighlightingOnLoad();
    </script>
</head>

<body>
    <h1>Introduction to Writing Content Security Policy Tests</h1>
    <p>The CSP test suite uses the standard W3C testharness.js framework, but there are a few additional things you'll need to do because of the unique way CSP works, even if you're already an expert at writing W3C tests. These tests require the use of the
    <a href="https://github.com/w3c/wptserve">wptserve</a> server (included in the <a href="https://github.com/web-platform-tests/wpt">web-platform-tests repository</a>) to operate correctly.</p>

    <h2>What's different about writing CSP tests?</h2>

    <h3>Headers</h3>
    <p>Content Security Policy is preferentially set through an HTTP header. This means we can't do our tests just as a simple set of HTML+CSS+JS files. Luckily the wptserver framework provides an easy method to add headers to a file.</p>
    <p>If my file is named <span class=code>example.html</span> then I can create a file
        <span class=code>example.html.headers</span> to define the headers that will be served with it. If I need to do template substitutions in the headers, I can instead create a file named <span class=code>example.html.sub.headers</span>.</p>

    <h3>Negative Test Cases and Blocked Script Execution</h3>
    <p>Another interesting feature of CSP is that it <em>prevents</em> things from happening. It even can and prevent script from running. How do we write tests that detect something didn't happen?</p>

    <h3>Checking Reports</h3>
    <p>CSP also has a feature to send a report. We ideally want to check that whenever a policy is enforced, a report is sent. This also helps us with the previous problem - if it is difficult to observe something not happening, we can still check that a report fired.</p>

    <h2>Putting it Together</h2>
    <p>Here's an example of a simple test. (ignore the highlights for now...) This file lives in the
        <span class=code>/content-security-policy/script-src/</span> directory.</p>

    <p class=codeTitle>script-src-1_1.html</p>
    <pre><code class="html">&lt;!DOCTYPE HTML&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;script src=&#39;/resources/testharness.js&#39;&gt;&lt;/script&gt;
    &lt;script src=&#39;/resources/testharnessreport.js&#39;&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;h1&gt;Inline script should not run without &#39;unsafe-inline&#39; script-src directive.&lt;/h1&gt;
    &lt;div id=&#39;log&#39;&gt;&lt;/div&gt;

    &lt;script&gt;
    test(function() {
        asset_unreached(&#39;Unsafe inline script ran.&#39;)},
        &#39;Inline script in a script tag should not run without an unsafe-inline directive&#39;
    );
    &lt;/script&gt;

    &lt;img src=&#39;doesnotexist.jpg&#39; onerror=&#39;test(function() { assert_false(true, &quot;Unsafe inline event handler ran.&quot;) }, &quot;Inline event handlers should not run without an unsafe-inline directive&quot;);&#39;&gt;

    &lt;script async defer src=&#39;../support/checkReport.sub.js?reportField=violated-directive&amp;reportValue=<span class=highlight1>script-src%20%27self%27</span>&#39;&gt;&lt;/script&gt;

&lt;/body&gt;
&lt;/html&gt;
        </code></pre>


    <p>This code includes three tests. The first one in the script block will generate a failure if it runs. The second one, in the onerror handler for the img which does not exist should also generate a failure if it runs. But for a successful CSP implementation, neither of these tests does run. The final test is run by the link to <span class=code>../support/checkReport.sub.js</span>. It will load some script in the page (make sure its not blocked by your policy!) which contacts the server asynchronously and sees if the expected report was sent. This should always run an generate a positive or negative result even if the inline tests are blocked as we expect.</p>

    <p>Now, to actually exercise these tests against a policy, we'll need to set headers. In the same directory we'll place this file:</p>

    <p class=codeTitle>script-src-1_1.html.sub.headers</p>
    <pre><code class="html">
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Cache-Control: post-check=0, pre-check=0, false
Pragma: no-cache
Set-Cookie: <span class=highlight2>script-src-1_1</span>={{$id:uuid()}}; Path=<span class=highlight2>/content-security-policy/script-src/</span>
Content-Security-Policy: <span class=highlight1>script-src 'self'</span>; report-uri  <span class=highlight2>..</span>/support/report.py?op=put&reportID={{$id}}
        </code></pre>
    <p>This sets some headers to prevent caching (just so we are more likely to see our latest changes if we're actively developing this test) sets a cookie (more on that later) and sets the relevant <span class=code>Content-Security-Policy</span> header for our test case.</p>

    <h4>What about those highlights?</h4>
    <p>In production code we don't like to repeat ourselves. For this test suite, we'll relax that rule a little bit. Why? It's easier to have many people contributing "safe" files using some template substitutions than require every file to be executable content like Python or PHP which would require much more careful code review. The highlights show where you have to be careful as you repeat yourself in more limited static files.
    </p>

    <p>The <span class=highlight1>YELLOW</span> highlighted text is information that must be the same between both files for report checking to work correctly. In the html file, we're telling
        <span class=code>checkReport.sub.js</span> to check the value of the <span class=code>
        violated-directive</span> key in the report JSON. So it needs to match (after URL encoding) the directive we set in the header.</p>

    <p>The <span class=highlight2>PINK</span> highlighted text is information that must be repeated from the path and filename of your test file into the headers file. The name of the cookie must match the name of the test file without its extension, the path for the cookie must be correct, and the relative path component to the report-uri must also be corrected if you nest your tests more than one directory deep.</p>

    <h2>Check Your Effects!</h2>
    <p>A good test case should also verify the state of the DOM in addition to checking the report - after all, a browser might send a report without actually blocking the banned content. Note that in a browser without CSP support there will be three failures on the example page as the inline script executes.</p>
    <p>How exactly you check your effects will depend on the directive, but don't hesitate to use script for testing to see if computed styles are as expected, if layouts changed or if certain elements were added to the DOM. Checking that the report also fired is just the final step of verifing correct behavior.</p>

    <p>Note that avoiding inline script is good style and good habits, but not 100% necessary for every test case. Go ahead and specify 'unsafe-inline' if it makes your life easier.</p>

    <h2>Report Existence Only and Double-Negative Tests</h2>
    <p>If you want to check that a report exists, or verify that a report <em>wasn't</em> sent for a double-negative test case,
    you can pass <strong>?reportExists=</strong><em>[true|false]</em> to <span class=code>checkReport.sub.js</span> instead of <strong>reportField</strong> and <strong>reportValue</strong>.</p>

    <h2>How does the magic happen?</h2>
    <p>Behind the scenes, a few things are going on in the framework.</p>
    <ol>
        <li>The {{$id:uuid}} templating marker in the headers file tells the wptserve HTTP server to create a new unique id and assign it to a variable, which we can re-use as {{$id}}.</li>
        <li>We'll use this UUID in two places:
            <ol>
                <li>As a GET parameter to our reporting script, to uniquely identify this instance of the test case so our report can be stored and retrieved.
                </li>
                <li>As a cookie value associated with the filename, so script in the page context can learn what UUID the report was sent under.</li>
            </ol>
        </li>
        <li>The report listener is a simple python file that stashes the report value under its UUID and allows it to be retrieved again, exactly once.</li>
        <li><span class=code>checkReport.sub.js</span> then grabs the current path information and uses that to find the cookie holding the report UUID. It deletes that cookie (otherwise the test suite would overrun the maximum size of a cookie header allowed) then makes an XMLHttpRequest to the report listener to retrieve the report, parse it and verify the contents as per the parameters it was loaded with.</li>
    </ol>

    <p>Why all these gymnastics? CSP reports are delivered by an <em>anonymous fetch</em>. This means that the browser does not process the response headers, body, or allow any state changes as a result. So we can't pull a trick like just echoing the report contents back in a Set-Cookie header or writing them to local storage.</p>

    <p>Luckily, you shouldn't have to worry about this magic much, as long as you get the incantation correct.</p>
</body>

</html>