Document Policy

Editor’s Draft,

This version:
https://w3c.github.io/webappsec-feature-policy/document-policy.html
Feedback:
public-webappsec@w3.org with subject line “[document-policy] … message topic …” (archives)
Editor:
(Google)

Abstract

This specification defines a mechanism that allows developers to ...

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Changes to this document may be tracked at https://github.com/w3c/webappsec.

The (archived) public mailing list public-webappsec@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “document-policy” in the subject, preferably like this: “[document-policy] …summary of comment…

This document was produced by the Web Application Security Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Introduction

This document defines Document Policy, which is a framework for designing configurable features as part of the web platform, and for allowing web developers to configure those features as part of their site deployment.

2. Examples #

Needs new examples. For now, see explainer.

Document Policy is similar in scope to some existing mechanisms for document configuration, though there are significant differences from each.

3.1. Relation to Feature Policy

Feature Policy [FEATURE-POLICY] is another mechanism which allows authors to configure features in documents, and is similar in scope, though it uses a different inheritance mechanism, which makes it more suitable for certain types of features, separate from those which are suitable for control by document policy.

Historically, document policy was created as a response to a number of proposed feature additions to feature policy, which either didn’t quite fit the existing 'feature' model, or required significant additional complexity to be added to the feature policy spec. This included features with parameters, features with optional inheritance into subframes, and features which would inherit differently in popups than in other top-level browsing contexts.

Those features are now proposed to be covered by document policy, and feature policy is used for features where delegation is the primary concern. Feature policy features are boolean-valued (either enabled or disabled), can never be re-enabled in a child frame if disabled in parent, and generally follow the model of "available in top-level browsing contexts and their same-origin children; must be delegated to cross-origin frames."

In contrast, features controlled by document policy may take parameters, and those parameters may have unrelated values in different frames (constraining a feature in a parent frame does not necessarily constrain its child frames.)

3.2. Relation to Content Security Policy

Content-Security-Policy [CSP] also configures 'features' in documents, although it is primarily concerned with the origin of resources in a page, rather than controlling what those resources can do once loaded.

CSP also provides a different mechanism for setting sandbox flags on a document, through the sandbox directive. If sandbox flags are moved to document policy, then this may be redundant, as the two headers may encode identical information.

CSP-Embedded-Enforcement introduced a model for forcing a policy to be adhered to by child documents, and for rejecting non-conforming documents as network errors during Fetch. This model is adopted by document policy for the required policy mechanism.

3.3. Relation to Sandboxing

Iframe sandboxing is another mechanism for controlling features in documents, and behaves in a very similar manner to document policy’s required policies: disabling a feature is something that can be imposed on a frame, and affects all content loaded into that frame.

The features which are controlled by the iframe sandbox attribute could be expressed very naturally with document policy.

One key difference between iframe sandboxing and document policy is that all sandbox features are applied by default when the 'sandbox' attribute is used on a frame, and must be re-enabled one-by-one. This makes it very difficult to extend the sandboxing model with new features, as any additions will immediately affect all existing sandboxed content. Additionally, there is no mechanism for the origin server to know that its content will be sandboxed, so it is difficult to add new sandbox features which could potentially alter control flow in a sandboxed document, as this could introduce new security vulnerabilities in existing content.

4. Framework

4.1. Features

A feature is defined by

  • A name, which is a token,

  • A value type, which is either boolean, integer, float, or enum,

  • A value range, which is a subset of the possible values for the feature’s type, and

  • A default value, which is an element of the feature’s value range.

When introducing a new feature, the default value should be chosen carefully, with highest consideration given to web compatibility. When no explicit policy has been declared for a document, the default value will be in effect.

4.2. Policies

  • Browsing context has a required document policy, which is a document policy.

  • Browsing context has a nested context required document policy, which is a document policy.

  • Document has a declared document policy, which is a document policy.

A document policy is an ordered map from features to values.

