From 7b325873cc3993ef19ad02902f4d9706b37bdbe1 Mon Sep 17 00:00:00 2001 From: Ian Clelland Date: Wed, 7 Aug 2019 11:43:35 -0400 Subject: [PATCH] Create document-policy-explainer.md (#328) Add a first draft of an explainer for document policies (Thanks @Malvoz, @eeeps, @huchenlei, @sideshowbarker, @foolip, @annevk for review) --- document-policy-explainer.md | 341 +++++++++++++++++++++++++++++++++++ 1 file changed, 341 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..9e9f7b4e --- /dev/null +++ b/document-policy-explainer.md @@ -0,0 +1,341 @@ +# 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=2'.) + +### 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 +