CSP 1.1: Adding `plugin-types` usage information.
authorMike West <mkwst@google.com>
Sat, 21 Jul 2012 20:44:04 -0500
changeset 1425e6fdb226239
parent 141 c7b95bd9d268
child 143 4700cb782553
CSP 1.1: Adding `plugin-types` usage information.

This patch adds a non-normative "Usage" section to the `plugin-types` directive
description, and makes a single substantive change: user agents are to treat
invalid `plugin-types` directive values (e.g. `plugin-types;` or
`plugin-types malformed/mime//type/;` as referring to the empty set of types.
This continues the trend of erring towards failing loudly and securely rather
than ignoring invalid directives.
csp-specification.dev.html
     1.1 --- a/csp-specification.dev.html	Thu Jul 19 11:11:59 2012 -0500
     1.2 +++ b/csp-specification.dev.html	Sat Jul 21 20:44:04 2012 -0500
     1.3 @@ -1404,8 +1404,9 @@
     1.4          <h4><code>plugin-types</code> (Experimental)</h4>
     1.5  
     1.6          <p>The <code>plugin-types</code> restricts the set of plugins that can
     1.7 -        be invoked by the protected resource.  The syntax for the name and
     1.8 -        value of the directive are described by the following ABNF grammar:</p>
     1.9 +        be invoked by the protected resource by limiting the types of resources
    1.10 +        that can be embedded.  The syntax for the name and value of the
    1.11 +        directive are described by the following ABNF grammar:</p>
    1.12  
    1.13  <pre>
    1.14  directive-name    = "plugin-types"
    1.15 @@ -1413,8 +1414,10 @@
    1.16  media-type        = &lt;type from RFC 2045&gt; "/" &lt;subtype from RFC 2045&gt;
    1.17  </pre>
    1.18  
    1.19 -        <p>The term <dfn>allowed plugin media types</dfn> refers to the
    1.20 -        <code>plugin-types</code> directive's value, <a
    1.21 +        <p>If the <code>plugin-types</code> directive's value is empty,
    1.22 +        consists solely of whitespace, or contains invalid characters, let the
    1.23 +        <dfn>allowed plugin media types</dfn> be the empty set. Otherwise, the
    1.24 +        term refers to the <code>plugin-types</code> directive's value, <a
    1.25          href="http://www.whatwg.org/specs/web-apps/current-work/#split-a-string-on-spaces">split
    1.26          on spaces</a>.</p>
    1.27  
    1.28 @@ -1424,11 +1427,32 @@
    1.29              href="http://www.whatwg.org/specs/web-apps/current-work/#plugin">plugin</a>
    1.30              for the protected resource to handle a resource whose media type is
    1.31              not contained in the list of <a href="#dfn-allowed-plugin-media-types">allowed plugin media types</a>,
    1.32 -            instead the user agent MUST act as the plugin reported an error
    1.33 -            (which will cause the user agent to display the <a
    1.34 +            instead the user agent MUST act as though the plugin reported an
    1.35 +            error (which will cause the user agent to display the <a
    1.36              href="http://www.whatwg.org/specs/web-apps/current-work/#fallback-content">fallback
    1.37              content</a>).</li>
    1.38          </ul>
    1.39 +
    1.40 +        <section class="informative">
    1.41 +          <h5>Usage</h5>
    1.42 +          <p>The <code>plugin-types</code> directive whitelists a certain set
    1.43 +          of MIME types that can be embedded in a protected resource. For
    1.44 +          example, a site might want to ensure that PDF content loads, but that
    1.45 +          no other plugins can be instantiated. The following directive would
    1.46 +          satisfy that requirement:</p>
    1.47 +          <pre>Content-Security-Policy: plugin-types application/pdf;</pre>
    1.48 +          <p>Resources embedded via an <code>embed</code> or <code>object</code>
    1.49 +          element delivered with an <code>application/pdf</code> content type
    1.50 +          would be rendered in the appropriate plugin; resources delivered with
    1.51 +          some other content type would be blocked. Multiple types can be
    1.52 +          specified, in any order. If the site decided to additionally allow
    1.53 +          Flash at some point in the future, it could do so with the following
    1.54 +          directive:</p>
    1.55 +          <pre>Content-Security-Policy: plugin-types application/pdf application/x-shockwave-flash;</pre>
    1.56 +          <p>Note that wildcards are not accepted in the
    1.57 +          <code>plugin-types</code> directive. Only the resource types
    1.58 +          explicitly listed in the directive will be allowed.</p>
    1.59 +        </section>
    1.60        </section>
    1.61  
    1.62        <section>