--- a/user-interface-safety.html Sun Sep 16 02:07:01 2012 +0200
+++ b/user-interface-safety.html Wed Sep 19 22:41:57 2012 +0200
@@ -191,7 +191,7 @@
<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> directive values are at the discretion of the
+the <code>input-protection</code>, <code>input-protection-padding</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
@@ -243,12 +243,6 @@
<p>The <code><applet></code> element is defined in the HTML 4.01
standard. [[!HTML401]]. </p>
-<!-- <p>The <code>@font-face</code> CSS rule is defined in the CSS Fonts Module Level 3 standard.
-[[!CSS3-FONTS]]</p>
-<p>The <code>XMLHttpRequest</code> object is defined in the <code>XMLHttpRequest</code>
-standard. [[!XMLHTTPREQUEST]]</p>
-<p>The <code>EventSource</code> object is defined in the <code>EventSource</code>
-standard. [<em><a href="http://dev.w3.org/html5/eventsource/">EVENTSOURCE</a></em>].</p> -->
<p>The Augmented Backus-Naur Form (ABNF) notation used in this document is
specified in RFC 5234. [[!ABNF]] </p>
@@ -270,6 +264,19 @@
obs-fold = CRLF ( SP / HTAB )
; obsolete line folding</pre>
+
+<p>A <dfn id=selector-string>selector string</dfn> is a list of one or more
+ <a href="http://dev.w3.org/csswg/selectors4/#complex">complex
+ selectors</a> (<a href="#bib-SELECTORS4"
+ rel=biblioentry>[SELECTORS4]<!--{{!SELECTORS4}}--></a>, section 3.1) that
+ <em class=ct>may</em> be surrounded by whitespace and matches the
+ <code>dom_selectors_group</code> production.
+</p>
+<pre>dom_selectors_group
+ : S* [ selectors_group ] S*
+ ;
+</pre>
+
<p class="issue">How to define <code>source-expression</code>, <code>host-source</code>,
etc. that may have different definitions depending on version of CSP? Basically, how
do we reference versions of CSP that may not yet exist?</p>
@@ -295,7 +302,7 @@
The syntax for the name and value of the directive are described by the following ABNF grammar:</p>
<pre>
-directive-name = "frame-options"
+directive-name = "frame-options"
directive-value = ('deny' / 'self' / 1*1<host-source> ['self']) / ('deny' / 'self' / 1*1<host-source>) 'top-only'
</pre>
@@ -330,105 +337,13 @@
</section>
-<!--
-<section>
-<h3><code>frame-ancestors</code></h3>
-
-<p>The <code>frame-ancestors</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 to avoid many UI Redressing attacks by ensuring
-they are not embedded into other sites.
-
-The syntax for the name and value of the directive are described by the following ABNF grammar:</p>
-
-<pre>
-directive-name = "frame-ancestors"
-directive-value = 'deny' / 'self' / 1*1<host-source> ['self']
-</pre>
-
-<p>Unlike policies defined in Content Security Policy, the
-<code>frame-ancestors</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 does not contain <code>'deny'</code> it may
-contain 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. 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.</p>
-
-<p>If the directive-value does not contain the <code>'deny'</code> keyword-source,
-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 Content Security Policy that includes a <code>frame-ancestors</code> directive
-MUST NOT include a <code>frame-options</code> directive.</p>
-
-
-</section>
-<section>
-<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 to avoid many UI Redressing attacks by ensuring
-they are not embedded into other sites.
-This directive replicates the functionality of the
-<code>X-Frame-Options</code> header. 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' / 1*1<host-source>
-</pre>
-
-<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. This
-provides functionality equivalent to the <code>DENY</code> value of
-the <code>X-Frame-Options header.</code></p>
-
-<p>If the directive-value does not contain <code>'deny'</code> it may
-contain the keyword-source <code>'self'</code> to indicate that the
-resource may only be embedded if the top-level browsing context is in the
-same origin as the protected resource. This provides functionality equivalent
-to the <code>SAMEORIGIN</code> value of the <code> X-Frame-Options</code> header.</p>
-
-<p>If the value of source does not contain the <code>'deny'</code> keyword-source,
-a single additional host-source indicates that the resource cannot be displayed in
-an embedded context unless the top-level browsing context is in the specified host-source origin.
-No more than one additional host-source may be specified. This provides functionality equivalent to the
-<code>ALLOW-FROM</code> value of the <code>X-Frame-Options</code> header.</p>
-
-<p>A Content Security Policy that includes a <code>frame-options</code> directive
-MUST NOT include a <code>frame-ancestors</code> directive.</p>
-
-</section>
--->
-
-<section>
+<section id="input-protection">
<h3><code>input-protection</code></h3>
-<p>The <code>input-protection</code> directive, if present, instructs the user
-agent to apply the heuristic UI redressing protections described in <a
-href="">Section 4</a> to user input events, such as <code>click</code>,
+<p>The <code>input-protection</code> directive, if present or implied, instructs the user
+agent to apply the heuristic UI redressing protections described in the <a
+href="#heuristic">Input Protection Heuristic</a> section to user input events, such as <code>click</code>,
<code>keypress</code>, <code>touch</code>, and <code>drag</code>, before they
are delivered to the resource. </p>
@@ -440,95 +355,124 @@
attribute on the <code>UIEvent</code> set to <code>true</code>
and cause a violation report to be sent.</p>
</p>
-<!-- <p>
-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 <strong>ancestors</strong> are <strong>same origin</strong>
-this token may be ignored. <em>TODO: </em>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.
-</p> -->
-<!--
-<pre>directive-name = "input-protection"
-directive-value = "block" / "report-only" </pre>
-
-<p>A value of <code>block</code> indicates the user agent should not deliver
-the input event to the resource if the input protection heuristic is triggered
-and a violation is detected. </p>
-
-<p>A value of <code>report-only</code> indicates the user agent should deliver
-the input event to the resource, even if a violation is detected. This
-directive-value lets servers experiment with policies by monitoring (rather
-than enforcing) a policy, or to take action higher in the application stack,
-for example, by increasing the fraud risk score of a transaction that triggers
-a violation report. </p>
-<p>If the <code>report-uri</code> directive is present in the policy,
-violations detected by the input protection heuristic <em class="rfc2119"
- title="must">must</em> always generate a
-report, whether the event is blocked or not. </p>
-
-<p>User agents SHOULD NOT prompt the user when the input protection heuristic
-is triggered. </p>
-<p>
-ISSUE: is it worth having a "deliver" option, or should this just
-always be part of a report-only policy?
+<p>The optional directive value allow 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>
-</section>
-<section>
-<h3><code>input-protection-hints</code></h3>
--->
-<p>The optional directive values allow resource authors to provide hints to
-the heuristic to improve accuracy. </p>
-
-
-<p class="issue">BWH: Consolidated the previous <code>input-protection</code> and
-<code>input-protection-hints</code> directives here. <code>input-protection</code>
-previously just had "block" and "report-only" options, which are covered by the
-two different types of CSP header already, without introducing new keyword-sources.
-</p>
<p class="issue">
Also removed setting of <code>unsafe</code> attribute from 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 = ["element-id=" name] ["ui-height=" num-val] ["ui-width=" num-val] ["display-time=" num-val] ["tolerance=" num-val]</pre>
+<pre>
+directive-name = "input-protection"
+directive-value = ["display-time=" num-val] ["tolerance=" num-val]</pre>
<p>If the policy does not contain a value for this directive
-or any of the optional values are absent, the user agent should apply default
-values as described in <a href="">Section XXX</a>. A user agent MAY ignore any
-or all values in <code>input-protection</code>. </p>
-
-<p><code>element-id</code> is the id attribute of a user interface element in the DOM.
-If the policy does not contain an explicit <code>element-id</code>, the user
-agent should apply protection to the <code>body</code> element of the resource.
-</p>
-
-<p><code>ui-height</code> is a numeric value that defines the height of the
-<!--user interface element-->viewing area to be used for performing the screenshot comparison.
-</p>
-
-<p><code>ui-width</code> is a numeric value that defines the width of the
-<!--user interface element-->viewing area to be used for performing the screenshot comparison. </p>
-
-<p><code>display-time</code> is a numeric value from 0 to 10000 that specifies how long, in
+or any of the hint name=value pairs are absent, the user agent SHOULD apply default
+values for hints as described in the following. </p>
+<dl id="input-protection-options">
+<dt><code>display-time</code></dt>
+<dd>is a numeric value from 0 to 10000 that specifies how long, in
milliseconds, the screen area containing the protected user interface
must have been displayed continuously unchanged when the event is processed.
If not specified, it defaults to 800. If a value out of the range stated above is specified, it defaults to the nearest
value between the lower and the higher bounds.
-</p>
+</dd>
-<p><code>tolerance</code> is a numeric value from 0 to 99 that defines the difference
+<dt><code>tolerance</code></dt>
+<dd>is a numeric value from 0 to 99 that defines the difference
threshold at which the screenshot comparison procedure of the input protection
heuristic triggers a violation. A value of 0 indicates that no difference
between the two images is permitted. A value of 99 provides little to no
-practical protection. Defaults to 0.</p>
+practical protection. If not specified, it defaults to 0.</p>
+</dd>
+</section>
+<section id="input-protection-padding">
+<h3><code>input-protection-padding</code></h3>
+
+<p>The <code>input-protection-padding</code> directive defines a rectangular screen area, intersecting the UI event target,
+which should be included in the screenshot comparison check explained in the
+<a href="#heuristic">Input Protection Heuristic</a> section.</p>
+<p>If not explicitly set in a policy which includes the <code>input-protection</code> directive, the <code>input-protection-padding</code>
+directive is implied with its default value, specified below.</p>
+<p>If explicitly set as part of a policy where no <code>input-protection</code>
+directive is explicitly set, the <code>input-protection-padding</code> directive
+implies the <code>input-protection</code> directive as if it was set in the same policy whith its default value.</p>
+</p>
+
+<pre>
+directive-name = "input-protection-padding"
+directive-value = ["before=" num-val] ["above=" num-val] ["after=" num-val] ["below=" num-val] / "none"</pre>
+
+<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 appliable (e.g. for keyboard events),
+to the geometrical center of the event target in screen coordinates.
+These offsets define a rectangle with
+<pre>
+x = eX - left, y = eY - top, width = left + right, height = top + bottom
+</pre>
+where <code>eX</code> and <code>eY</code> are the event's explicit (when possible) or inferred (the target's center) screen cordinates.
+The <code>left</code>, <code>top</code>, <code>right</code> and <code>bottom</code>
+values are mapped to the offsets labeled as
+<code>before</code>, <code>above</code>, <code>after</code> and <code>below</code>
+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>
+The computed rectangle should be regarded as the minimum reference area for the screenshot comparison check explained in the
+<a href="#heuristic">Input Protection Heuristic</a> section.</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>A value of <code>none</code> explicitly disables the screenshot comparison heuristic unless the
+<code>input-protection-selectors</code> is set and its value matches the current event target or one of its ancestors.</p>
+</section>
+
+<section>
+<h3><code>input-protection-selectors</code></h3>
+
+<p>The <code>input-protection-selectors</code> directive overrides the
+implicit or explicit <code>input-protection-padding</code> value when
+the processed UI event target or one of its ancestors in the DOM match the <code>dom_selectors_group</code>
+<a href="#selector-string">selector string</a> provided as the mandatory directive's value:
+in this case, the reference area used for screenshot comparison is the
+bounding box of the event target itself, if it matches the selectors, or the bounding box of its nearest
+matching ancestor, if any, augmented by the margins given by the leading optional labeled offsets, if any.
+UI events whose target and ancestors don't match any of the specified selectors are still processed using the
+<code>input-protection-padding</code> value if explicitly set, or its default value if omitted, in order to compute the
+screenshot reference area, unless said value is the <code>none</code>.
+</p>
+
+<p>If set as part of a policy where no <code>input-protection</code>
+directive is explicitly set, the <code>input-protection-selectors</code> directive
+implies the <code>input-protection</code> directive as if it was set in the same policy whith its default value.</p>
+</p>
+
+<pre>
+directive-name = "input-protection-selectors"
+directive-value = ["before=" num-value] ["after=" num-value] ["above=" num-value] ["below=" num-value] dom_selectors_group</pre>
+
+<p>Any of the four non-negative numeric labeled offsets, which represent margins expressed in CSS pixels,
+may be omitted, taking 0 (zero) as their default values.</p>
+<p>
+The reference screenshot area is computed as the rectangle having
+<pre>
+x = match.x - left, y = match.y - top, width = left + match.width + right, height = top + match.height + bottom
+</pre>
+where <code>match</code> is the bounding rectangle around the UI event target, if it matches <code>dom_selectors_group</code>,
+or around its nearest matching ancestor. The
+<code>left</code>, <code>top</code>, <code>right</code> and <code>bottom</code> values
+are mapped to the offsets labeled as
+<code>before</code>, <code>above</code>, <code>after</code> and <code>below</code>
+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> (similarly to the <a href="#input-protection-padding"><code>input-protection-padding</code></a> directive).
</section>
<section>
@@ -615,7 +559,8 @@
</section>
-</section><section>
+</section>
+<section>
<h2 id="sec-api">DOM interface</h2>
<p>This specification introduces a new attribute for the <code>UIEvent</code>
@@ -646,10 +591,10 @@
makePayment();
};</pre>
</section></section>
-<section>
+<section id="heuristic" class=informative>
<h2>Input Protection Heuristic</h2>
-<section class=informative>
-<p>This section is non-normative. The algorithm described here can be
+<section>
+<p>The algorithm described here can be
implemented mostly in terms of HTML5 constructs, but requires 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
@@ -658,30 +603,32 @@
attack, (e.g. the 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.</p>
-<ul>
-<li><h4>Preparation</h4>
+</section>
+<section>
+<h4>Preparation</h4>
<ol>
<li><strong>Listener registration</strong> - On the topmost window, register a "global" capturing
event listener for mouse button, tapping, keyboard, drag & drop and
focus events, which must be guaranteed to run before any other event
handler of the same kind and therefore be able to prevent any event from
- being handled by the content, if needed.</em> </li>
+ being handled by the content, if needed. </li>
<li><strong>Display changes tracking</strong> - whenever a repaint occurs in the topmost window or in one of its descendants,
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-hints</code>'s <code>display-time</code>, or whose document
- is not alive anymore (the weak reference is possibly null), can be discarded.
+ Records older than the maximum value for <code>input-protection</code>'s <code>display-time</code> can be discarded on update.
</li>
</ol>
-</li>
-<li><h4>UI Event handling</h4>
+</section>
+<section>
+<h4>UI Event handling</h4>
<ol>
<!-- 1 --> <li><strong>Timing attacks countermeasure</strong> -
- check whether the "Display Change List" contains a record whose repainted regions
+ 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
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 (more recent than the <code>display-time</code> value) in the way the protected UI is displayed, with causes external to the UI
+ a recent change in the way the protected UI is displayed, with causes external to the UI
itself (e.g. an overlapping element in an ancestor document or a
floating window being suddenly moved away), assume a timing attack is happening
and jump to step 4.
@@ -694,20 +641,20 @@
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, we take two reasonably sized (300x200 on average, but growing or
- shrinking depending on document's inherent size and viewport constraints
- and hints provided by the <code>ui-height</code> and <code>ui-width</code>
- properties of <code>input-protection-hints</code>) 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
+ element, take two screenshots of the area defined by the
+ <a href="#input-protection-padding"><code>input-protection-padding</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
- certain configurable percentual threshold set by the
- <code>tolerance</code> property of <code>input-protection-hints</code>,
- return. Otherwise we tentatively assume the DOM element our user is
+ 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.
+ 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
Mozilla-proprietary extension of the HTML 5 Canvas API available to
@@ -720,12 +667,9 @@
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>
-
- </li>
</ol>
-</li>
-</ul>
-</section></section>
+</section>
+</section>
<section>
<h2>Script Interfaces</h2>
@@ -743,14 +687,16 @@
policies.</p>
<p><strong>Example 1:</strong> A resource wishes to block delivery of UI events
-to the DOM element with the id of "submitButton" and suggests a 15% tolerance
-threshold for determining obstruction of the element within a 200 by 200 pixel window:</p>
-<pre>Content-Security-Policy: input-protection element-id=submitButton tolerance=15
- ui-height=200 ui-width=200</pre>
+to any 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;
+ input-protection-selectors above=200 before=200 after=0 below=0 button, input[type=submit], input[type=button];
+ input-protection-padding none;</pre>
-<p><strong>Example 2:</strong> An resource wishes to receive reports when the
-UI Safety heuristic is triggered for any element in the <code><body></code>
-:</p>
+<p><strong>Example 2:</strong>A resource wishes to receive reports when the
+UI Safety heuristic is triggered for any element in the <code><body></code>,
+with the default 300 by 300 pixels reference area and 0 tolerance:</p>
<pre>Content-Security-Policy-Report-Only: input-protection;
report-uri https://example.com/csp-report?unique_id=XKSJ9KAAHJDK9928KKSJEQ</pre>
@@ -883,5 +829,41 @@
of the Content-Security-Policy and Content-Security-Policy-Report-Only headers, so
no updates to the permanent message header field registry (see [<a
href="http://tools.ietf.org/html/rfc3864">RFC3864</a>]) are required.
-</section></section></body>
+</section></section>
+
+<h2 class=no-num id=references>References</h2>
+
+ <h3 class=no-num id=normative-references>Normative references</h3>
+ <!--begin-normative-->
+ <!-- Sorted by label -->
+
+ <dl class=bibliography>
+ <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
+ <!---->
+
+ <dt id=bib-RFC2119>[RFC2119]
+
+ <dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key
+ words for use in RFCs to Indicate Requirement Levels.</cite></a> Internet
+ RFC 2119. URL: <a
+ href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
+ </dd>
+ <!---->
+
+ <dt id=bib-SELECTORS4>[SELECTORS4]
+
+ <dd>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>
+ </dd>
+ <!---->
+
+ </dl>
+ <!--end-normative-->
+
+
+
+</body>
</html>