Intent to Implement: Document Policy
Ian Clelland
Contact emails
Explainer
https://github.com/w3c/webappsec-feature-policy/blob/master/document-policy-explainer.md
TAG review
https://github.com/w3ctag/design-reviews/issues/408
Summary
Document Policy is a mechanism to allow documents to configure the web platform on which they operate: restricting certain behaviours or APIs, configuring defaults, or enabling new platform features. It also includes a way for documents to require such restrictions on sub-documents embedded in iframes.
(The actual capabilities are intentionally vague here; this is a framework for individual features to be defined in, rather than being a set of concrete features itself)
Motivation
Currently, it is not possible to restrict the surface area of the web platform on a per-document basis; Iframe sandboxing goes part of the way to help with this, but is difficult to extend, and has strict security-focused semantics. We would like to enable such ideas as:
Restricting the use of poorly-performing images
Disabling slow synchronous JS APIs
Configuring frame, image or script loading styles
Restricting overall document sizes or network usage
Restricting patterns which cause slow page re-layout
among other things. These restrictions should be opt-in by developers, and do not necessarily need to extend to a frame's embedded content or popups.
Feature policy has been proposed a number of times as a mechanism for accomplishing this, but the existing feature policy spec is not particularly well suited to it, as it has focused strongly on the "delegating powerful features to third parties" model. In particular, the syntax is designed around boolean feature states, and the processing model expects that frames cannot ever be configured independently of their embedders.
Previous attempts to graft these ideas on to feature policy have resulted in a spec which is much harder to reason about, and more complex to implement and use, than having two distinct mechanisms. (see, for example, https://github.com/w3c/webappsec-feature-policy/issues/163, and https://github.com/w3c/webappsec-feature-policy/issues/252)
Risks
Interoperability and Compatibility
Interop risks here are two-fold:
If sites begin to use this to impose restrictions on themselves, and update their content to adhere to those restrictions, the interop risk is quite low -- the site will still adhere to the restrictions even with this feature removed, or unimplemented in other browsers.
Use of "required document policies" has similar interop risks as iframe sandboxing: An embedding page may be written with the belief that certain behaviours will be restricted in a subframe, while in fact the subframe may be unrestricted if this feature is removed from the platform. This could carry significant risk if Document Policy becomes an established, ubiquitous part of the web platform and is then removed, but until then, sites will need to be aware that Document Policy may not be implemented in every browser (similar to the situation with sandbox flags) and consider that when embedding content.
Firefox: No public signals
Mozilla has been involved in many of the discussions that have led to this proposal; see https://github.com/w3c/webappsec-feature-policy/issues/282#issuecomment-486267212 for instance, and has been generally supportive of the idea. This is not a public stance on a particular spec yet, though.
Edge: No public signals
Safari: No public signals
Web developers: No signals
Ergonomics
This framework is intended as a way to configure/restrict other platform APIs. Ergonomically, it may end up that specifying configuration for many different features in a single header becomes unwieldy for developers, in which case we intend to look at a couple of mitigations: Grouping policies and allowing multiple features to be configured easily together, and integrating with Origin Policy, so that policies need only be specified in a single place. Neither of these are in scope for the initial implementation.
Other ergonomic risks include the use of structured headers as a serialization format; that proposal has wide support, but is not yet standard (a similar risk was taken with Feature Policy's initial use of JSON in headers, which was abandoned with that effort). Also, the requirement to reflect any required policies may be difficult for some developers, but is the safest route as far as security is concerned; we have considered adding something like an "Accept-Document-Policy-From" header (à la CORS), which would make embedding easier, but have not evaluated the security implications of that yet.
Activation
Sites which want to set policies for their own documents have very few challenges: as long as they have some control over their serving infrastructure and can set HTTP headers, they will be able to use this framework immediately.
For the 'required policy' embedding case, the challenge will be to incentivise site owners to set appropriate response headers in order to be embeddable by some documents. This challenge is similar to that faced by CORS and embedded CSP; documents which don't agree to be embedded in a given context simply can't be embedded.
Security
As this framework may end up taking the role of iframe sandboxing, there are several security concerns to take into account: When restrictions are imposed on a frame, it is important that that frames descendants also have the same restrictions. These restrictions cannot be unset or relaxed during the lifetime of a document; like sandboxing, a navigation/reload is required.
Additionally, since controlling the behaviour or availability of certain features from a parent document may alter control flow in a child frame, the concept of 'required policies', and the requirement that they be acknowledged by embedded content has been introduced.
The behavior in popups has been considered and is intended to match that of sandboxing.
Will this feature be supported on all six Blink platforms (Windows, Mac, Linux,
Chrome OS, Android, and Android WebView)?
Yes
Is this feature fully tested by web-platform-tests?
No
[WPT coming with spec]
Link to entry on the Chrome Platform Status
https://www.chromestatus.com/feature/5645593894453248
This intent message was generated by Chrome Platform Status.