4.3. Values

  • Policies have values for features

  • Values have domains

  • Domains have ordering

  • Examples: positive ints, floats, bools, enums

4.4. Default Values

  • features have default values.

  • (Non-normative) Defaults are chosen for web compatibility.

5. Required Policy Serialization

  • Explain here how required policies are serialized as structured headers.

  • Ensure that there is a canonical form (for compat testing).

6. Delivery

6.1. Policies as Structured Headers

Policies are represented in HTTP headers and in HTML attributes as the serialization of an sh-list structure. The list members are tokens, each corresponding to a policy directive. Each token may take a single parameter; the details of the parameter name and allowed values are determined by the value type of the feature which the token names.

6.1.1. Boolean-valued features

Boolean-valued features do not take any parameters. They may be expressed in headers by simply naming them, to enable the feature, or naming them with a prefix of 'no-', to disable the feature.

Examples:

  • boolean-feature

  • no-boolean-feature

6.1.2. Integer-valued features

Integer-valued features should have a single parameter, whose name is defined by the feature, and whose value should be an Integer. The range of Integers allowed should be defined by the feature.

Examples:

  • integer-feature;p=2

6.1.3. Float-valued features

Float-valued features should have a single parameter, whose name is defined by the feature, and whose value should be a Float. The range of Floats allowed should be defined by the feature.

Examples:

  • float-feature;q=-0.2

6.1.4. Enum-valued features

Enum-valued features should take a parameter with no value. The allowed values for the enum should be used as the parameter name.

Examples:

  • enum-feature;state

6.2. HTTP Headers

6.2.1. Document-Policy

The `Document-Policy` HTTP header can be used in the response (server to client) to communicate the document policy that should be enforced by the client.

The Document-Policy header is a Structured Header. Its value must be a list. Its ABNF is:

Document-Policy = sh-list

Each list element must be a token. If the token does not name a supported feature, (or a supported boolean feature prefixed by "no-",) then the list element must be ignored.

6.2.2. Require-Document-Policy

The `Require-Document-Policy` HTTP header field is a response header which is used to communicate to the client the minimum required document policy to apply to all nested content.

The Require-Document-Policy header is a Structured Header list, with exactly the same syntax as the Document-Policy header.

6.2.3. Sec-Required-Document-Policy

The `Sec-Required-Document-Policy` HTTP header field is a request header which is used to communicate to the server the document policy which must be sent with the document returned with the request.

The header’s value is the § 5 Required Policy Serialization of one or more policy directives

6.3. The policy attribute of the iframe element

iframe elements have a "policy" attribute, which contains a required policy directive (SH format).

7. Integrations

If a frame has a required policy, then that policy must be advertised in the request header for any outgoing document requests, to inform the server of the policy which will be applied to the document by the user agent. This allows the server to alter the representation which is returned, to conform to that policy.

In the case where a required policy request header is present, the response must contain a compatible document policy header, or the fetch will fail.

7.1. Integration with HTML

The following changes should be incorporated into [HTML]:

  • iframe elements should have the following IDL added:

        [CEReactions] attribute DOMString policy;

7.2. Integration with Fetch

The following changes should be incorporated into [FETCH]:

internalResponse to request be blocked due to document policy

8. Algorithms

8.1. Is policy compatible?

Given a required document policy requiredPolicy and a declared document policy declaredPolicy, this algorithm returns true if declaredPolicy is compatible with requiredPolicy, or false otherwise.

  1. For each featurevalue in requiredPolicy:

    1. If feature does not require acknowledgement, then continue.

    2. If declaredPolicy[feature] does not exist, then return false.

    3. If requiredPolicy[feature] is stricter than declaredPolicy[feature], then return false.

  2. Return true.

8.2. Process response policy

