Table of Contents

• 1. Introduction
• 2. Conformance
  • 2.1 Terminology
• 3. Directives
• 4. input-protection
• 5. input-protection-clip
• 6. input-protection-selectors
• 7. report-uri
  • 7.1 Producing blocked-target-xpath
• 8. DOM interface
• 9. Script Interfaces
  • 9.1 SecurityPolicyViolationEvent Events
    • 9.1.1 Attributes
    • 9.1.2 Dictionary SecurityPolicyViolationEventInit Members
  • 9.2 SecurityPolicy
    • 9.2.1 Attributes
• 10. Input Protection Heuristic
  • 10.1 Preparation
  • 10.2 UI Event handling
• 11. Alternate Heuristic
  • 11.1 Preparation
  • 11.2 UI Event handling
• 12. Examples
  • 12.1 Sample Policy Definitions
  • 12.2 Sample Violation Report
  • 12.3 Example Boundary Calculations for the Obstruction Check
• 13. Security Considerations
• 14. Implementation Considerations
  • 14.1 Accessibility Technologies
• 15. Implementation Considerations for Resource Authors
• 16. IANA Considerations
• A. References
  • A.1 Normative references
  • A.2 Informative references

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.

OWS            = *( SP / HTAB / obs-fold )
               ; "optional" whitespace
obs-fold       = CRLF ( SP / HTAB )
               ; obsolete line folding

dom_selectors_group
  : S* [ selectors_group ] S*
  ;

embedding-keyword-source = "'self'" / "'deny'"
embedding-source-expression = host-source / embedding-keyword-source
embedding-source-list = *WSP [ embedding-source-expression *( 1*WSP embedding-source-expression ) *WSP ]

3. Directives

This section describes the content security policy directives introduced in this specification.

4. input-protection

The input-protection directive, if present or implied, instructs the user agent to apply the heuristic UI redressing protections described in the Input Protection Heuristic section to user input events, such as click, keypress, touch, and drag, before they are delivered to the resource.

The screenshot comparison heuristic, in particular, uses the body-bounding rectangle of the document triggering the event as its default reference area, or the rectangle defined by the input-protection-clip and by the input-protection-selectors directives if any of those is explicitly set.

If the input-protection-clip directive is set as part of a Content-Security-Policy, triggering of the heuristic should cancel delivery of the UI event to the target and cause a violation report to be sent. If set as part of a Content-Security-Policy-Report-Only, triggering of the heuristic should result in the event being delivered with the unsafe attribute on the UIEvent set to true and cause a violation report to be sent.

The optional directive value allows resource authors to provide options for heuristic tuning in the form of space-separated option-name=option-value pairs.

directive-name    = "input-protection"
directive-value   = ["display-time=" num-val] ["tolerance=" num-val]

If the policy does not contain a value for this directive or any of the hint name=value pairs are absent, the user agent SHOULD apply default values for hints as described in the following.

display-time

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.

tolerance

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. If not specified, it defaults to 0.

5. 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, 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

x = eX - left, y = eY - top, width = left + right, height = top + bottom

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.

6. input-protection-selectors

The input-protection-selectors directive overrides the implicit or explicit input-protection-clip value when the processed UI event target or one of its DOM ancestors match the dom_selectors_group selector string 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 DOM 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 should be ignored (not blocked) unless an input-protection-clip directive is explicitly included in the policy: if this is the case, the UI event must be checked and the screenshot reference area should be computed using the input-protection-clip directive.

If set as part of a policy where no input-protection directive is explicitly set, the input-protection-selectors directive implies the input-protection directive as if it was set in the same policy with its default value.

directive-name  = "input-protection-selectors"
directive-value = ["before=" num-value] ["after=" num-value] ["above=" num-value] ["below=" num-value] dom_selectors_group

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.

The reference screenshot area is computed as the rectangle having

x = match.x - left, y = match.y - top, width = left + match.width + right, height = top + match.height + bottom

7. report-uri

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. [CSP]

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 input-protection 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.

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].

pointer-type

The pointerType value of a Pointer Event [POINTER-EVENTS].

pointer-height

The height value of a Pointer Event.

pointer-width

The width value of a Pointer Event.

device-height

The device-height property as defined in [CSS3-MEDIAQUERIES].

device-width

The device-width property as defined in [CSS3-MEDIAQUERIES].

blocked-event-client-x

The clientX attribute of the UIEvent [DOM-LEVEL-2-EVENTS] that was blocked by policy, if set.

blocked-event-client-y

The clientY attribute of the UIEvent [DOM-LEVEL-2-EVENTS] that was blocked by policy, if set.

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.

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);
}

8. DOM interface

