Security/CSP/Specification: Difference between revisions

=Specification=

=Definitions=

When CSP is activated for a site, a few <b>[[Security/CSP#Content_Restrictions|base restrictions]]</b> in the browser environment are enforced <i>by default</i> to help provide proper enforcement of any policy defined.  These base restrictions provide general security enhancements by limiting the types of dynamic content that is allowed: generally any script on a site that converts text into code (through the use of <tt>eval()</tt> or similar functions) is disallowed.  Details of the refinements can be found in the [[Security/CSP/Specification#Base_Restrictions|Base Restrictions]] section.

==Policy Language and Syntax==

Note: In the case of policy refinements as described above, it is possible to have two report-uri values; in this situation, a copy of the report is sent to each of the two URIs.

;allow:

* User Agents MUST enforce this directive for all HTTP requests not subject to one of the more specific directives.

** <tt>inline-script</tt> enables inline scripts and <tt>javascript:</tt> URIs

** <tt>eval-script</tt> enables the <tt>eval()</tt> functionality of scripts interpreted by the browser, and allows code to be created from strings in uses of the <tt>new Function()</tt> constructor, <tt>setTimeout</tt> and <tt>setInterval</tt>

;img-src:

* Indicates which sources are valid for images and favicons.

* User Agents MUST subject image requests to the allow directive if img-src is not explicitly specified.  

;media-src:

* Indicates which sources are valid for <tt>audio</tt> and <tt>video</tt> elements.

* User Agents MUST subject audio and video requests to the allow directive if media-src is not explicitly specified.

* Indicates which sources are valid for scripts.

* Regulates which scripts can be loaded via the <tt>src=</tt> attribute.

* User Agents MUST subject script requests to the allow directive if script-src is not explicitly specified.

;object-src:

* Indicates which sources are valid for <tt>object</tt>, <tt>embed</tt>, and <tt>applet</tt> elements.

* User Agents MUST subject object, embed, and applet requests to the allow directive if object-src is not explicitly specified.

;frame-src:

* Indicates which sources are valid for <tt>frame</tt> and <tt>iframe</tt> elements.

* User Agents MUST subject frame requests to the allow directive if frame-src is not explicitly specified.

;font-src:

* Indicates which sources are valid for <tt>@font-src</tt> CSS loads.

* User Agents MUST subject requests caused by <tt>@font-src</tt> to the allow directive if font-src is not explicitly specified.

;xhr-src:

* Indicates which sources are valid for <tt>XMLHttpRequest</tt> connections.

* User Agents MUST subject requests caused by <tt>XMLHttpRequest</tt> to the allow directive if xhr-src is not explicitly specified.

;frame-ancestors:

* Indicates which sources are valid <b>ancestors</b> for embedding the protected resource via <tt>object</tt>, <tt>frame</tt> and <tt>iframe</tt> tags.  An ancestor is any HTML document between the protected resource and the top of the window frame tree; for example, if A embeds B which embeds C, both A and B are <b>ancestors</b> of C.  If A embeds both B and C, B is <i>not</i> an ancestor of C, but A still <i>is</i>.

* All web pages that are ancestors of the protected content must be indicated by the value of this directive.  For example, if A embeds B which embeds C, and C defines a <tt>frame-ancestors</tt> as "B,C" then C is not rendered as a subframe.

* Answers the question: "Which sites may embed this resource?"

* User Agents MUST always render the protected document if frame-ancestors is not explicitly specified.

* Note that this directive addresses the [http://jeremiahgrossman.blogspot.com/2008/10/clickjacking-web-pages-can-see-and-hear.html clickjacking] threat, but not [http://www.cgisecurity.com/articles/csrf-faq.shtml CSRF]

* Indicates which sources are valid for externally linked stylesheets.

* User Agents MUST always allow inline stylesheets and style attributes of HTML tags.

* User Agents MUST subject stylesheet requests to the allow directive if style-src is not explicitly specified.

;report-uri:

* Instructs the browser where to send a report when CSP is violated.

* Acceptable report URIs MUST use the scheme and port as the protected content, and the [http://publicsuffix.org public suffix] and most general DNS label of the protected content and the report URI must match.  For example www.foo.co.uk and reports.foo.co.uk, but not reports.bar.co.uk.  Relative URIs are acceptable, and are resolved within the same scheme, host and port as the document served with the CSP.   

* User Agents MUST send violation reports to any acceptable URIs in this directive.  Details about the information provided in violation reports are found in the [[#Violation Report Syntax|Violation Report Syntax]] section.

* User Agents MUST ignore report URIs that don't match the public suffix and base host match requirements.  User Agents SHOULD log one error to an error console.  User Agents MUST then continue CSP enforcement as if the report URI were not specified.  

;policy-uri:

If a port is not specified as the source expression, a User Agent MUST use the default port for the source's scheme (whether it is inherited or explicitly specified in the source expression).

====Host-less Schemes====

  <policy>            ::= <allow-directive>";"<directive-list>

   

   

  <directive-list>    ::= <empty> | <directive>";"<directive-list>

   

  <ldh-str>          ::= <let-dig-hyp>

   

  <let-dig-hyp>      ::= <letter> | <digit> | "-"

==Violation Report Syntax==

User Agents MUST notify any provided report-uri when its containing policy is violated. These reports contain information about the protected resource and the violating content, and MUST be transmitted to any specified <tt>report-uri</tt>s via HTTP POST if available in the employed scheme, otherwise User Agents MUST choose an appropriate "submit" method.   

; <tt>request</tt> : HTTP request line of the resource whose policy is violated (including method, resource, path, HTTP version)

; <tt>original-policy</tt> : The original policy as served in the X-Content-Security-Policy HTTP header (or if there were multiple headers, a comma separated list of the policies)

   

===Violation Report Sample===

=User Agent Behavior=

</font>

<font color="#060">

** Scripts imported from external files whose sources are allowed by the protected document's policy AND are served with a Content-Type of <tt>application/javascript</tt> or <tt>application/json</tt>.

</font>

</font>

<font color="#060">

** Functions declared using the function operator, e.g. function f() { some_code }, or var f = function() { some_code }

** calls to setTimeout using a Function argument, e.g. setTimeout(myFunc, 1000)

</font>

<font color="#060">

** data: URIs when used as a source for inline content explicitly allowed by the protected document's policy.  

</font>

</font>

<font color="#060">

** XBL bindings loaded via the chrome: or resource: protocols

</font>

;Unrecognized <tt>options</tt> token: If an unrecognized token is present in the <tt>options</tt> directive value, the User Agent MUST ignore it and SHOULD report a warning message to the Error Console stating the unrecognized token.

;Other Parsing Errors: Any other parsing errors not covered here SHOULD cause the User Agent to enforce the policy "allow 'none'".  If such a case should arise, the User Agent SHOULD report a descriptive error to the Error Console describing the problem.

== Report-Only mode ==

Report-only mode is enabled by specifying a policy in the <tt>X-Content-Security-Policy-Report-Only</tt> header instead of the <tt>X-Content-Security-Policy</tt> header.   

=HTTP Server Behavior=