CSP 1.1: Adding a non-normative "Usage" section to `script-nonce`.
authorMike West <mkwst@google.com>
Tue, 17 Jul 2012 22:10:42 -0500
changeset 139b574fbf95a50
parent 138 bff58d373917
child 140 9a3ee7b957e4
CSP 1.1: Adding a non-normative "Usage" section to `script-nonce`.

The section explains the expected usage of the directive at a higher level,
targeting web developers as opposed to browser implementors.
csp-specification.dev.html
     1.1 --- a/csp-specification.dev.html	Tue Jul 17 13:35:20 2012 -0500
     1.2 +++ b/csp-specification.dev.html	Tue Jul 17 22:10:42 2012 -0500
     1.3 @@ -1292,9 +1292,9 @@
     1.4          <h4><code>script-nonce</code> (Experimental)</h4>
     1.5  
     1.6          <p>The <code>script-nonce</code> directive restricts script execution
     1.7 -        by requiring the presence of the specified nonce. The syntax for the
     1.8 -        name and value of the directive are described by the following ABNF
     1.9 -        grammar:</p>
    1.10 +        by requiring the presence of the specified nonce on <code>script</code>
    1.11 +        elements. The syntax for the name and value of the directive are
    1.12 +        described by the following ABNF grammar:</p>
    1.13  
    1.14  <pre>
    1.15  directive-name    = "script-nonce"
    1.16 @@ -1335,6 +1335,47 @@
    1.17          </p>
    1.18  
    1.19          <section class="informative">
    1.20 +          <h5>Usage</h5>
    1.21 +          <p>The <code>script-nonce</code> directive is intended to allow
    1.22 +          developers to strictly specify exactly which <code>script</code>
    1.23 +          elements on a page were intentionally included for execution. This
    1.24 +          is particularly useful when <code>'unsafe-inline'</code> is accepted
    1.25 +          as a valid <code>script-src</code> (though any site is better off
    1.26 +          avoiding inline script completely), but can also serve as a layer of
    1.27 +          protection against the execution of otherwise trusted resources in a
    1.28 +          context where they might be unexpected and potentially dangerous.</p>
    1.29 +
    1.30 +          <p>Usage is straightforward. For <em>each</em> request, the server
    1.31 +          generates a unique value at random, and includes it in the CSP
    1.32 +          header:</p>
    1.33 +
    1.34 +          <pre>Content-Security-Policy: script-nonce <em>random-value</em>;</pre>
    1.35 +
    1.36 +          <p>This same value is then applied as a <code>nonce</code> attribute
    1.37 +          to each <code>script</code> tag that ought to be executed.</p>
    1.38 +
    1.39 +          <pre>&lt;script src="/path/to/script.js" nonce="<em>random-value</em>"&gt;&lt;/script&gt;
    1.40 +&lt;script nonce="<em>random-value</em>"&gt;
    1.41 +  alert("I execute! Hooray!");
    1.42 +&lt;/script&gt;
    1.43 +&lt;script&gt;
    1.44 +  alert("I don't execute. Boo!");
    1.45 +&lt;/script&gt;
    1.46 +</pre>
    1.47 +
    1.48 +          <p>Note that the nonce's value is <em>not</em> a hash or signature
    1.49 +          that verifies the contents of the script resources. It's quite simply
    1.50 +          a random string that informs the user agent which scripts were
    1.51 +          intentionally included in the page.</p>
    1.52 +
    1.53 +          <p><code>script</code> elements containing the proper nonce execute.
    1.54 +          <code>script</code> elements that don't, don't. Even if an attacker
    1.55 +          is able to inject markup into the protected resource, the attack
    1.56 +          will be blocked by the attacker's inability to guess the random
    1.57 +          value.</p>
    1.58 +        </section>
    1.59 +
    1.60 +        <section class="informative">
    1.61            <h5>Interaction with the <code>script-src</code> directive</h5>
    1.62            <p>The <code>script-nonce</code> and <code>script-src</code>
    1.63            directives' restrictions on code execution are non-exclusive: script