This specification introduces a new attribute for the UIEvent interface introduced in DOM Level 2. [DOM-LEVEL-2-EVENTS]

partial interface UIEvent {
    [Unforgeable]
    readonly    attribute bool unsafe;
};

document.getElementById('payment-button').addEventListener("click", function(eventObj) {
  if ("unsafe" in eventObj) {
    if (eventObj.unsafe == true) {
      return reportUnsafeOrShowDialog();
    }
  }
  makePayment();
};

9. Script Interfaces

If associated with a Content Security Policy 1.1 [CSP11] or later implementation, the User Interface Security Directives include the following script interfaces which extend the experimental functinality defined therein: https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html#script-interfaces--experimental

[Constructor(DOMString type, optional SecurityPolicyViolationEventInit eventInitDict)]
partial interface SecurityPolicyViolationEvent : Event {
    readonly    attribute DOMString blockedEventType;
    readonly    attribute bool      touchEvent;
    readonly    attribute DOMString pointerType;
    readonly    attribute long      pointerHeight;
    readonly    attribute long      pointerWidth;
    readonly    attribute long      deviceHeight;
    readonly    attribute long      deviceWidth;
    readonly    attribute long      blockedEventClientX;
    readonly    attribute long      blockedEventClientY;
    readonly    attribute DOMString blockedTargetID;
    readonly    attribute DOMString blockedTargetXPath;
};

partial dictionary SecurityPolicyViolationEventInit {
    DOMString blockedEventType;
    bool      touchEvent;
    DOMString pointerType;
    long      pointerHeight;
    long      pointerWidth;
    long      deviceHeight;
    long      deviceWidth;
    long      blockedEventClientX;
    long      blockedEventClientY;
    DOMString blockedTargetID;
    DOMString blockedTargetXPath;
};

partial interface Security {
    readonly    attribute bool inputProtection;
};

12. Examples

Content-Security-Policy: input-protection

Content-Security-Policy: input-protection display-time 800;
        input-protection-selectors #send-button, .tweet, form

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]

Content-Security-Policy-Report-Only: input-protection; input-protection-clip;
                                     report-uri https://example.com/csp-report?unique_id=XKSJ9KAAHJDK9928KKSJEQ

Content-Security-Policy-Report-Only: input-protection

Content-Security-Policy: frame-options 'self' https://checkout.example.com
Content-Security-Policy-Report-Only: input-protection 

input-protection; report-uri https://example.org/csp-report.cgi?unique_id=12345

{
  "csp-report": {
    "document-uri": "http://example.org/page.html",
    "referrer": "http://evil.example.com/haxor.html",
    "blocked-event-type": "click",
    "blocked-event-client-x": "325",
    "blocked-event-client-y": "122",
    "touch-event": "false",
    "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"
  }
}

12.3 Example Boundary Calculations for the Obstruction Check

A resource at OriginX embeds a resource at OriginY. The OriginY resource has the following policy:

Content-Security-Policy: input-protection tolerance=50; input-protection-selectors div;

and results in the following layout:

The element with the id "div1" has an onClick handler defined, and a click event is triggered at 120,120 in the OriginX document's coordinate system. The red dot indicates the position of the event. The event is delivered to "div1", which matches the input-protection-selectors, and no parent of "div1" matches. As no input-protection-clip value is defined, the entire area of "div1" becomes the boundaries for the obstruction check, indicated by the cyan fill. As more than 50% of this area is occluded behind the iframe viewport, and so does not match by definition, this will trigger a violation.

If the OriginY protected resource set the following policy, instead:

Content-Security-Policy: input-protection tolerance=50; input-protection-selectors div; input-protection-clip before=60 after=60 above=60 below=60;

The region for the obstruction check, still indicated in solid cyan, is now only the intersection of the boundaries of the protected element handling the event, indicated by diagonal cyan lines, and the clipping window around the event, indicated by the green dotted line. If the OriginX resource has not painted anything over the iframe viewport, this check will not trigger a violation because the entire cyan area will be identical in the user image and control image.

If the OriginY protected resource omitted selectors, as in this policy:

Content-Security-Policy: input-protection tolerance=50; input-protection-clip before=60 after=60 above=60 below=60;

The region for the obstruction check, still indicated in solid cyan, is now the intersection of the boundaries of the entire document, indicated by diagonal cyan lines, and the clipping window around the event, indicated by the green dotted line. This demonstrates that portions of the protected resource may be included in the obstruction check region, even if they do not have event listeners. Thus, the hit test rectangles which trigger the heuristic do not necessarily compose the entire region that must be checked.

As in the previous example, if the OriginX resource has not painted anything over the iframe viewport, this check will not trigger a violation because the entire cyan area will be identical in the user image and control image.

16. 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.