--- a/user-interface-safety.html Mon Mar 04 14:59:21 2013 -0800
+++ b/user-interface-safety.html Mon Mar 04 21:17:40 2013 -0800
@@ -2,7 +2,7 @@
<html>
<head>
<!--link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css" charset="utf-8"-->
- <title>User Interface Safety Directives for Content Security Policy</title>
+ <title>User Interface Security Directives for Content Security Policy</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<!--
=== NOTA BENE ===
@@ -14,7 +14,7 @@
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
// Member-SUBM
- specStatus: "WD",
+ specStatus: "ED",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "UISecurity",
@@ -91,7 +91,7 @@
"CLEARCLICK" : "G. Maone <a href=\"http://noscript.net/downloads/ClearClick_WAS2012_rv2.pdf\"><cite>ClearClick: Effective Client-Side Protection Against UI Redressing Attacks</cite></a>. (Work in progress.) URL: <a href=\"http://noscript.net/downloads/ClearClick_WAS2012_rv2.pdf\">http://noscript.net/downloads/ClearClick_WAS2012_rv2.pdf</a>",
"UIREDRESS" : "M. Zalewski <a href=\"http://code.google.com/p/browsersec/wiki/Part2#Arbitrary_page_mashups_(UI_redressing)\"><cite>Browser Security Handbook, part 2</cite></a>. URL: <a href=\"http://code.google.com/p/browsersec/wiki/Part2#Arbitrary_page_mashups_(UI_redressing)\">http://code.google.com/p/browsersec/wiki/Part2#Arbitrary_page_mashups_(UI_redressing)</a>",
"FRAMEBUSTING" : "Boneh, et al. <a href=\"http://seclab.stanford.edu/websec/framebusting/\"><cite>Busting frame busting: a study of clickjacking vulnerabilities at popular sites</cite></a>. URL: <a href=\"http://seclab.stanford.edu/websec/framebusting/\">http://seclab.stanford.edu/websec/framebusting/</a>",
-"INCONTEXT" : "Lin-Shung Huang, et al. <a href=\"https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final39.pdf\"><cite>Clickjacking:Attacks and Defenses</cite></a> published in the 21st USENIX Security Symposium Proceedings. URL: <a href=\"https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final39.pdf\">https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final39.pdf</a>","SELECTORS4" : "Elika J. Etemad. <a href=\"http://www.w3.org/TR/2011/WD-selectors4-20110929/\"><cite>Selectors Level 4.</cite></a> 29 September 2011. W3C Working Draft. (Work in progress.) URL: <a href=\"http://www.w3.org/TR/2011/WD-selectors4-20110929/\">http://www.w3.org/TR/2011/WD-selectors4-20110929/</a>"
+"INCONTEXT" : "Lin-Shung Huang, et al. <a href=\"https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final39.pdf\"><cite>Clickjacking:Attacks and Defenses</cite></a> published in the 21st USENIX Security Symposium Proceedings. URL: <a href=\"https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final39.pdf\">https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final39.pdf</a>","SELECTORS4" : "Elika J. Etemad. <a href=\"http://www.w3.org/TR/2011/WD-selectors4-20110929/\"><cite>Selectors Level 4.</cite></a> 29 September 2011. W3C Working Draft. (Work in progress.) URL: <a href=\"http://www.w3.org/TR/2011/WD-selectors4-20110929/\">http://www.w3.org/TR/2011/WD-selectors4-20110929/</a>","POINTER-EVENTS" : "Jacob Rossi and Matt Brubeck. <a href=\"http://www.w3.org/TR/pointerevents/\"><cite>Pointer Events.</cite></a> 19 February 2013 W3C Working Draft. (Work in progress.) URL: <a href=\"http://www.w3.org/TR/pointerevents/\">http://www.w3.org/TR/pointerevents/</a>", "CAPTCHA-Wikipedia" : "Wikipedia <a href=\"http://en.wikipedia.org/wiki/CAPTCHA\"><cite>CAPTCHA</cite></a> from Wikipedia. URL: <a href=\"http://en.wikipedia.org/wiki/CAPTCHA\">http://en.wikipedia.org/wiki/CAPTCHA</a>", "CLICKJACKING-Unresolved" : "Lin-Shung Huang and Collin Jackson. <a href=\"https://docs.google.com/document/pub?id=1hVcxPeCidZrM5acFH9ZoTYzg1D0VjkG3BDW_oUdn5qc\"><cite>Clickjacking Attacks Unresolved.</cite></a> Carnegie Mellon University, 06 July 2011. URL: <a href=\"https://docs.google.com/document/pub?id=1hVcxPeCidZrM5acFH9ZoTYzg1D0VjkG3BDW_oUdn5qc\">https://docs.google.com/document/pub?id=1hVcxPeCidZrM5acFH9ZoTYzg1D0VjkG3BDW_oUdn5qc</a>"
}
@@ -102,31 +102,18 @@
<body>
<section id=abstract>
-<p>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. </p>
+
+<p>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. </p>
+
</section>
+
<section id=sotd>
-<p>This is the First Public Working Draft of the User Interface Safety
-Directives for Content Security Policy. [[!CSP]]
+<p>This is a Working Draft of the User Interface Security Directives for Content Security Policy. [[!CSP]]
-<p>Portions of the technology described in this document were originally
-developed as part of <code>X-Frame-Options</code>
-[[XFRAMEOPTIONS]],
-the ClearClick module of the Mozilla Firefox add-on NoScript,
-[[CLEARCLICK]]
-and in the InContext system implemented experimentally in Internet Explorer
-[[INCONTEXT]]. </p>
+<p>Portions of the technology described in this document were originally developed as part of <code>X-Frame-Options</code> [[XFRAMEOPTIONS]], the ClearClick module of the Mozilla Firefox add-on NoScript, [[CLEARCLICK]] and in the InContext system implemented experimentally in Internet Explorer [[INCONTEXT]]. </p>
-<p>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 <a
-href="http://tools.ietf.org/wg/websec/">IETF websec working group</a>,
-particularly that working group's requirements document: <a
-href="http://tools.ietf.org/id/draft-hodges-websec-framework-reqs">draft-hodges-websec-framework-reqs</a>.
-</p>
+<p>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 <a href="http://tools.ietf.org/wg/websec/">IETF websec working group</a>, particularly that working group's requirements document: <a href="http://tools.ietf.org/id/draft-hodges-websec-framework-reqs">draft-hodges-websec-framework-reqs</a>. </p>
@@ -134,80 +121,37 @@
</section><section class=informative>
<h2>Introduction</h2>
-<p>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. </p>
-
-<p>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. </p>
-<p>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
-<code>source-expression</code> in Content Security Policy 1.0 is at the
-granularity of an <dfn>origin</dfn> [[!ORIGIN]]
-but may be more granular in future versions of the core Content Security Policy.
-</p>
-<p>Application authors SHOULD transmit the directives in this specification
-as part of a single, complete Content Security Policy, as indicated by
-that specification. </p>
+<p>This document defines User Interface Security 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. </p>
-<p>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. </p>
-
-<p>Existing anti-clickjacking measures including frame-busting [[FRAMEBUSTING]]
- codes and <code>X-Frame-Options</code> 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. </p>
-
-<p>The User Interface Safety directives encompass the policies defined in <code>X-Frame-Options</code>
-and also provide a new mechanism to allow web applications to enable heuristic
-input protections for its user interfaces on user agents. </p>
+<p>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. </p>
-<p>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. </p>
-
-<p>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. </p>
+<p>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 <code>source-expression</code> in Content Security Policy 1.0 is at the granularity of an <dfn>origin</dfn> [[!ORIGIN]] but may be more granular in future versions of the core Content Security Policy. </p>
-<p>This specification obsoletes <code>X-Frame-Options</code>. Resources may supply an
-<code>X-Frame-Options</code> 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 <code>X-Frame-Options</code> 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 <code>X-Frame-Options</code> policies
-applied otherwise.</p>
+<p>Application authors SHOULD transmit the directives in this specification as part of a single, complete Content Security Policy, as indicated by that specification. </p>
+
+<p>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. </p>
+
+<p>Existing anti-clickjacking measures including frame-busting [[FRAMEBUSTING]] codes and <code>X-Frame-Options</code> cannot be used to protect resources where the set of origins that should be allowed and disallowed is unknown, where attacks might come from origins intended to be allowed by a use scenario, or defend against timing-based attacks involving multiple windows instead of multiple frames. Frame-busting scripts also rely on browser behavior that has not been engineered to provide a security guarantee. As a consequence, such scripts may be unreliable if loaded inside a sandbox or otherwise disabled.</p>
+
+<p>The User Interface Security directives encompass the policies defined in <code>X-Frame-Options</code> and also provide a new mechanism to allow web applications to enable heuristic input protections for its user interfaces on user agents. </p>
+
+<p>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. </p>
+
+<p>The User Interface Security 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. </p>
+
+<p>This specification obsoletes <code>X-Frame-Options</code>. Resources may supply an <code>X-Frame-Options</code> 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 <code>X-Frame-Options</code> header, when present, if User Interface Security 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 <code>X-Frame-Options</code> policies applied otherwise.</p>
</section><section id=conformance>
-<p>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. </p>
+<p>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. </p>
-<p>A conformant user agent is one that implements all the requirements listed
-in this specification that are applicable to user-agents. Treatment of
+<p>A conformant user agent is one that implements all the requirements listed in this specification that are applicable to user-agents. Treatment of
the <code>input-protection</code>, <code>input-protection-clip</code> and <code>input-protection-selectors</code> directives are at the discretion of the
user agent.</p>
-<p>A conformant server is one that implements all the requirements listed in
-this specification that are applicable to servers. </p>
+<p>A conformant server is one that implements all the requirements listed in this specification that are applicable to servers. </p>
+
<section>
+
<h3>Terminology</h3>
<p>This section defines several terms used throughout the document. </p>
@@ -220,30 +164,15 @@
<li>a fragment of text that codifies these preferences.</li>
</ol>
-<p>The security policies defined by this document are applied by a user agent
-on a <em>per-resource representation basis</em>. Specifically, when a user
-agent receives a policy along with the representation of a given resource, that
-policy applies to <em>that resource representation only</em>. This document
-often refers to that resource representation as the <dfn>protected
-resource</dfn>. </p>
+<p>The security policies defined by this document are applied by a user agent on a <em>per-resource representation basis</em>. Specifically, when a user agent receives a policy along with the representation of a given resource, that policy applies to <em>that resource representation only</em>. This document often refers to that resource representation as the <dfn>protected resource</dfn>. </p>
-<p>A server transmits its security policy for a particular resource as a
-collection of <dfn>directives</dfn>, such as <code>default-src 'self'</code>,
-each of which controls a specific set of privileges for a document rendered by
-the user agent. More details are provided in the <a
-href="#directives">directives</a> section. </p>
+<p>A server transmits its security policy for a particular resource as a collection of <dfn>directives</dfn>, such as <code>default-src 'self'</code>, each of which controls a specific set of privileges for a document rendered by the user agent. More details are provided in the <a href="#directives">directives</a> section. </p>
-<p>A directive consists of a <dfn>directive name</dfn>, which indicates the
-privileges controlled by the directive, and a <dfn>directive value</dfn>, which
-specifies the restrictions the policy imposes on those privileges. </p>
+<p>A directive consists of a <dfn>directive name</dfn>, which indicates the privileges controlled by the directive, and a <dfn>directive value</dfn>, which specifies the restrictions the policy imposes on those privileges. </p>
-<p> An <dfn>ancestor</dfn> 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.</p>
+<p> An <dfn>ancestor</dfn> 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.</p>
-<p>The term <dfn>origin</dfn> is defined in the Origin specification. [<em><a
-href="http://tools.ietf.org/html/draft-ietf-websec-origin">ORIGIN</a></em>] </p>
+<p>The term <dfn>origin</dfn> is defined in the Origin specification. [<em><a href="http://tools.ietf.org/html/draft-ietf-websec-origin">ORIGIN</a></em>] </p>
<p>The term <dfn>URI</dfn> is defined in the URI specification. [[!URI]] </p>
@@ -287,7 +216,17 @@
;
</pre>
-</section></section><section>
+
+<p>A <dfn id="embedding-source-list">embedding source list</dfn> follows the ABNF and parsing rules defined for <a href="http://www.w3.org/TR/CSP/#source-list">source-list</a> (see [[!CSP]] section 3.22) with the following new productions:
+
+<pre>embedding-keyword-source = "'self'" / "'top-only'" / "'deny'"
+embedding-source-expression = host-source / embedding-keyword-source
+embedding-source-list = *WSP [ embedding-source-expression *( 1*WSP embedding-source-expression ) *WSP ]
+</pre>
+
+</section>
+
+</section><section>
<h2 id="sec-directives">Directives</h2>
<p>This section describes the content security policy directives introduced in
@@ -298,58 +237,37 @@
<h3><code>frame-options</code></h3>
-<p>The <code>frame-options</code> directive indicates whether the
-user-agent should embed the resource using a <code>frame</code>,
-<code>iframe</code>, <code>object</code>, <code>embed</code> or <code>applet</code> 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.
+<p>The <code>frame-options</code> directive indicates whether the user-agent should embed the resource using a <code>frame</code>, <code>iframe</code>, <code>object</code>, <code>embed</code> or <code>applet</code> 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. </p>
-The syntax for the name and value of the directive are described by the following ABNF grammar:</p>
+<p>The syntax for the name and value of the directive are described by the following ABNF grammar:</p>
<pre>
directive-name = "frame-options"
-directive-value = 'deny' / 'self' ['top-only'] / 1*1<host-source> ['self'] / 1*1<host-source> 'top-only'
+directive-value = embedding-source-list
</pre>
-<p class="issue">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.</p>
-
-<p>Unlike policies defined in Content Security Policy, the
-<code>frame-options</code> directive is not subject to the
-<code>default-src</code> directive. If this directive is not
-explicitly stated in the policy its value is assumed to be <code>"*"</code>.</p>
-
-<p>If the directive-value contains the keyword-source <code>'deny'</code>, 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.</p>
-
-<p>If the directive-value contains the keyword-source <code>'self'</code>
-alone to indicate that the resource may be embedded only if all
-<strong>ancestors</strong> are in the same origin as the protected resource.</p>
+<p>Unlike policies defined in Content Security Policy, the <code>frame-options</code> directive is not subject to the <code>default-src</code> directive. If this directive is not explicitly stated in the policy its value is assumed to be <code>"*"</code>.</p>
-<p>A host-source value indicates an origin that is a valid
-<strong>ancestor</strong> for the resource. No more than one additional host-source may
-be specified, with the exception of the keyword-source 'self'. </p>
+<p>A host-source value in the embedding-source-list indicates an origin that is a valid <strong>ancestor</strong> for the resource.</p>
-<p class="issue">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.</p>
+<p>If the directive-value contains the embedding-keyword-source <code>'deny'</code>, 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.</p>
-<p>If the <code>'top-only'</code> 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 <code>X-Frame-Options</code> but may introduce vulnerabilities
-in some cases as discussed in [SECURITY CONSIDERATIONS]. When <code>'top-only'</code> is
-specified, a <code>host-source</code> may not be combined with <code>'self'</code>.
+<p>If the directive-value contains the embedding-keyword-source <code>'self'</code>, <strong>ancestors</strong> are in the same origin as the protected resource.</p>
+<p>If the <code>'top-only'</code> 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 <code>X-Frame-Options</code> but may introduce vulnerabilities in some cases as discussed in the <a href="#security-considerations">Security Considerations</a>.</p>
+<section id="multiple-host-source-values" class=informative>
+<h4>Multiple Host Source Values</h4>
+<p class="issue" title="Inline Security Considerations?">Does this belong here or in a policy author security considerations section?</p>
+
+<p>Multiple <code>host-source</code> values are allowed primarily to enable scenarios involving embedded application compoments that are multiple levels below the top-level browsing context.</p>
+
+<p>Many common scenarios for permissioned embedding (e.g. embeddable payment, sharing or social apps) involve potentially many hundreds or thousands of valid <code>host-source</code> values, but it is strongly recommended against accomodating such scenarios with a static <code>frame-options</code> directive listing mulitple values. In such cases it is beneficial to generate this value dynamically, based on an HTTP Referer header or an explicitly passed-in value, to allow only the source(s) necessary for each given embedding of the resource.</p>
+
+<p>Consider a service providing a payments application at <code>https://payments/makeEmbedded</code>. The service allows this resource to be embedded by both merchant Alice and merchant Bob, who compete with each other. Sending
+<pre>Content-Security-Policy: frame-options https://alice https://bob</pre>
+would allow Bob to re-frame Alice's resource and create fradulent clicks, perhaps discrediting Alice with her customers or the payments service. If the payments service required additional information (e.g. <code>https://payments/makeEmbedded?merchant=alice</code>) to send individually-tailored headers listing only the <code>host-source</code> values needed by each merchant, this attack would be eliminated.</p>
+</section>
</section>
<section id="input-protection">
@@ -374,14 +292,9 @@
attribute on the <code>UIEvent</code> set to <code>true</code>
and cause a violation report to be sent.</p>
-<p>The optional directive value allow resource authors to provide <a href="#input-protection-options">options</a> for heuristic tuning
+<p>The optional directive value allows resource authors to provide <a href="#input-protection-options">options</a> for heuristic tuning
in the form of space-separated <code>option-name=option-value</code> pairs. </p>
-<p class="issue">
-The <code>unsafe</code> attribute is not defined for the enforced directive
-because the event should be cancelled. Do we want to raise another type of event or allow a callback to be specified when an action is blocked?
-</p>
-
<pre>
directive-name = "input-protection"
directive-value = ["display-time=" num-val] ["tolerance=" num-val]</pre>
@@ -428,7 +341,7 @@
<p>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
-(<code>event.screenX</code> and <code>event.screenY</code> for mouse and touch event) or, if not applicable (e.g. for keyboard events),
+(<code>event.screenX</code> and <code>event.screenY</code> for mouse, touch or pointer events) 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
<pre>
@@ -441,20 +354,16 @@
respectively, unless the bi-directional text properties of the event target suggest otherwise: for instance,
if the target's direction is RTL, <code>before</code> translates to <code>right</code> and <code>after</code>
translates to <code>left</code>.
-<p class="issue">Should the bi-directional mapping rules being defined more strictly and reference any
-external document, or is the language above clear enough?</p>
-<p>The default value for this directive is <code>before=250 above=250 after=50 below=50</code>.
-If a partial value is provided (i.e. any offset has been omitted) the default values should be implied for the missing offsets.
-</p>
-<p>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
-<a href="#heuristic">Input Protection Heuristic</a> section, unless the UI event's target or one of its DOM ancestors match a
-<code>input-protection-selector</code> directive set in the same policy.</p>
-<p>If the <code>input-protection-clip</code> 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 <code>input-protection-selectors</code> directive is set in the same policy.</p>
+
+<p>The default value for this directive is <code>before=250 above=250 after=50 below=50</code>. If a partial value is provided (i.e. any offset has been omitted) the default values should be implied for the missing offsets. </p>
+
+<p>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 <a href="#heuristic">Input Protection Heuristic</a> section, unless the UI event's target or one of its DOM ancestors match a <code>input-protection-selector</code> directive set in the same policy.</p>
+
+<p>If the <code>input-protection-clip</code> 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 <code>input-protection-selectors</code> directive is set in the same policy.</p>
+
</section>
+
<section>
<h3><code>input-protection-selectors</code></h3>
@@ -499,16 +408,13 @@
<section>
<h3><code>report-uri</code></h3>
-<p class="issue">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?</p>
<p>The <code>report-uri</code> directive specifies a URI to which the
user agent sends reports about policy violation.
<p>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]</p>
+by Content Security Policy. [[!CSP]]</p>
<p>The core Content Security Policy specification provides directives to
restrict from where external content may be loaded. As such, violation
@@ -522,52 +428,42 @@
<p>In step 1, when preparing the JSON object <em>violation-object</em>,
add the following keys and values to the <dfn>csp-report</dfn>: [[!CSP]]</p>
-<p>If the violation is of the <code>frame-options</code> directive, add the
-following keys and values:</p>
+<p>If the violation is of the <code>frame-options</code> directive, no additional processing is required.</p>
-<dl>
- <dt>frame-options</dt>
- <dd><em>No value.</em></dd>
- <p class="issue">
-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?
-</p>
-</dl>
-<p>If the violation is of the <code>input-protection</code> directive, add
-the following keys and values:</P>
+<p>If the violation is of the <code>input-protection</code> directive, add the following keys and values. If a value is not set or applicable for the violation (e.g. pointer-height, if the violating event type is not a Pointer Event) the key SHOULD be omitted.
+</P>
<dl>
<dt>blocked-event-type</dt>
<dd>The <code>type</code> attribute of the <code>UIEvent</code> that was blocked by policy.</dd>
<dt>touch-event</dt>
- <dd>A <dfn>boolean</dfn> indicating whether the event blocked by policy was a <dfn>Touch Event</dfn> [[TOUCH-EVENTS]].</dd>
-</dl>
+ <dd>A <dfn>boolean</dfn> indicating whether the event blocked by policy was a <dfn>Touch Event</dfn> [[!TOUCH-EVENTS]].</dd>
-<p class="issue">
-Need to harmonize with the new Pointer Events WG specs.
-</p>
-<dl>
- <dt>client-height</dt>
- <dd>The <code>document.documentElement.clientHeight</code> property
- as defined in <em>TODO</em>.</dd>
+ <dt>pointer-type</dt>
+ <dd>The <code>pointerType</code> value of a <dfn>Pointer Event</dfn> [[POINTER-EVENTS]].</dd>
- <dt>client-width</dt>
- <dd>The <code>document.documentElement.clientWidth</code> property
- as defined in <em>TODO</em>.</dd>
+ <dt>pointer-height</dt>
+ <dd>The <code>height</code> value of a <dfn>Pointer Event</dfn> [[POINTER-EVENTS]].</dd>
+
+ <dt>pointer-width</dt>
+ <dd>The <code>width</code> value of a <dfn>Pointer Event</dfn> [[POINTER-EVENTS]].</dd>
+
+ <dt>device-height</dt>
+ <dd>The <code>device-height</code> property as defined in [[!CSS3-MEDIAQUERIES]].</dd>
+
+ <dt>device-width</dt>
+ <dd>The <code>device-width</code> property as defined in [[!CSS3-MEDIAQUERIES]].</dd>
<dt>blocked-event-client-x</dt>
- <dd>The <code>clientX</code> attribute of the <code>UIEvent</code> that was blocked by policy, if set.</dd>
+ <dd>The <code>clientX</code> attribute of the <code>UIEvent</code> [[!DOM-LEVEL-2-EVENTS]] that was blocked by policy, if set.</dd>
<dt>blocked-event-client-y</dt>
- <dd>The <code>clientY</code> attribute of the <code>UIEvent</code> that was blocked by policy, if set.</dd>
+ <dd>The <code>clientY</code> attribute of the <code>UIEvent</code> [[!DOM-LEVEL-2-EVENTS]] that was blocked by policy, if set.</dd>
</dl>
-<p class="issue">What standard defines these attributes?</p>
-
<p>If the target of an <code>UIEvent</code> which triggers an <code>input-protection</code> violation has an explictly-set <code>id</code> attribute:
@@ -581,10 +477,44 @@
<dl>
<dt>blocked-target-xpath</dt>
- <dd>An XPath [[!XPATH]] expression that returns the target <code>Element</code> of the <code>UIEvent</code>
- that was blocked by policy. <em>TODO: describe the algorithm to do this here</em></dd>
+ <dd>An XPath [[!XPATH]] expression that returns the target <code>Element</code> of the <code>UIEvent</code> that was blocked by policy.</dd>
+
</dl>
+<section class=informative>
+<h3>Producing <code>blocked-target-xpath</code></h3>
+User agent implementers may provide any unambiguous XPath in the report. The following example code using the ECMAScript language bindings for DOM Level 2 Core [[!DOM-LEVEL-2-CORE]] produces an unambiguous XPath to the target DOM element <em>"e"</em>:
+
+<pre class="example" title="Sample implementation of XPath generation for reporting">
+function getXPathFor(e) {
+
+ var xpath = '';
+
+ while(e.nodeType == e.ELEMENT_NODE) {
+
+ var child = e;
+ var siblingIndex = 0;
+ while( (child = child.previousSibling) != null ) {
+ if(child.tagName == e.tagName) {
+ siblingIndex++;
+ }
+ }
+
+ xpath = e.tagName +
+ '[' + siblingIndex + ']' +
+ (xpath == '' ? '' : '/') +
+ xpath;
+
+ e = e.parentNode;
+ }
+ xpath = '/' + xpath;
+ return(xpath);
+}
+</pre>
+
+
+</section>
+
</section>
@@ -612,7 +542,7 @@
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: </p>
-<pre class="example">document.getElementById('payment-button').addEventListener("click", function(eventObj) {
+<pre class="example" title="Example code responing to unsafe attribute">document.getElementById('payment-button').addEventListener("click", function(eventObj) {
if ("unsafe" in eventObj) {
if (eventObj.unsafe == true) {
return reportUnsafeOrShowDialog();
@@ -646,7 +576,7 @@
create a record containing a weak reference to the document causing the repaint, the screen coordinates of the
regions being repainted and a timestamp detailing when the repaint occurred, and add this record
to a screen-global list named "Display Changes List".
- Records older than the maximum value for <code>input-protection</code>'s <code>display-time</code> can be discarded on update.
+ Records older than the maximum value for <code>input-protection</code> <code>display-time</code> can be discarded on update.
</li>
</ol>
</section>
@@ -655,7 +585,7 @@
<ol>
<!-- 1 --> <li><strong>Timing attacks countermeasure</strong> -
check whether the "Display Change List" contains any record younger than the
- <code>input-protection</code>'s <code>display-time</code> value, whose repainted regions
+ <code>input-protection</code> <code>display-time</code> value, whose repainted regions
intersect with the protected UI elements <em>and</em> whose repaint-causing
document is <em>different</em> than the protected one. If this is true, hinting at
a recent change in the way the protected UI is displayed, with causes external to the UI
@@ -670,43 +600,44 @@
possibly attacker-provided bitmap: if it has, jump to step 4. This provides
protection against "Phantom cursor" attacks, also known as
"Cursorjacking".</li>
- <!-- 3 --> <li><strong>Obstruction check</strong> - By using an off-screen HTML 5 canvas
- element, take two screenshots of the area defined by the
+ <!-- 3 --> <li><strong>Obstruction check</strong> Take two screenshots of the area defined by the
<a href="#input-protection-clip"><code>input-protection-clip</code></a> and
<a href="#input-protection-selectors"><code>input-protection-selectors</code></a>
- directives and containing the DOM element
- which is about to receive the event:
- one screenshot must be taken from its owner document's "point of view" (unobstructed by definition),
- the other from the topmost window's point of view. In the plugin content case,
- the former "screenshot" must contain the element itself only. If the number of
- the pixels which are different between the screenshots don't exceed a
+ directives and containing the DOM element which is about to receive the event.
+
+ <p> The <dfn>control image</dfn> is taken from its owner document's "point of view" (unobstructed by definition) in an off-screen HTML5 canvas element [[!HTML5]]. The <dfn>user image</dfn> is taken from either the topmost window's point of view in an off-screen HTML5 canvas element [[!HTML5]] or using the fully compositied operating system perspective, obtained using OS-native APIs.</p>
+
+ <p>When this heuristic is applied to plugin content, the <strong>control image</strong> must contain the element itself only.</p>
+
+ <p>If the number of the pixels which are different
+ between the screenshots don't exceed a
the percentual threshold defined by the
<code>tolerance</code> property of the <code>input-protection</code> directive,
return. Otherwise, assume that the DOM element which the user is
interacting with has been obstructed or obscured by a UI Redressing
- attempt and proceed with step 4.
- <em>Existent implementation note</em>: in NoScript's ClearClick,
- the screenshots are taken by using the CanvasRenderingContext2D.drawWindow() method, which is a
+ attempt and proceed with step 4.</p>
+
+ <p class="note">
+ <em>Implementation note</em>: In the first implementation of this
+ hueristic, NoScript's ClearClick, the screenshots are taken by using the
+ CanvasRenderingContext2D.drawWindow() method, 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.
- <p class="issue"> We should define terms here - e.g. "control image", "user image", to refer
- to elsewhere consistgently</p>
- <!-- 4--> <li><strong>Violation management</strong> -
- If in report-only mode, turn the <code>unsafe</code> property of the event been handled to true and let the
- event processing continue. Otherwise, prevent the event from reaching its target.
- Create and send a violation report if a valid report-uri has been specified.
+ </p>
+
+ <li><strong>Violation management</strong> -
+ If in report-only mode, set the <code>unsafe</code> property of the event been handled to <code>true</code> and let the event processing continue. Otherwise, prevent the event from reaching its target. Create and send a violation report if a valid report-uri has been specified.
</li>
</ol>
</section>
</section>
<section>
-<h2>Script Interfaces</h2>
+<h2>Script and META Tag Interfaces</h2>
-<p class="issue"> Should we define 1.1 compatible script interfaces, or only
- recommend checking the presence of the <code>unsafe</code> attribute?</p>
+<p class="issue" title="Pending CSP 1.1 Details">Need to define forward-compatible language here for 1.1 updates.</p>
</section>
<section>
@@ -718,38 +649,45 @@
<p>This section provides some sample use cases and accompanying security
policies.</p>
-<p><strong>Example 1:</strong>
+<p>
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):
-<pre>Content-Security-Policy: input-protection</pre>
+has been entirely visible (no tolerance) during the past 1 second (default display-time value):</p>
+<pre class="example" title="Policy Header">Content-Security-Policy: input-protection</pre>
-<p><strong>Example 2:</strong>
-A resource wishes to block delivery of UI events to the element with id "send-box", all the elements with class
+<p>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):
-<pre>
+(their intrinsic sizes is used as a reference for screenshot comparison): </p>
+<pre class="example" title="Policy Header">
Content-Security-Policy: input-protection display-time 800;
input-protection-selectors #send-button, .tweet, form</pre>
-<p><strong>Example 3:</strong> A resource wishes to block delivery of UI events
+<p>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:</p>
-<pre>Content-Security-Policy: input-protection tolerance=15;
+<pre class="example" title="Policy Header">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]</pre>
-<p><strong>Example 4:</strong>A resource wishes to receive reports when the
-UI Safety heuristic is triggered for any element in the <code><body></code>,
+<p>A resource wishes to receive reports when the
+UI Security heuristic is triggered for any element in the <code><body></code>,
with the default 300 by 300 pixels clipped reference area and 0 tolerance:</p>
-<pre>Content-Security-Policy-Report-Only: input-protection; input-protection-clip;
+<pre class="example" title="Policy Header">Content-Security-Policy-Report-Only: input-protection; input-protection-clip;
report-uri https://example.com/csp-report?unique_id=XKSJ9KAAHJDK9928KKSJEQ</pre>
-<p><strong>Example 5:</strong> A resource wants to react to potential clickjacking
+<p>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 <code>UIEvent</code> is sent, the <code>unsafe</code>
attribute will still be set when the heuristic is triggered:</p>
-<pre>Content-Security-Policy-Report-Only: input-protection</pre>
+<pre class="example" title="Policy Header">Content-Security-Policy-Report-Only: input-protection</pre>
+
+<p>A resource wants to allow itself to be embedded by <strong>ancestors</strong> that are same-origin or from the origin <code>https://checkout.example.com</code>, but also to have the <code>unsafe</code> attribute set on events that violate the <code>input protection</code> heuristic.</p>
+<pre class="example" title="Policy Header">Content-Security-Policy: frame-options 'self' https://checkout.example.com
+Content-Security-Policy-Report-Only: input-protection </pre>
+
</section>
+
+
+
<section class=informative>
<h3>Sample Violation Report</h3>
@@ -762,7 +700,7 @@
<pre>input-protection; report-uri https://example.org/csp-report.cgi?unique_id=12345</pre>
<p>A <code>click</code> violated the policy.</p>
-<pre>{
+<pre class="example" title="Sample violation report JSON body">{
"csp-report": {
"document-uri": "http://example.org/page.html",
"referrer": "http://evil.example.com/haxor.html",
@@ -770,31 +708,21 @@
"blocked-event-client-x": "325",
"blocked-event-client-y": "122",
"touch-event": "false",
- "client-width": "600",
- "client-height": "700",
- "blocked-target-id": "makePaymentSubmit",
- "blocked-target-xpath": <em>TODO</em>,
- "ancestor-chain": <em>TODO</em>,
+ "device-width": "800",
+ "device-height": "300",
+ "blocked-target-xpath": "/html[0]/body[0]/div[6]/form[2]/input[0]",
"violated-directive": "input-protection",
"original-policy": "input-protection; report-uri https://example.org/csp-report.cgi?unique_id=12345"
}
}</pre>
</section></section>
-<section>
+<section id="security-considerations">
<h2>Security Considerations</h2>
-<p>The <code>'top-only'</code> keword with the <code>frame-options</code>
-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.</p>
+<p>The <code>'top-only'</code> keword with the <code>frame-options</code> 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.</p>
<p>
-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.</p>
+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.</p>
<p>
-A <code>frame-options</code> policy check applied to Z with a value of <code>'self' 'top-only'</code>
-would succeed if X was the topmost frame, but this would still allow the untrusted content Y
-to attack Z. Checking all <strong>ancestors</strong> would prevent this attack.</p>
+A <code>frame-options</code> policy check applied to Z with a value of <code>'self' 'top-only'</code> would succeed if X was the topmost frame, but this would still allow the untrusted content Y to attack Z. This attack is most likely in the case when the sandbox attribute of an iframe is used to contain untrusted context. Such sandboxed content could still mount clickjacking attacks on content in the parent origin with <code>'top-only'</code>. Checking all <strong>ancestors</strong> would prevent this attack.</p>
<p><code>frame-options</code> 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 <code>input-protection</code> to provide additional protection in such environments.</p>
@@ -821,12 +749,12 @@
<p>Some resource owners may specify a restrictive policy forbidding embedding in
user agents that only understand <code>X-Frame-Options</code> but be more
-permissive with user agents that implement UI Safety directives. User agents
+permissive with user agents that implement UI Security directives. User agents
that are aware of but choose not to implement any of the heuristics in this
document MAY still ignore <code>X-Frame-Options</code> when
-presented in combination with UI Safety directives in a Content Security Policy.
+presented in combination with UI Security 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
+UI Security 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 <code>unsafe</code> attribute of the <code>UIEvent</code> interface
as this may be interrogated by client applications doing feature detection.</p>
@@ -834,13 +762,14 @@
<p>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.
-[<em>TODO: ref Jackson et al. paper here</em>] In such environments user agent
+[[CLICKJACKING-Unresolved]] In such environments user agent
implementers may wish to use a native operating system screenshot facility to
calculate the user's view for the <strong>obstruction check</strong> phase of
-the heuristic.</p>
+the heuristic. In such cases user agents should take special caution to
+potential infereference from <a href=#accessibility>accessibility technologies</a></p>
<p>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
+User Interface Security protections, user agents MAY choose to opt-in all resources
to <code>input-protection</code> by default, or provide users with an option
to enable such protections for all resources.</p>
@@ -852,7 +781,7 @@
rate of false positives, and perhaps to build a compatibility opt-out list of
sites or resources to further reduce the false positive rate.</p>
-<section>
+<section id="accessibility">
<h3>Accessibility Technologies</h3>
<p>Certain classes of accessibility technologies such as
screen readers will provide strong defenses against many classes
@@ -861,21 +790,25 @@
SHOULD set the <code>unsafe</code> attribute of the <code>UIEvent</code>
interface as this may be interrogated by client applications doing
feature detection, and SHOULD ignore <code>X-Frame-Options</code>
-headers when presented in combination with UI Safety directives in a
+headers when presented in combination with UI Security directives in a
Content Security Policy.</p>
-<p>Use of accessibility technologies MUST NOT cause
-the <code>input-protection</code> heuristic to be triggered.
+<p>Use of accessibility technologies MUST NOT by itself cause
+the <code>input-protection</code> 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 <strong>obstruction
check</strong>if not applied in a consistent manner to both the
<strong>user image</strong> and <strong>control image</strong>.
To prevent this inteference, user agents SHOULD apply accessibility
-transformations to the <strong>control image</strong>. If a user
-agent is able to detect that accessibility technologies are in use
+transformations to the <strong>control image</strong> if possible.
+If a user agent is able to detect that accessibility technologies are in use
that cannot be applied uniformly as part of the <strong>obstruction
-check</strong>, the check MUST be disabled.</p>
+check</strong>, the check MUST be disabled. In some cases,
+interference from accessiblity tools may be avoided by acquiring
+the <strong>user image</strong> in terms of the user agent's local
+rendering surface, rather than using an operating-system level
+screenshot.</p>
<p>User agents SHOULD provide a means for the user to manually disable
enforcement of the <strong>Input Protection Heuristic</strong> if it
@@ -886,7 +819,7 @@
</section><section>
<h2>Implementation Considerations for Resource Authors</h2>
-<p>When possible, resource authors SHOULD make use of violation reports and the <code>unsafe</code> 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 [<em>REF</em>] 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 <code>report-uri</code> a unique identifier that can be correlated to the authenticated user and the action they are taking.</p>
+<p>When possible, resource authors SHOULD make use of violation reports and the <code>unsafe</code> 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 [[CAPTCHA-Wikipedia]] or responding to an out-of-band confirmation when the UI Security 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 Security heuristics. To be able to do this effectively, it is likely necessary to encode into the <code>report-uri</code> a unique identifier that can be correlated to the authenticated user and the action they are taking.</p>
</section><section>
<h2>IANA Considerations</h2>