From 3ae4d07e30670f278ffd2a77116d4430abba9d57 Mon Sep 17 00:00:00 2001 From: Barry Pollard Date: Thu, 10 Jun 2021 13:07:29 +0100 Subject: [PATCH] Update Permission Policy documentation (#10) * Update Permission Policy documentation * Mis reorders * Update links * Update README.rst Co-authored-by: Stargirl Flowers --- README.rst | 73 +++++++++++++++++++-------------- flask_talisman/talisman_test.py | 8 ++-- 2 files changed, 46 insertions(+), 35 deletions(-) diff --git a/README.rst b/README.rst index 24e54e1..918d81d 100644 --- a/README.rst +++ b/README.rst @@ -39,7 +39,8 @@ The default configuration: - Sets a strict `Referrer-Policy `_ of ``strict-origin-when-cross-origin`` that governs which referrer information should be included with requests made. -- Disables ingest-cohort by default in the `Permissions-Policy `_ like `Drupal `_ to enhance privacy protection. +- Disables interest-cohort by default in the `Permissions-Policy `_ + like `Drupal `_ to enhance privacy protection. In addition to Talisman, you **should always use a cross-site request @@ -327,6 +328,33 @@ As you can see above the policy can be defined simply just like the official specification requires the HTTP header to be set: As a semicolon separated list of individual CSP directives. +Feature Policy +-------------- + +**Note:** Feature Policy has largely been `renamed Permissions Policy `_ +in the latest draft and some features are likely to move to Document Policy. +At this writing, most browsers support the ``Feature-Policy`` HTTP Header name. +See the `Permissions Policy`_ and `Document Policy`_ sections below should you wish +to set these. + +Also note that the Feature Policy specification did not progress beyond the `draft https://wicg.github.io/feature-policy/` +stage before being renamed, but is `supported in some form in most browsers +`_. + +The default feature policy is empty, as this is the default expected behaviour. + +Geolocation Example +~~~~~~~~~~~~~~~~~~~ + +Disable access to Geolocation interface. + +.. code:: python + + feature_policy = { + 'geolocation': '\'none\'' + } + talisman = Talisman(app, feature_policy=feature_policy) + Permissions Policy ------------------ @@ -336,8 +364,16 @@ and it is recommended to still set the ``Feature-Policy`` HTTP Header. Permission Policy support is included in Talisman for when this becomes more widely supported. -The default permissions policy is empty, as this is the default expected behaviour. -Note that the `Permission Policy is still an Editor's Draft `_. +Note that the `Permission Policy is still an Working Draft `_. + +When the same feature or permission is set in both Feature Policy and Permission Policy, +the Permission Policy setting will take precedence in browsers that support both. + +It should be noted that the syntax differs between Feature Policy and Permission Policy +as can be seen from the ``geolocation`` examples provided. + +The default Permissions Policy is ``interest-cohort=()``, which opts sites out of +`Federated Learning of Cohorts `_ an interest-based advertising initiative. Permission Policy can be set either using a dictionary, or using a string. @@ -370,8 +406,9 @@ and it is recommended to still set the ``Feature-Policy`` HTTP Header. Document Policy support is included in Talisman for when this becomes more widely supported. -The default permissions policy is empty, as this is the default expected behaviour. -Note that the `Document Policy is still an Editors Draft `_. +Note that the `Document Policy is still an Unofficial Draft `_. + +The default Document Policy is empty, as this is the default expected behaviour. Document Policy can be set either using a dictionary, or using a string. @@ -394,32 +431,6 @@ Forbid oversized-images using string syntax: document_policy = 'oversized-images=?0' talisman = Talisman(app, document_policy=document_policy) -Feature Policy --------------- - -Note: Feature Policy has largely been `renamed Permissions Policy `_ -in the latest draft and some features are likely to move to Document Policy. -At this writing, most browsers support the ``Feature-Policy`` HTTP Header name._ -See the `Permissions Policy`_ and `Document Policy`_ sections should you wish -to set these. - -The default feature policy is empty, as this is the default expected behaviour. -Note that the Feature Policy is still a `draft https://wicg.github.io/feature-policy/` -but is `supported in some form in most browsers -`_. - -Geolocation Example -~~~~~~~~~~~~~~~~~~~ - -Disable access to Geolocation interface. - -.. code:: python - - feature_policy = { - 'geolocation': '\'none\'' - } - talisman = Talisman(app, feature_policy=feature_policy) - Disclaimer ---------- diff --git a/flask_talisman/talisman_test.py b/flask_talisman/talisman_test.py index b912f75..0c77874 100644 --- a/flask_talisman/talisman_test.py +++ b/flask_talisman/talisman_test.py @@ -283,8 +283,8 @@ def testFeaturePolicy(self): def testPermissionsPolicy(self): # default disabled FLoC response = self.client.get('/', environ_overrides=HTTPS_ENVIRON) - document_policy = response.headers['Permissions-Policy'] - self.assertIn('interest-cohort=()', document_policy) + permissions_policy = response.headers['Permissions-Policy'] + self.assertIn('interest-cohort=()', permissions_policy) self.talisman.permissions_policy['geolocation'] = '()' response = self.client.get('/', environ_overrides=HTTPS_ENVIRON) @@ -300,8 +300,8 @@ def testPermissionsPolicy(self): # no policy self.talisman.permissions_policy = {} response = self.client.get('/', environ_overrides=HTTPS_ENVIRON) - document_policy = response.headers.get('Permissions-Policy') - self.assertEqual(None, document_policy) + permissions_policy = response.headers.get('Permissions-Policy') + self.assertEqual(None, permissions_policy) # string policy at initialization app = flask.Flask(__name__)