This document defines a directive for the Content Security Policy 1.0 mechanism to allow Web application developers to declare a set of protections for a web resource to help prevent malicious obscuring or re-contextualizing of the resource's user interface when it is displayed in an embedded context. The document also defines a set of heuristics for Web user agents to implement these protections and a reporting mechanism for when they are triggered.
Portions of the technology described in this document were developed as part of the X-Frame-Options header.
Portions of the technology described in this document were developed and implemented in the ClearClick module of the Mozilla Firefox add-on NoScript.
This document uses the syntax and mechanism of the Content Security Policy 1.0 and defines a new directive to convey anti-clickjacking policy.
In addition to the documents in the W3C Web Application Security working group, the work on this document is also informed by the work of the IETF websec working group, particularly that working group's requirements document: draft-hodges-websec-framework-reqs.
This document defines new directives for Content Security Policy 1.0 to allow applications to mitigate some of the risks of User Interface Redressing vulnerabilities that can lead to fraud.
Content Security Policy is a declarative policy that lets the authors (or server administrators) of a web application restrict from where an application can load resources. The intent and implementation of the directive defined in this document differs in that respect from other directives defined in CSP 1.0. A user agent may implement the directives of CSP 1.0 independently from the directives in this specification, but the policy conveyance mechanism for the directives in this specicification is described in CSP 1.0. Application authors should transmit the directives in this specification as part of a single, complete Content Security Policy, as indicated by that specification.
Content Security Policy (CSP) is not intended as a first line of defense against content injection vulnerabilities. Instead, CSP is best used as defense-in-depth, to reduce the harm caused by content injection attacks.
The anti-clickjacking directive can often be applied to existing applications with few or no changes, but the hueristic hints supplied by the policy may require considerable experimental fine-tuning to achieve an acceptable error rate.
This specification obsoletes X-Frame-Options. Resources may supply an X-Frame-Options header in addition to a Content-Security-Policy header to indicate policy to user agents that do not implement the directives in this specification. A user agent that understands the directives in this document should ignore the X-Frame-Options header, when present, if Embedding Safety directives are also present in a Content-Security-Policy header. This is to allow resources to only be embedded if the mechanisms described in this specification are enforced, and more restrictive X-Frame-Options policies applied otherwise.
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("MUST", "SHOULD", "MAY", etc) used in introducing the algorithm.
A conformant user agent is one that implements all the requirements listed in this specification that are applicable to user-agents.
A conformant server is one that implements all the requirements listed in this specification that are applicable to servers.
This section defines several terms used throughout the document.
The term security policy, or simply policy, for the purposes of this specification refers to either:
The security policies defined by this document are applied by a user agent on a per-resource representation basis. Specifically, when a user agent receives a policy along with the representation of a given resource, that policy applies to that resource representation only. This document often referes to that resource representation as the protected resource.
A server transmits its security policy for a particular resource as
a collection of directives, such as default-src
'self', each of which controls a specific set of privileges for
a document rendered by the user agent. More details are provided in the
directives section.
A directive consists of a directive name, which indicates the privileges controlled by the directive, and a directive value, which specifies the restrictions the policy imposes on those privileges.
The term origin is defined in the Origin specification. [ORIGIN]
The term URI is defined in the URI specification. [[!URI]]
The <script>, <object>, <embed>,
<img>, <video>, <audio>,
<link>, <frame> and <iframe>
elements are defined in the HTML5 standard. [[!HTML5]].
The <applet> element is defined in the HTML 4.01 standard. [[!HTML401]].
The @font-face CSS rule is defined in the CSS Fonts Module Level 3 standard.
[[!CSS3FONT]]
The XMLHttpRequest object is defined in the XMLHttpRequest
standard. [[!XMLHTTPREQUEST]]
The WebSocket object is defined in the WebSocket
standard. [WEBSOCKET].
The EventSource object is defined in the EventSource
standard. [EVENTSOURCE].
The Augmented Backus-Naur Form (ABNF) notation used in this document is specified in RFC 5234. [[!ABNF]]
The following core rules are included by reference, as defined in
[ABNF Appendix B.1]:
ALPHA (letters), DIGIT (decimal
0-9), WSP (white space) and VCHAR (printing
characters).
The OWS rule is used where zero or more linear whitespace octets might appear. OWS SHOULD either not be produced or be produced as a single SP. Multiple OWS octets that occur within field-content SHOULD either be replaced with a single SP or transformed to all SP octets (each octet other than SP replaced with SP) before interpreting the field value or forwarding the message downstream.
OWS = *( SP / HTAB / obs-fold )
; "optional" whitespace
obs-fold = CRLF ( SP / HTAB )
; obsolete line folding
This section describes the content security policy directives introduced in this specification.
embed-ancestorsTODO: Coordinate with the IETF websec Working Group.
The embed-options directive indicates whether the
user-agent should embed the resource using a frame,
iframe, object or embed tag,
or equivalent functionality in non-HTML resources.
Resources can use this to avoid many UI Redressing attacks by ensuring
they are not embedded into other sites.
This directive replicates some of the functionality of the
X-Frame-Options header. The syntax for the name and
value of the directive are described by the following ABNF grammar:
directive-name = "embed-ancestors" directive-value = source-list
Unlike policies defined in Content Security Policy 1.0, the
embed-ancestors directives is not subject to the
default-src directive. If this directive is not
explicitly stated in the policy its value is assumed to be "*".
If 'deny' is present in the source-list, the resource
cannot be displayed in an embedded context, regardless of the origin attempting
to do so, and all other members of the source-list are ignored. This
provides functionality equivalent to the DENY value of
the X-Frame-Options header.
If 'deny' is not present the source-list indicates
which origins are valid ancestors for the resource.
An ancestor is any resource 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 ancestors of C. If A embeds both B and C,
B is not an ancestor of C, but A still is.
The 'self' source indicates that content of the same-origin
as the protected resource may embed it. This provides functionality
equivalent to the SAMEORIGIN value of the
X-Frame-Options header.
click-protectionThe click-protection directive, if present,
instructs the user agent to apply the heuistic clickjacking
protections described in Section XXX to click
and drag-and-drop events delivered before they are delivered
to the resouce in an embedded context.
ISSUE: Need some optimization language here. e.g. If the resource is not embedded (it is topmost in the user agent rendering context) or if all ancestors are same origin this token may be ignored. TODO: this still allows attacks with multiple windows in environments where that is possible (traditional desktop OS) but to defend against this the user-visible screenshot would have to be defined in terms of the OS, not the user agent.
directive-name = "click-protection" directive-value = "block" / "deliver"
A value of block indicates the user agent should
not deliver the event to the resource if the click protection
heuristic is triggered.
A value of deliver indicates the user agent should
deliver the event to the resource, even if the click protection
heuristic is triggered.
If a report-uri is present, triggering of the click protection heuristic MUST always generate a report, whether the event is delivered or not.
User agents SHOULD NOT prompt the user when the click protection heuristic is triggered.
ISSUE: is it worth having a "deliver" option, or should this just always be part of a report-only policy?
click-protection-hintsThe click-protection-hints directive allows a
resource to provide hints to the click-protection
heuristics for greater accuracy.
directive-name = "click-protection-hints" directive-value = ["tolerance=" num-val] ["viewport-height=" num-val] ["viewport-width=" num-val] ["ui-delay=" num-val]
If the policy does not contain explicit click-protection-hints
or any of the optional values are absent, the user agent should apply default
values as described in Section XXX. A user agent MAY ignore
any or all values in click-protection-hints.
tolerance is a numeric value from 0-99 that defines the
threshold at which the screenshot comparision procedure triggers the
click protection heuristic. A value of 0 indicates that no difference
between the two images is permitted. A value of 99 provides little
to no practical protection.
viewport-height is a numeric value that defines the height of
the viewport to be used for performing the screenshot comparision.
viewport-width is a numeric value that defines the width of
the viewport to be used for performing the screenshot comparision.
ui-delay is a numeric value that specifies the delay time, in
milliseconds, used in the click protection heuristic.
protected-id ??? does it make sense to allow protections to apply
to a named element in the DOM, instead of a viewport window?
This section is non-normative. The algorithm described here can be implemented mostly in terms of HTML5 constructs, but requries the ability to monitor and intercept actions in the rendering of a resource and delivery of events to that resource. User agents may apply equivalent protections using means more optimized for their implementation details, may ignore recommendations where the browsing environment eliminates certain classes of attack, (e.g. cursor sanity check in a touch-only environment) or may implement some features in terms of the underlying operating system or platform rather than directly in the user agent.
viewport-height and viewport-width properties of
click-protection-hints) screenshots of the region centered around the DOM
element which is about to receive the event: one from its owner document's
"point of view" (unobstructed by definition),
the other from the topmost window's. In the plugin content case, we ensure the former
"screenshot" contains the element itself only. If the number of the pixels which are
different between the screenshots don't exceed a certain configurable tolerance rate
(default 18%, or as set by the tolerance property of
click-protection-hints), return. Otherwise we tentatively assume the
DOM element our user is interacting with has been obstructed or obscured by a
UI Redressing attempt.
CBC: the screenshots are taken by using the CanvasRenderingContext2D.drawWindow()
method11, which is a Mozilla-proprietary extension of the HTML 5 Canvas API available to
privileged code only, allowing the content of DOM windows to be drawn on a canvas
surface exactly as rendered on the screen. The rest of this phase relies on cross-browser
canvas features, instead, such as pixel grabbing and data URL serialization.
This section provides some sample use cases and accompanying security policies.
Example 1: A server wishes to load resources only form its own origin:
Content-Security-Policy: default-src 'self'
Example 2: An auction site wishes to load images from any URI, plugin content from a list of trusted media providers (including a content distribution network), and scripts only from a server under its control hosting sanitized ECMAScript:
Content-Security-Policy: default-src 'self'; img-src *;
object-src media1.example.com media2.example.com *.cdn.example.com;
script-src trustedscripts.example.com
Example 3: Online banking site wishes to ensure that all of the content in its pages is loaded over TLS to prevent attackers from eavesdropping on insecure content requests:
Content-Security-Policy: default-src https: 'unsafe-inline' 'unsafe-eval'
This section contains an example violation report the user agent might sent to a server when the protected resource violations a sample policy.
In the following example, a document from
http://example.org/page.html was rendered with the
following CSP policy:
default-src 'self'; report-uri http://example.org/csp-report.cgi
The document loaded an image from
http://evil.example.com/image.png, violating the
policy.
{
"csp-report": {
"document-uri": "http://example.org/page.html",
"referrer": "http://evil.example.com/haxor.html",
"blocked-uri": "http://evil.example.com/image.png",
"violated-directive": "default-src 'self'",
"original-policy": "default-src 'self'; report-uri http://example.org/csp-report.cgi"
}
}
XXX TODO
XXX TODO suggestions on back-end anti-fraud here and use of unique, per-transaction report-uris with information about targets encoded, and use of report-only to collect possible fraud data without blocking transactions.
The permanent message header field registry (see [RFC3864]) should be updated with the following registrations:
Header field name: Content-Security-Policy
Applicable protocol: http
Status: standard
Author/Change controller: W3C
Specification document: this specification (See Content-Security-Policy
Header Field)
Header field name: Content-Security-Policy-Report-Only
Applicable protocol: http
Status: standard
Author/Change controller: W3C
Specification document: this specification (See Content-Security-Policy-Report-Only
Header Field)