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, it is possible that the content doesn't conform with the standards you set for your own 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 features 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:

  • 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 other)
  • prevent the content to navigate its top-level browsing context
  • block automatically triggered features (such as automatically playing a video or automatically focusing a form control)

The webdev can specify if all these features or a selection of it is sandboxed. This way it's possible to block form submissions, but allow API-calls within the iframe.

The rise of the Feature Policy

As an addition to the iframe sandbox features (and other stuff), the Feature Policy header was created. Feature 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. Feature 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; Feature 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 API's your website can access or modify. Here are some examples:

  • Change the default behavior on autoplaying videos
  • Restrict a site from using the camera or microphone
  • Block outdated API's like synchronous XHR
  • Ensure images are sized properly for the current viewport
  • and many more!

Extending Feature Policy with Document Policies

There is a proposal for extending the Feature Policy with what is called "Document Policies". Those are policies that are less security focused and more about configuring a document or remove 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 difficult 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.

There are multiple proposed ways to use Document Policies. 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 an 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 is asking 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:

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 a good image compression. If not, it will be discarded.

Document Policies and iframe sandboxing are close friends and can 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 nice 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 really security focused. Document Policiy is an extension for Feature 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 which cause slow page re-layout

It has the potential of being an awesome 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, at the time of writing, no other browsers have shown public signals of doing the same. 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 of Document Policies violations

Because Document Policies will be an extension on Feature Policy, violations can easily be tracked in your URIports.com account under the section Feature 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!