Abstract
This document defines directives for the Content Security Policy
mechanism to declare a set of input protections for a web resource's user
interface, defines a non-normative set of heuristics for Web user agents to
implement these input protections, and a reporting mechanism for when they are
triggered.
Status of This Document
This section describes the status of this document at the time of its publication. Other
documents may supersede this document. A list of current W3C publications and the latest revision
of this technical report can be found in the W3C technical reports
index at http://www.w3.org/TR/.
This is the First Public Working Draft of the User Interface Safety
Directives for Content Security Policy. [CSP]
Portions of the technology described in this document were originally
developed as part of X-Frame-Options
[XFRAMEOPTIONS],
the ClearClick module of the Mozilla Firefox add-on NoScript,
[CLEARCLICK]
and in the InContext system implemented experimentally in Internet Explorer
[INCONTEXT].
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 was published by the Web Application Security Working Group as a First Public Working Draft.
This document is intended to become a W3C Recommendation.
If you wish to make comments regarding this document, please send them to
public-webappsec@w3.org
(subscribe,
archives).
All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents at
any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the
5 February 2004 W3C Patent Policy.
W3C maintains a public list of any patent disclosures
made in connection with the deliverables of the group; that page also includes instructions for
disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains
Essential Claim(s) must disclose the
information in accordance with section
6 of the W3C Patent Policy.
1. Introduction
This section is non-normative.
This document defines User Interface Safety directives for Content Security
Policy, a mechanism web applications can use to mitigate some of the risks
of User Interface (UI) Redressing [UIREDRESS] (AKA "Clickjacking")
vulnerabilities that can lead to fraudulent actions not intended by the user.
Content Security Policy (CSP) is a declarative policy that lets the authors (or
server administrators) of a web application restrict the behavior of a document, e.g.
the origins where it can load its resources from or the ways it can execute scripts.
This document defines directives to restrict the presentation or the interactivity of
a resource when its interaction with the user may be happening in an ambiguous or deceitful
context due to the spatial and/or temporal contiguity with other content
displayed by the user agent.
A user agent may implement the core directives of CSP independently from the
directives in this specification, but this specification requires the
policy conveyance and reporting mechanisms described in CSP.
The interpretation of terms imported into this document from CSP may
vary depending on the version implemented by the user agent. For example, a
source-expression in Content Security Policy 1.0 is at the
granularity of an origin [ORIGIN]
but may be more granular in future versions of the core Content Security Policy.
Application authors should transmit the directives in this specification
as part of a single, complete Content Security Policy, as indicated by
that specification.
In some UI Redressing attacks (also known as Clickjacking), a malicious web
application presents a user interface of another web application in a
manipulated context to the user, e.g. by partially obscuring the genuine user
interface with opaque layers on top, hence tricking the user to click on a
button out of context.
Existing anti-clickjacking measures including frame-busting [FRAMEBUSTING]
codes and X-Frame-Options cannot be used to protect resources that
are intended to be embedded by arbitrary origins, and are insufficient to
defend against timing-based attacks involving multiple windows instead of multiple
frames.
The User Interface Safety directives encompass the policies defined in X-Frame-Options
and also provide a new mechanism to allow web applications to enable heuristic
input protections for its user interfaces on user agents.
To mitigate UI redressing, for example, a web application can request that
a user interface element should be fully visible for a minimum period of time
before a user input can be delivered.
The User Interface Safety directive can often be applied to existing
applications with few or no changes, but the heuristic 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 User Interface
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.
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
and notes in this specification are non-normative. Everything else in this specification is
normative.
The key words must, must not, required, should, should not, recommended, may,
and optional in this specification are to be interpreted as described in [RFC2119].
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. Treatment of
the input-protection, input-protection-clip and input-protection-selectors directives are at the discretion of the
user agent.
A conformant server is one that implements all the requirements listed in
this specification that are applicable to servers.
2.1 Terminology
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:
- a set of security preferences for restricting the behavior of content
within a given resource, or
- a fragment of text that codifies these preferences.
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 refers 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.
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 term origin is defined in the Origin specification. [ORIGIN]
The term URI is defined in the URI specification. [URI]
The <iframe>, <object>,
<embed>, and <frame>
elements are defined in the HTML5 standard.
[HTML5].
The <applet> element is defined in the HTML 4.01
standard. [HTML401].
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
A selector string is a list of one or more
complex
selectors (see [SELECTORS4], section 3.1) that
may be surrounded by whitespace and matches the
dom_selectors_group production.
dom_selectors_group
: S* [ selectors_group ] S*
;
3. Directives
This section describes the content security policy directives introduced in
this specification.
3.1 frame-options
The frame-options directive indicates whether the
user-agent should embed the resource using a frame,
iframe, object, embed or applet tag,
or equivalent functionality in non-HTML resources.
Resources can use this directive to avoid many UI Redressing attacks by ensuring
they are not embedded into potentially hostile contexts.
The syntax for the name and value of the directive are described by the following ABNF grammar:
directive-name = "frame-options"
directive-value = 'deny' / 'self' ['top-only'] / 1*1<host-source> ['self'] / 1*1<host-source> 'top-only'
Issue 1
Should we use source-expression rather than host-source here? host-source
provides compatibility with current granularity of X-Frame-Options, but a source-expression
will allow seamless forward-evolution to more granular expressions in CSP 1.1.
Unlike policies defined in Content Security Policy, the
frame-options directive 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 the directive-value contains the keyword-source 'deny', the resource
cannot be displayed in an embedded context, regardless of the origin attempting
to do so, and all other values in the directive are ignored.
If the directive-value contains the keyword-source 'self'
alone to indicate that the resource may be embedded only if all
ancestors are in the same origin as the protected resource.
A host-source value indicates an origin that is a valid
ancestor for the resource. No more than one additional host-source may
be specified, with the exception of the keyword-source 'self'.
Issue 2
The restriction to a single additional host source value was based on
the request of the Websec WG as part of moving this feature to this document. This
decision should be evaluated in the context of CSP. For example, while standalone
implementations of X-Frame-Options may not have wanted to incur the complexity of
parsing potentially large lists of origins, CSP implementaions must already be robust
in their handling of such lists. The inclusion of multiple origins may reveal
details of the security model of a resource that chooses to publish such a policy and
risks associated with this should be discussed in the Security Considerations section
if any change is made.
If the 'top-only' keyword-source is specified, only the origin of the
top-level browsing context is checked, not the full window frame tree of ancestors. This
provides compatibility with X-Frame-Options but may introduce vulnerabilities
in some cases as discussed in [SECURITY CONSIDERATIONS]. When 'top-only' is
specified, a host-source may not be combined with 'self'.
3.3 input-protection-clip
The input-protection-clip directive defines a rectangular screen area
whose intersection with the bounding rectangle of the whole document's body should be used as the reference area in
the screenshot comparison check explained in the Input Protection Heuristic section.
If the input-protection-clip directive is not explicitly set in a policy
which includes the input-protection directive
and no input-protection-selectors directive is set either,
the bounding rectangle of the whole document's body should be used for screenshot comparisons.
If explicitly set as part of a policy where no input-protection
directive is explicitly set, the input-protection-clip directive
implies the input-protection directive as if it was set in the same policy with its default value.
directive-name = "input-protection-clip"
directive-value = ["before=" num-val] ["above=" num-val] ["after=" num-val] ["below=" num-val]
The optional directive value can include up to four non-negative numeric labeled offsets,
expressed in CSS pixels and relative to the screen coordinates of the UI event being processed
(event.screenX and event.screenY for mouse and touch event) or, if not applicable (e.g. for keyboard events),
to the geometrical center of the event target in screen coordinates.
These offsets define a rectangle with
x = eX - left, y = eY - top, width = left + right, height = top + bottom
where eX and eY are the event's explicit (when possible) or inferred (the target's center) screen ordinates.
The left, top, right and bottom
values are mapped to the offsets labeled as
before, above, after and below
respectively, unless the bi-directional text properties of the event target suggest otherwise: for instance,
if the target's direction is RTL, before translates to right and after
translates to left.
Issue 4
Should the bi-directional mapping rules being defined more strictly and reference any
external document, or is the language above clear enough?
The default value for this directive is before=250 above=250 after=50 below=50.
If a partial value is provided (i.e. any offset has been omitted) the default values should be implied for the missing offsets.
The intersection of the computed rectangle with the bounding rectangle of the document's body
should be used as the reference area for the screenshot comparison check explained in the
Input Protection Heuristic section, unless the UI event's target or one of its DOM ancestors match a
input-protection-selector directive set in the same policy.
If the input-protection-clip directive is not set or provides an invalid value, the whole bounding rectangle
of the document's body must be used as the reference area for the screenshot comparison,
unless an input-protection-selectors directive is set in the same policy.
3.5 report-uri
Issue 5
Review this section to ensure that privacy violations
do not occur - is any of this information not normally available to
the DOM of an embedded resource?
The report-uri directive specifies a URI to which the
user agent sends reports about policy violation.
The syntax for the name and value of this directive and the
algorithm to prepare a report are described
by Content Security Policy. [REF - fwd compatible]
The core Content Security Policy specification provides directives to
restrict from where external content may be loaded. As such, violation
reports include a blocked-uri key/value pair that specifies the
attempted resource load that was blocked by the policy.
As this is not applicable to the directives in this document, the
following additional steps must be added to the algorithm defined in
Content Security Policy to prepare a violation report:
In step 1, when preparing the JSON object violation-object,
add the following keys and values to the csp-report: [CSP]
If the violation is of the frame-options directive, add the
following keys and values:
- frame-options
- No value.
Issue 6
We cannot send the ancestor stack and origins without going outside what
is currently allowed by the Same Origin Policy. Is there a safe way
to provide more meaningful information?
If the violation is of the input-protection directive, add
the following keys and values:
- blocked-event-type
- The
type attribute of the UIEvent that was blocked by policy.
- touch-event
- A boolean indicating whether the event blocked by policy was a Touch Event [TOUCH-EVENTS].
Issue 7
Need to harmonize with the new Pointer Events WG specs.
- client-height
- The
document.documentElement.clientHeight property
as defined in TODO.
- client-width
- The
document.documentElement.clientWidth property
as defined in TODO.
- blocked-event-client-x
- The
clientX attribute of the UIEvent that was blocked by policy, if set.
- blocked-event-client-y
- The
clientY attribute of the UIEvent that was blocked by policy, if set.
Issue 8
What standard defines these attributes?
If the target of an UIEvent which triggers an input-protection violation has an explictly-set id attribute:
- blocked-target-id
- The
id attribute of the DOM Element that a violating
UIEvent targeted.
Otherwise, if the target element does not have an explicit id attribute:
- blocked-target-xpath
- An XPath [XPATH] expression that returns the target
Element of the UIEvent
that was blocked by policy. TODO: describe the algorithm to do this here
4. DOM interface
This specification introduces a new attribute for the UIEvent
interface introduced in DOM Level 2. [DOM-LEVEL-2-EVENTS]
4.1 unsafe attribute for the UIEvent interface
unsafe of type boolean,
readonly - This is a non-configurable boolean property of input event objects. The
value should be "true" if a
violation occurred. The value should not not be set unless triggered by user initiated
actions.
The unsafe attribute allows web applications to monitor and
immediately respond to suspect violations in the report-only
mode. Applications may also use this interface for capability detection. For
example, a web application may monitor user inputs on a payment button element
like this:
Example 1
document.getElementById('payment-button').addEventListener("click", function(eventObj) {
if ("unsafe" in eventObj) {
if (eventObj.unsafe == true) {
return reportUnsafeOrShowDialog();
}
}
makePayment();
};6. Script Interfaces
Issue 10
Should we define 1.1 compatible script interfaces, or only
recommend checking the presence of the unsafe attribute?
7. Examples
7.1 Sample Policy Definitions
This section is non-normative.
This section provides some sample use cases and accompanying security
policies.
Example 1:
A resource wishes to block delivery of UI events to the document unless its whole body
has been entirely visible (no tolerance) during the past 1 second (default display-time value):
Content-Security-Policy: input-protection
Example 2:
A resource wishes to block delivery of UI events to the element with id "send-box", all the elements with class
".tweet" and all the forms in the page unless those elements have been visible for the past 800 milliseconds at least,
(their intrinsic sizes is used as a reference for screenshot comparison):
Content-Security-Policy: input-protection display-time 800;
input-protection-selectors #send-button, .tweet, form
Example 3: A resource wishes to block delivery of UI events
to any obstructed HTML button and suggests a 15% tolerance
threshold for determining obstruction of the element with a 200 pixels wide margin above and before (on the top and on the left,
if orientation is LTR) the triggering element:
Content-Security-Policy: input-protection tolerance=15;
input-protection-selectors above=200 before=200 after=0 below=0 button, input[type=submit], input[type=button]
Example 4:A resource wishes to receive reports when the
UI Safety heuristic is triggered for any element in the <body>,
with the default 300 by 300 pixels clipped reference area and 0 tolerance:
Content-Security-Policy-Report-Only: input-protection; input-protection-clip;
report-uri https://example.com/csp-report?unique_id=XKSJ9KAAHJDK9928KKSJEQ
Example 5: A resource wants to react to potential clickjacking
directly, without sending a report, so it sets a report-only header but does not
specify a report-uri. When a UIEvent is sent, the unsafe
attribute will still be set when the heuristic is triggered:
Content-Security-Policy-Report-Only: input-protection
8. Security Considerations
The 'top-only' keword with the frame-options
directive is provided for compatible behavior with the X-Frame-Options header,
but it may allow attacks to be mounted if a trusted context embeds an untrusted
context, because that untrusted context may itself then re-embed a resource
from the same origin as the trusted context.
For example, if a resource X at origin A allows untrusted content Y from origin B
to be displayed in an iframe, Y may itself create another
iframe embedding resource Z from origin A.
A frame-options policy check applied to Z with a value of 'self' 'top-only'
would succeed if X was the topmost frame, but this would still allow the untrusted content Y
to attack Z. Checking all ancestors would prevent this attack.
frame-options provides deterministic protections within a single browsing window, but may not provide full protection in environments where multiple browser windows may overlap and be programmatically closed or moved by malicious content. These directives should be deployed in concert with input-protection to provide additional protection in such environments.
UI Redressing and Clickjacking attacks rely on violating the contextual and temporal integrity of embedded content. Because these attacks target the subjective perception of the user and not well-defined security boundaries, the heuristic protections afforded by the input-protection directive can never be 100% effective for every interface. It provides no protection against certain classes of attacks, such as displaying content around an embedded resource that appears to extend a trusted dialog but provides misleading information.
9. Implementation Considerations
The policy and intent of the user always takes precedence over the policy
of resources. In particular, transformations, customizations or enhancements
of visual content made by the user agent or user-installed plugins should not cause the
input-protection heuristic to be triggered.
Many UI Redressing and Clickjacking attacks rely on exploiting specific features of user agents, such as repositioning of the browsing window, hiding or creating fake cursors, and script-driven scrolling and content repositioning. Not all attacks apply to all user agents in all contexts. User agents are free to optimize or not implement suggested heuristics when they do not apply, for example:
- Cursor integrity in a touch-only environment
- Drag and drop protections for user agents where
drag is not a supported event type
ui-width and ui-height values that exceed the
capabilities of the browsing environment
Some resource owners may specify a restrictive policy forbidding embedding in
user agents that only understand X-Frame-Options but be more
permissive with user agents that implement UI Safety directives. User agents
that are aware of but choose not to implement any of the heuristics in this
document may still ignore X-Frame-Options when
presented in combination with UI Safety directives in a Content Security Policy.
For example, a browsing environment that deliberately chooses not to implement
UI Safety features because they interfere with assistive technologies should not deny
users access to resources on this account. User agents taking this stance should
implement the unsafe attribute of the UIEvent interface
as this may be interrogated by client applications doing feature detection.
In environments that support multiple, overlapping browser windows, attacks
may be mounted by positioning a target window under another, instructing the
user to double click, and closing the obstructing window with the first click.
[TODO: ref Jackson et al. paper here] In such environments user agent
implementers may wish to use a native operating system screenshot facility to
calculate the user's view for the obstruction check phase of
the heuristic.
While this document describes a mechanism for resource authors to opt-in to
User Interface Safety protections, user agents may choose to opt-in all resources
to input-protection by default, or provide users with an option
to enable such protections for all resources.
In support of enabling default protection, user agents may, with appropriate
user consent and privacy protections, gather large-scale data on when the
heuristic would have been triggered, if it had been enabled, for various values
of the configurable hint parameters. Such data would allow the user agent to
determine what default settings can provide broad protection with an acceptable
rate of false positives, and perhaps to build a compatibility opt-out list of
sites or resources to further reduce the false positive rate.
9.1 Accessibility Technologies
Certain classes of accessibility technologies such as
screen readers will provide strong defenses against many classes
of UI Redressing attacks by presenting the content to the user
in a manner not subject to interference. Such user agents
should set the unsafe attribute of the UIEvent
interface as this may be interrogated by client applications doing
feature detection, and should ignore X-Frame-Options
headers when presented in combination with UI Safety directives in a
Content Security Policy.
Use of accessibility technologies must not cause
the input-protection heuristic to be triggered.
Accessibility technologies that modify the appearance of a resource,
such as screen magnifiers or color and contrast modifications to the
display have the potential to interfere with the obstruction
checkif not applied in a consistent manner to both the
user image and control image.
To prevent this inteference, user agents should apply accessibility
transformations to the control image. If a user
agent is able to detect that accessibility technologies are in use
that cannot be applied uniformly as part of the obstruction
check, the check must be disabled.
User agents should provide a means for the user to manually disable
enforcement of the Input Protection Heuristic if it
interferes with their chosen accessibility technologies.
10. Implementation Considerations for Resource Authors
When possible, resource authors should make use of violation reports and the unsafe attribute to apply additional security measures in the application or during back-end processing. Real-time measures in the application might include requiring completion of a CAPTCHA [REF] or responding to an out-of-band confirmation when the UI Safety heuristic is triggered. Example back-end measures might include increasing a fraud risk score for individual actions that trigger or targets accounts/resources that frequently trigger UI Safety heuristics. To be able to do this effectively, it is likely necessary to encode into the report-uri a unique identifier that can be correlated to the authenticated user and the action they are taking.
11. IANA Considerations
This document does not define new message headers and uses the existing grammar
of the Content-Security-Policy and Content-Security-Policy-Report-Only headers, so
no updates to the permanent message header field registry (see [RFC3864]) are required.