Document Policy: a new Permissions Policy extension

Roeland Kuiper -

Sometimes your website has to rely on content from other sources—embedding content through an iframe or embedding a document like a PDF, for instance. When loading data through an iframe, the content may not conform with the standards you set for your site, like loading time, effective network usage, etc. Another risk when embedding documents is that the source could get hacked, causing your site to embed and execute malicious code or show unwanted content.

There are many permissions currently available to webdevs to limit what the content in an iframe can do. It's called the sandbox attribute. When an iframe with the attribute sandbox is loaded, the browser can adjust the iframe privileges. For instance, it can do the following:

  • treat the content as being from a unique origin
  • block form submission
  • block script execution
  • disable APIs
  • prevent links from targeting other browsing contexts
  • prevent content from using plugins (through <embed>, <object>, <applet>, or others)
  • prevent the content from navigating its top-level browsing context
  • block automatically triggered permissions (such as automatically playing a video or automatically focusing a form control)

The webdev can specify whether all or just a selection of these permissions should be sandboxed. In this way, it's possible to block form submissions but allow API calls within the iframe.

The rise of the Permission Policy

As an addition to the iframe sandbox permissions (and other stuff), the Permissions Policy (previously referred to as Feature Policy) header was created. Permissions Policy allows webdevs to selectively enable, disable, and modify the behavior of certain features and APIs in the browser. It is similar to Content Security Policy but controls features instead of security behavior, hence the name. Permissions Policy also uses the Reporting API (again, like the Content Security Policy) to report violations to a monitoring tool like URIports.com 🤘

In a nutshell: Permissions Policy allows you to opt-in to a set of policies for the browser to enforce on specific features used throughout your website. These policies can restrict what browser APIs your website can access or modify. Here are some examples:

  • Change the default behavior on auto-play videos
  • Restrict a site from using the camera or microphone
  • Block outdated APIs like synchronous XHR
  • Ensure images are appropriately sized for the current viewport
  • and many more!

Extending Permissions Policy with Document Policies

There is a proposal for extending the Permissions Policy with what is called Document Policies. These are less security-focused policies and more about configuring a document or removing extra features from a document or iframe (like sandboxing).

You might be thinking: Why use Document Policies when we already have sandboxed iframes with many configurable options? The idea of Document Policies is to be a framework for individual features that can be defined instead of being a set of concrete features itself. And while iframe sandboxing does a lot, it has very security-focused semantics and is challenging to extend. Document Policies try to fix that by creating an extensible framework.

So how do Document Policies work?

Document Policies can be set in the HTTP response headers of a resource. It sets the policy on the document that it's served with. It's possible to create restrictions on image sizes, compression ratios, lazy loading of frames, use of sync API calls, etc.

Document Policies can be used in multiple ways. Here are the two most important: HTTP headers and iframes.

HTTP headers

The main document, like index.html, is loaded with a response header like:

Document-Policy: no-unsized-media, no-document-write,
                 image-compression;bpp=2, frame-loading;lazy

Now when embedded content is being loaded on that page, the request header for that embedded content will also send:

GET / HTTP/1.1
Host: img.example.com
Sec-Required-Document-Policy: no-unsized-media,image-compression;bpp=2

Now the browser asks for the content and gives the set document policies that the content must comply with. If the content doesn't comply with the request document policy, the content will be discarded.

Iframe

It is possible to set the document policy in the iframe-tag like so:

<iframe src="https://img.example.com/" policy="image-compression;bpp=2">

The GET request headers will then look like this:

GET / HTTP/1.1
Host: img.example.com
Sec-Required-Document-Policy: image-compression;bpp=2

So now, the loaded document in the iframe must have good image compression. If not, it will be discarded.

Document Policies and iframe sandboxing are close friends and should be used together for an ultimate fine-tuning and control of embedded content through iframes. Read the complete proposal for Document Policies, including some excellent samples.

Why should you use Document Policies?

When using Document Policies, you can get a little more grip on embedded content on your site. Sandboxing an iframe helps a lot but is security-focused. Document Policy is an extension of Permissions Policy and allows you to fine-tune a policy for the structure of a document. Like:

  • Restricting the use of poorly performing images
  • Disabling slow synchronous JS APIs
  • Configuring frame, image, or script loading styles
  • Restricting overall document sizes or network usage
  • Restricting patterns that cause slow page re-layout

It has the potential of being an excellent tool to get more control over what content is embedded on your site.

When to start implementation

Since the Document-Policy extension is still just a proposal, I don't recommend implementing this just yet. Even though Chrome has released an Intent to Implement, no other browsers have shown public signals of doing the same at the time of writing. We will keep an eye on future developments and keep you updated. The proposal looks promising, so I think we will hear more about this extension in the near future.

Reporting Document Policy violations

Because Document Policies will be an extension of Permissions Policy, violations can easily be tracked in your URIports.com account under the section Permissions Policy.

We'll keep you updated in this blog when Document Policies is implemented in Chrome and when other browsers show public signs of implementing this new technology.

Thanks for reading!