Permissions policy is the new name for feature policy with a new HTTP header which uses structured header syntax. Code currently under feature_policy directory in chromium repository has not been renamed yet.
Permissions policy (see spec) is a mechanism that allows developers to selectively enable and disable various browser features an APIs (e.g, “vibrate”, “fullscreen”, “usb”, etc.). A permissions policy can be defined via a HTTP header and/or an iframe “allow” attribute.
Below is an example of a header policy (note that the header should be kept in one line, split into multiple for clarity reasons):
Permissions-Policy: vibrate=(), geolocation=(self https://example.com), camera=*
vibrate is disabled for all browsing contexts;geolocation is disabled for all browsing contexts except for its own origin and those whose origin is “https://example.com”;camera is enabled for all browsing contexts.Below is an example of a container policy:
<iframe allowpaymentrequest allow='vibrate; fullscreen'></iframe>
OR
<iframe allowpaymentrequest allow="vibrate 'src'; fullscreen 'src'"></iframe>
payment is enabled (via allowpaymentrequest) on all browsing contexts within the iframe;vibrate and fullscreen are enabled on the origin of the URL of the iframe's src attribute.Combined with a header policy and a container policy, inherited policy defines the availability of a feature. See more details for how to define an inherited policy for feature
A step-to-step guide with examples.
If the additional feature is unshipped, or if the correct behaviour with feature policy is undetermined, consider shipping the feature behind a runtime-enabled feature.
Permissions policy features are defined in third_party/blink/renderer/core/feature_policy/feature_policy_features.json5. Add the new feature, placing any runtime-enabled feature or origin trial dependencies in its “depends_on” field as described in the file's comments.
Append the new feature enum with a brief description as well in third_party/blink/public/mojom/feature_policy/feature_policy_feature.mojom.
Append the new feature name to PermissionsPolicyFeature enum in third_party/blink/public/devtools_protocol/browser_protocol.pdl.
The most common way to check if features are enabled is ExecutionContext::IsFeatureEnabled.
Examples:
vibrate: NavigatorVibration::vibrate()payment: AllowedToUsePaymentRequest()usb: USB::getDevices()To test the new feature with permissions policy, refer to third_party/blink/web_tests/external/wpt/feature-policy/README.md for instructions on how to use the permissions policy test framework.
Document Policy (see spec) is a similar mechanism to Feature Policy. It is intended
to cover those kinds of features which don't involve delegation of permission to trusted origins; features which are more about configuring a document, or removing features (sandboxing) from a document or a frame. Document Policy can only be set through HTTP header, and will not inherit to subframes.
Example HTTP header: Document-Policy: force-load-at-top=?0, lossy-images-max-bpp=1.0
force-load-at-top is set to boolean value false (?0 in structured header syntax), i.e. the feature is disallowed in current document;lossy-images-max-bpp is set to 1.0, i.e. lossy image format (e.g. jpeg) images with byte per pixel rate higher than 1.0 will be blocked.If the additional feature is unshipped, or if the correct behaviour with document policy is undetermined, consider shipping the feature behind a runtime-enabled feature.
Document policy features are defined in third_party/blink/renderer/core/feature_policy/document_policy_features.json5. Add the new feature, placing any runtime-enabled feature or origin trial dependencies in its “depends_on” field as described in the file's comments.
Append the new feature enum with a brief description as well in third_party/blink/public/mojom/feature_policy/document_policy_feature.mojom
The most common way to check if features are enabled is ExecutionContext::IsFeatureEnabled.
Please add new tests to third_party/blink/web_tests/external/wpt/document-policy/.
For more questions, please feel free to reach out to: iclelland@chromium.org chenleihu@google.com (Emerita: loonybear@)