Given a response (response), this algorithm returns a declared document policy.

  1. Abort these steps if the response’s header list does not contain a header whose name is "Document-Policy".

  2. Let header be the concatenation of the values of all header fields in response’s header list whose name is "Document-Policy", separated by U+002C (,) (according to [RFC7230, 3.2.2]).

  3. Let document policy be the result of executing Parse document policy on header.

  4. Return document policy.

8.3. Parse document policy

Given a string (policyString), this algorithm returns a document policy, if it can be parsed as one, or else fails.

  1. Let policy be a new ordered map.

  2. Let list be the result of parsing policyString as a list.

  3. If parsing fails, then fail.

  4. For each element in list,

    1. If element is not a token, then fail

    2. If element is the name of a supported feature which is a boolean feature, then

      1. If element has any associated parameters, then fail.

      2. Let feature be the supported feature with name element.

      3. If policy[feature] exists, then continue with the next element.

      4. Set policy[feature] to the boolean value true.

      5. Continue with the next element.

    3. If element begins with the string "no-", and the remaining characters match the name of a supported feature which is a boolean feature, then

      1. If element has any associated parameters, then fail.

      2. Let feature be the supported feature with name element.

      3. If policy[feature] exists, then continue with the next element.

      4. Set policy[feature] to the boolean value false.

      5. Continue with the next element.

    4. If element is the name of a supported feature, then

      1. If element does not have exactly one parameter, then fail.

      2. Let feature be the supported feature with name element.

      3. If policy[feature] exists, then continue with the next element.

      4. If feature is an enum-valued feature, then

        1. If element’s parameter has a value, then fail.

        2. Let value be the name of element’s parameter.

        3. If value is not the name of one of features allowed enum values, then fail.

        4. Let policy[feature] be the enum value named value.

        5. Continue with the next element.

      5. If element’s parameter’s name does not match feature’s parameter name, then fail.

      6. Let value be the value of element’s parameter.

      7. If feature is an integer-valued feature, then

        1. If value is not an integer, then fail.

        2. If value is not in feature’s range, then fail.

        3. Let policy[feature] be the integer value value.

        4. Continue with the next element.

      8. If feature is an float-valued feature, then

        1. If value is not a float, then fail.

        2. If value is not in feature’s range, then fail.

        3. Let policy[feature] be the float value value.

        4. Continue with the next element.

  5. Return policy.

8.4. Serialize required policy

Given a document policy (requiredPolicy), this algorithm returns a string which represents the canonical serialization of the policy.

  1. Let list be an empty sh-list

  2. Let features be the keys of requiredPolicy

  3. Sort features by the name of each element, in ASCII order.

  4. For each feature in features:

    1. If feature is a boolean-valued feature, then

      1. If requiredPolicy[feature] is true, append feature’s name to list.

      2. Otherwise, append the sh-token formed by concatenating the string "no-" and feature’s name to list.

    2. Otherwise, if feature is an enum-valued feature, then

      1. Let value be requiredPolicy[feature].

      2. Let param be a parameter with param-name value and with no param-value.

      3. Append an sh-item which is an sh-token formed from feature’s name, with the single parameter param, to list.

    3. Otherwise,

      1. Let value be requiredPolicy[feature].

      2. Let param be a parameter with param-name being features’s parameter name, and with param-value value.

      3. Append an sh-item which is an sh-token formed from feature’s name, with the single parameter param, to list.

  5. Return the serialization of list.

8.5. Create a required policy for a browsing context

Given a browsing context (browsingContext), this algorithm returns a new Document Policy.

  1. If browsingContext is a nested browsing context, then

    1. Let requiredPolicy be a clone of browsingContext’s browsing context container’s nested context required document policy.

    2. If browsingContext’s browsing context container has a "policy" attribute, then

      1. Let somethingPolicy be the result of parsing the attribute

      2. For each feature -> value in somethingPolicy:

        1. If requiredPolicy[feature] does not exist, or if value is stricter than requiredPolicy[feature], then set requiredPolicy[feature] to value.

  2. Otherwise, let requiredPolicy be a new ordered map.

  3. return requiredPolicy.

