From 0ef8efe571811122c427eaf52968c4644a988b61 Mon Sep 17 00:00:00 2001 From: Ian Clelland Date: Wed, 24 Jul 2019 15:56:57 -0400 Subject: [PATCH 1/4] Create document-policy-explainer.md Add a first draft of an explainer for document policies --- document-policy-explainer.md | 337 +++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 document-policy-explainer.md diff --git a/document-policy-explainer.md b/document-policy-explainer.md new file mode 100644 index 00000000..1e15d17f --- /dev/null +++ b/document-policy-explainer.md @@ -0,0 +1,337 @@ +# Feature Policy: Document Policies + +This is a proposal for an extension to Feature Policy 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. + +## Start with Examples! + +### Performance guardrails + +The simplest example is a site which wants to enforce some performance +best-practices on their own content. They can do this by serving their HTML +content with this HTTP header: + +```http +Document-Policy: no-unsized-media, no-document-write, + image-compression;bpp=2, frame-loading;lazy +``` + +A document served with this header may embed other content, first- or +third-party, and that content will not be subject to those restrictions. That +content may include its own `Document-Policy` header, but the headers do not +combine in any way. + +### Enforcing performance guardrails on embedded content + +In this example, the top level document wants to ensure that the content loaded +into a particular frame uses best practices regarding its images. All images +should have declared sizes, and should be reasonably compressed. It includes an +iframe tag like this: + +```html + + + + + +``` + +Would result in these three (simplified) HTTP requests: + +```http +GET / HTTP/1.1 +Host: a.example.com +Sec-Required-Document-Policy: image-compression;bpp=2,no-unsized-media +``` + +```http +GET / HTTP/1.1 +Host: b.example.com +Sec-Required-Document-Policy: image-compression;bpp=1 +``` + +```http +GET / HTTP/1.1 +Host: c.example.com +Sec-Required-Document-Policy: image-compression;bpp=2 +``` + +(Note that in the last example, the stricter requirements imposed by the +top-level document subsume the requirements on the nested frame, so the combined +threshold value is still 'bpp=4'.) + +### Sandboxing nested content (Traditional sandbox) + +```html + + policy="image-compression;bpp=1"> + policy="image-compression;bpp=4"> ``` @@ -128,13 +128,17 @@ threshold value is still 'bpp=4'.) ### Sandboxing nested content (Traditional sandbox) +As examples of different ways to sandbox content using a combination of the +`sandbox` and `policy` attributes, the following could all be used to create a +sandboxed iframe: + ```html