8.6. Create a document Policy for a browsing context from response

Given a browsing context (browsingContext) and a response (response), this algorithm returns a new Document Policy.

  1. Let requiredPolicy be the result of running Create a required policy for a browsing context given browsingContext.

  2. Let declaredPolicy be the result of running Process response policy on response.

  3. If declaredPolicy is compatible with requiredPolicy, then return declaredPolicy.

  4. Throw an exception.

8.7. Should response to request be blocked due to document policy?

  1. If request has a required document policy, then

    1. Let documentPolicy be the result of getting and parsing the structured header Document-Policy as "list" from response’s header list.

    2. If documentPolicy is not compatible with request’s required document policy, return "blocked".

    3. Return "valid".

8.8. Get policy value for feature in document

Given a feature (feature) and a Document object (document), this algorithm the value for feature in document’s document policy.

  1. Let policy be document’s Document Policy.

  2. If policy[feature] exists, return it.

  3. Return feature’s default value.

9. IANA Considerations

The permanent message header field registry should be updated with the following registrations [RFC3864]:

Header field name
Document-Policy
Applicable protocol
http
Status
standard
Author/Change controller
W3C
Specification document
Document Policy API
Header field name
Require-Document-Policy
Applicable protocol
http
Status
standard
Author/Change controller
W3C
Specification document
Document Policy API
Header field name
Sec-Required-Document-Policy
Applicable protocol
http
Status
standard
Author/Change controller
W3C
Specification document
Document Policy API

10. Privacy and Security

This is going to be very similar to feature policy, with these notes:

  1. Opt-in generally required to enable enforcement in subframes.

  2. Policy attribute may conflict with sandbox attribute

  3. Observability? Yes, still. Take care when designing features that their effects cannot be seen across origin boundaries.

  4. Take care in creating non-reflect features

This specification standardizes a mechanism for an embedding page to set a policy which will be enforced on an embedded page. When explicit acknowlegement of a required policy is not required, similar to iframe sandbox, this means that behaviors of existing features may be changed in published web sites, by embedding them in another document with an appropriate required policy.

As such, the biggest privacy and security concerns are:

To a degree, these concerns are already present in the web platform, and this specification attempts to at least not make them needlessly worse.

Security and privacy issues may also be caused by the design of individual features, so care must be taken when integrating with this specification. This section attempts to provide some guidance as to what kinds of behaviors could cause such issues.

10.1. Exposure of cross-origin behavior {#exposure-of-cross-origin-behavior}

Features should be designed such that a violation of the policy in a framed document is not observable by documents in other frames. For instance, a hypothetical feature which caused a event to be fired in the embedding document if it is used while disabled by policy, could be used to extract information about the state of an embedded document. If the feature is known only to be used while a user is logged in to the site, for instance, then the embedder could disable that feature for the frame, and then listen for the resulting events to determine whether or not the user is logged in.

10.2. Unanticipated behavior changes

Document policy grants a document the ability to control which features will and will not be availble in a subframe at the time it is loaded. When a feature represents an existing, long-standing behavior of the web platform, this may mean that existing published content on the web was not written with the expectation that a particular API could fail.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

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.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[FEATURE-POLICY]
Ian Clelland. Feature Policy. 16 April 2019. WD. URL: https://www.w3.org/TR/feature-policy-1/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HEADER-STRUCTURE]
Mark Nottingham; Poul-Henning Kamp. Structured Headers for HTTP. Draft. URL: https://tools.ietf.org/html/draft-ietf-httpbis-header-structure-14
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3864]
G. Klyne; M. Nottingham; J. Mogul. Registration Procedures for Message Header Fields. September 2004. Best Current Practice. URL: https://tools.ietf.org/html/rfc3864

Informative References

[CSP]
Mike West. Content Security Policy Level 3. 15 October 2018. WD. URL: https://www.w3.org/TR/CSP3/