Mike West on web.dev

Confound malicious middlemen with HTTPS and HTTP Strict transport security

2013-02-14T00:00:00Z

Given the amount of personal data that flows through the great series of tubes that is the internet, encryption isn't something that we can or should lightly ignore. Modern browsers offer several mechanisms you can use to ensure that your users' data is secure while in transit: secure cookies and Strict Transport Security are two of the most important. They allow you to seamlessly protect your users, upgrading their connections to HTTPS, and providing a guarantee that user data is never sent in the clear.

Why should you care? Consider this:

Delivering a web page over an unencrypted HTTP connection is more or less the same as handing an unsealed envelope to the first person you see on the street who looks like she's walking in the direction of the post office. If you're lucky, she might take it all the way there herself, or she might hand it off to the next person she sees who's headed the right way. That person might do the same, and so on.

Most strangers in this impromptu chain are trustworthy, and would never peek at your open letter or alter it. The more times the letter changes hands, however, the greater the number of people with complete access to the letter you're sending. In the end, it's quite likely that your letter's intended recipient will get something in the mail, but whether that something is the same something that you handed off in the first place is an open question. Maybe you should have sealed that envelope…

Middlemen #

For better or worse, huge swaths of the internet rely on the trustworthiness of strangers. Servers aren't directly connected to each other, but pass requests and responses along from router to router in an enormous game of Telephone.

You can see these hops in action with traceroute. The route from my computer to HTML5Rocks looks something like this:

$ traceroute html5rocks.com
traceroute to html5rocks.com (173.194.71.102), 30 hops max, 60 byte packets
 1  router1-lon.linode.com (212.111.33.229)  0.453 ms
 2  212.111.33.233 (212.111.33.233)  1.067 ms
 3  217.20.44.194 (217.20.44.194)  0.704 ms
 4  google1.lonap.net (193.203.5.136)  0.804 ms
 5  209.85.255.76 (209.85.255.76)  0.925 ms
 6  209.85.253.94 (209.85.253.94)  1.226 ms
 7  209.85.240.28 (209.85.240.28)  48.714 ms
 8  216.239.47.12 (216.239.47.12)  22.575 ms
 9  209.85.241.193 (209.85.241.193)  36.033 ms
10  72.14.233.180 (72.14.233.180)  43.222 ms
11  72.14.233.170 (72.14.233.170)  43.242 ms
12  *
13  lb-in-f102.1e100.net (173.194.71.102)  44.523 ms

13 hops isn't bad, really. However, if I'm sending requests via HTTP, then each of those intermediate routers has complete access to my requests and to the servers' responses. All the data is being transferred as unencrypted plaintext, and any of those intermediaries could act as a Man in the Middle, reading through my data, or even manipulating it in transit.

Worse, this sort of interception is virtually undetectable. A maliciously modified HTTP response looks exactly like a valid response, as no mechanism exists that would enable you to ensure that the data received is _exactly _the data sent. If someone decides to turn my Internet upside-down for laughs, then I'm more or less out of luck.

Is this a secure line? #

Switching from plaintext HTTP to a secured HTTPS connection offers your best defense against middlemen. HTTPS connections encrypt the entire channel end-to-end before any data is sent, making it impossible for machines between you and your destination to read or modify data in transit.

Chrome's Omnibox gives quite a bit of detail about a connection's status.

The security HTTPS provides is rooted in the concept of public and private cryptographic keys. A deep discussion of the details is (happily) well beyond the scope of this article, but the core premise is fairly straightforward: data encrypted with a given public key can only be decrypted with the corresponding private key. When a browser kicks off an HTTPS handshake to create a secure channel, the server provides a certificate which gives the browser all the information necessary in order to verify its identity by checking that the server is in possession of the proper private key. All communication from that point forward is encrypted in such a way that proves that requests are delivered to and responses received from the authenticated server.

HTTPS, therefore, gives you some assurance that you're talking to the server you think you're talking to, and that no one else is listening in or twiddling bits on the wire. This kind of encryption is an absolute prerequisite for security on the web; if your application isn't currently delivered over HTTPS, it's vulnerable to attack. Fix it. Ars Technica has a great guide to obtaining and installing a certificate (for free) that I'd recommend you take a look at for technical details. Configuration will differ from provider to provider and server to server, but the certificate request process is the same everywhere.

Secure by default #

Once you've requested and installed a certificate, make sure your users benefit from your hard work: migrate your existing users to HTTPS connections transparently via the magic of HTTP redirection, and ensure that cookies are only delivered over secure connections.

This way, please #

When a user visits http://example.com/, redirect them to https://example.com/ by sending a 301 Moved Permanently response with an appropriate Location header:

$ curl -I http://mkw.st/
HTTP/1.1 301 Moved Permanently
Server: nginx/1.3.7
...
Keep-Alive: timeout=20
Location: https://mkw.st/

You can set up this sort of redirection easily in servers like Apache or Nginx. For example, an Nginx configuration that redirects from http://example.com/ to https://example.com/ looks like this:

server {
    listen [YOUR IP ADDRESS HERE]:80;
    server_name example.com www.example.com;
    location "/" {
        rewrite ^(.*) https://www.example.com$1 permanent;
    }
}

Cookies give us the ability to provide users with seamless logged-in experiences over the stateless HTTP protocol. Data stored in cookies, including sensitive information like session IDs, is sent along with every request, allowing the server to make sense of which user it's responding to at the moment. Once we've ensured that users are hitting our site over HTTPS, we should also ensure that the sensitive data stored in cookies is only ever transferred over a secure connection, and never sent in the clear.

Setting a cookie generally involves an HTTP header that looks something like this:

set-Cookie: KEY=VALUE; path=/; expires=Sat, 01-Jan-2022 00:00:00 GMT

You can instruct the browser to restrict the cookie's use to secure sessions by tacking on a single keyword:

Set-Cookie: KEY=VALUE; path=/; expires=Sat, 01-Jan-2022 00:00:00 GMT; secure

Cookies set with the secure keyword won't be sent over HTTP, ever.

Closing the open window #

Transparent redirection to HTTPS means that the vast majority of the time your users are on your site, they'll be using a secure connection. It does, however, leave a small window of opportunity for attack: the initial HTTP connection is wide open, vulnerable to SSL stripping and related attacks. Given that a man in the middle has complete access to the initial HTTP request, it can act as a proxy between you and the server, keeping you on an insecure HTTP connection regardless of the server's intentions.

You can mitigate the risk of this class of attack by asking the browser to enforce HTTP Strict Transport Security (HSTS). Sending the Strict-Transport-Security HTTP header instructs the browser to do the HTTP to HTTPS redirection client-side, without ever touching the network (this also happens to be great for performance; the best request is the one you don't have to make):

$ curl -I https://mkw.st/
HTTP/1.1 200 OK
Server: nginx/1.3.7
...
Strict-Transport-Security: max-age=2592000

Browsers that support this header (currently Firefox, Chrome, and Opera: caniuse has details) will make a note that this particular site has requested HTTPS-only access, meaning that regardless of how a user comes to the site, she'll be visiting over HTTPS. Even if she types http://example.com/ into the browser, she'll end up on HTTPS without ever making an HTTP connection. Better yet, if the browser detects an invalid certificate (potentially trying to spoof your server's identity), users won't be allowed to continue on via HTTP; it's all or nothing, which is excellent.

The browser will expire the server's HSTS status after max-age seconds (about a month in this example); set this to something reasonably high.

You can also ensure that all of an origin's subdomains are protected by adding the includeSubDomains directive to the header:

$ curl -I https://mkw.st/
HTTP/1.1 200 OK
Server: nginx/1.3.7
...
Strict-Transport-Security: max-age=2592000

Go forth, securely #

HTTPS the only way to be even remotely sure that data you send reaches the intended recipient intact. You should set up secure connections for your sites and applications, today. It's a fairly straightforward process, and will help keep your customers' data safe. Once you've gotten an encrypted channel in place, you should transparently redirect users to this secure connection regardless of how they come to your site by sending a 301 HTTP response. Then make sure that that all your users' sensitive session information uses only that secure connection by adding the secure keyword when setting cookies. Once you've done all that, ensure that your users never accidentally fall off the bus: protect them by ensuring that their browser does the right thing by sending a Strict-Transport-Security header.

Setting up HTTPS isn't much work, and has huge benefits for your site and its users. It's well worth the effort.

Resources #

StartSSL offers free domain-verified certificates. You can't beat free. Stepping up to higher grades of verification is, of course, both possible and reasonably priced.
SSL Server Test: Once you've set up HTTPS for your servers, verify that you've done it right by running it through SSL Labs' server test. You'll get a nicely detailed report that shows you whether you're really up and running.
Ars Technica's recent article "Securing your Web Server with SSL/TLS" is worth reading for a little more background detail about the nuts and bolts of setting up a server.
The HTTP Strict Transport Security specification (RFC6797) is worth skimming for all the technical information about the Strict-Transport-Security header you could possibly want.
Once you really know what you're doing, one possible next step would be to advertise that your site should only be reachable via a specific set of certificates. There's some work underway at the IETF which would allow you to do just that via the Public-Key-Pins header; still early days, but interesting, and worth following.

Play safely in sandboxed IFrames

2013-01-04T00:00:00Z

Constructing a rich experience on today's web almost unavoidably involves embedding components and content over which you have no real control. Third-party widgets can drive engagement and play a critical role in the overall user experience, and user-generated content is sometimes even more important than a site's native content. Abstaining from either isn't really an option, but both increase the risk that Something Bad™ could happen on your site. Each widget that you embed -- every ad, every social media widget -- is a potential attack vector for those with malicious intent:

Content Security Policy (CSP) can mitigate the risks associated with both of these types of content by giving you the ability to whitelist specifically trusted sources of script and other content. This is a major step in the right direction, but it's worth noting that the protection that most CSP directives offer is binary: the resource is allowed, or it isn't. There are times when it would be useful to say "I'm not sure I actually trust this source of content, but it's soooo pretty! Embed it please, Browser, but don't let it break my site."

Least Privilege #

In essence, we're looking for a mechanism that will allow us to grant content we embed only the minimum level of capability necessary to do its job. If a widget doesn't need to pop up a new window, taking away access to window.open can't hurt. If it doesn't require Flash, turning off plugin support shouldn't be a problem. We're as secure as we can be if we follow the principle of least privilege, and block each and every feature that isn't directly relevant to functionality we'd like to use. The result is that we no longer have to blindly trust that some piece of embedded content won't take advantage of privileges it shouldn't be using. It simply won't have access to the functionality in the first place.

iframe elements are the first step toward a good framework for such a solution. Loading some untrusted component in an iframe provides a measure of separation between your application and the content you'd like to load. The framed content won't have access to your page's DOM, or data you've stored locally, nor will it be able to draw to arbitrary positions on the page; it's limited in scope to the frame's outline. The separation isn't truly robust, however. The contained page still has a number of options for annoying or malicious behavior: autoplaying video, plugins, and popups are the tip of the iceberg.

The sandbox attribute of the iframe element gives us just what we need to tighten the restrictions on framed content. We can instruct the browser to load a specific frame's content in a low-privilege environment, allowing only the subset of capabilities necessary to do whatever work needs doing.

Twust, but verify #

Twitter's "Tweet" button is a great example of functionality that can be more safely embedded on your site via a sandbox. Twitter allows you to embed the button via an iframe with the following code:

<iframe src="https://platform.twitter.com/widgets/tweet_button.html"
        style="border: 0; width:130px; height:20px;"></iframe>

To figure out what we can lock down, let's carefully examine what capabilities the button requires. The HTML that's loaded into the frame executes a bit of JavaScript from Twitter's servers, and generates a popup populated with a tweeting interface when clicked. That interface needs access to Twitter's cookies in order to tie the tweet to the correct account, and needs the ability to submit the tweeting form. That's pretty much it; the frame doesn't need to load any plugins, it doesn't need to navigate the top-level window, or any of a number of other bits of functionality. Since it doesn't need those privileges, let's remove them by sandboxing the frame's content.

Sandboxing works on the basis of a whitelist. We begin by removing all permissions possible, and then turn individual capabilities back on by adding specific flags to the sandbox's configuration. For the Twitter widget, we've decided to enable JavaScript, popups, form submission, and twitter.com's cookies. We can do so by adding a sandbox attribute to the iframe with the following value:

<iframe sandbox="allow-same-origin allow-scripts allow-popups allow-forms"
    src="https://platform.twitter.com/widgets/tweet_button.html"
    style="border: 0; width:130px; height:20px;"></iframe>

That's it. We've given the frame all the capabilities it requires, and the browser will helpfully deny it access to any of the privileges that we didn't explicitly grant it via the sandbox attribute's value.

Granular Control over Capabilities #

We saw a few of the possible sandboxing flags in the example above, let's now dig through the inner workings of the attribute in a little more detail.

Given an iframe with an empty sandbox attribute, the framed document will be fully sandboxed, subjecting it to the following restrictions:

JavaScript will not execute in the framed document. This not only includes JavaScript explicitly loaded via script tags, but also inline event handlers and javascript: URLs. This also means that content contained in noscript tags will be displayed, exactly as though the user had disabled script herself.
The framed document is loaded into a unique origin, which means that all same-origin checks will fail; unique origins match no other origins ever, not even themselves. Among other impacts, this means that the document has no access to data stored in any origin's cookies or any other storage mechanisms (DOM storage, Indexed DB, etc.).
The framed document cannot create new windows or dialogs (via window.open or target="_blank", for instance).
Forms cannot be submitted.
Plugins will not load.
The framed document can only navigate itself, not its top-level parent. Setting window.top.location will throw an exception, and clicking on link with target="_top" will have no effect.
Features that trigger automatically (autofocused form elements, autoplaying videos, etc.) are blocked.
Pointer lock cannot be obtained.
The seamless attribute is ignored on iframes the framed document contains.

This is nicely draconian, and a document loaded into a fully sandboxed iframe poses very little risk indeed. Of course, it also can't do much of value: you might be able to get away with a full sandbox for some static content, but most of the time you'll want to loosen things up a bit.

With the exception of plugins, each of these restrictions can be lifted by adding a flag to the sandbox attribute's value. Sandboxed documents can never run plugins, as plugins are unsandboxed native code, but everything else is fair game:

allow-forms allows form submission.
allow-popups allows (shock!) popups.
allow-pointer-lock allows (surprise!) pointer lock.
allow-same-origin allows the document to maintain its origin; pages loaded from https://example.com/ will retain access to that origin's data.
allow-scripts allows JavaScript execution, and also allows features to trigger automatically (as they'd be trivial to implement via JavaScript).
allow-top-navigation allows the document to break out of the frame by navigating the top-level window.

With these in mind, we can evaluate exactly why we ended up with the specific set of sandboxing flags in the Twitter example above:

allow-scripts is required, as the page loaded into the frame runs some JavaScript to deal with user interaction.
allow-popups is required, as the button pops up a tweeting form in a new window.
allow-forms is required, as the tweeting form should be submittable.
allow-same-origin is necessary, as twitter.com's cookies would otherwise be inaccessible, and the user couldn't log in to post the form.

One important thing to note is that the sandboxing flags applied to a frame also apply to any windows or frames created in the sandbox. This means that we have to add allow-forms to the frame's sandbox, even though the form only exists in the window that the frame pops up.

With the sandbox attribute in place, the widget gets only the permissions it requires, and capabilities like plugins, top navigation, and pointer lock remain blocked. We've reduced the risk of embedding the widget, with no ill-effects. It's a win for everyone concerned.

Privilege Separation #

Sandboxing third-party content in order to run their untrusted code in a low-privilege environment is fairly obviously beneficial. But what about your own code? You trust yourself, right? So why worry about sandboxing?

I'd turn that question around: if your code doesn't need plugins, why give it access to plugins? At best, it's a privilege you never use, at worst it's a potential vector for attackers to get a foot in the door. Everyone's code has bugs, and practically every application is vulnerable to exploitation in one way or another. Sandboxing your own code means that even if an attacker successfully subverts your application, they won't be given full access to the application's origin; they'll only be able to do things the application could do. Still bad, but not as bad as it could be.

You can reduce the risk even further by breaking your application up into logical pieces and sandboxing each piece with the minimal privilege possible. This technique is very common in native code: Chrome, for example, breaks itself into a high-privilege browser process that has access to the local hard-drive and can make network connections, and many low-privilege renderer processes that do the heavy lifting of parsing untrusted content. Renderers don't need to touch the disk, the browser takes care of giving them all the information they need to render a page. Even if a clever hacker finds a way to corrupt a renderer, she hasn't gotten very far, as the renderer can't do much of interest on its own: all high-privilege access must be routed through the browser's process. Attackers will need to find several holes in different pieces of the system order to do any damage, which hugely reduces the risk of successful pwnage.

Safely sandboxing `eval()` #

With sandboxing and the postMessage API, the success of this model is fairly straightforward to apply to the web. Pieces of your application can live in sandboxed iframes, and the parent document can broker communication between them by posting messages and listening for responses. This sort of structure ensures that exploits in any one piece of the app do the minimum damage possible. It also has the advantage of forcing you to create clear integration points, so you know exactly where you need to be careful about validating input and output. Let's walk through a toy example, just to see how that might work.

Evalbox is an exciting application that takes a string, and evaluates it as JavaScript. Wow, right? Just what you've been waiting for all these long years. It's a fairly dangerous application, of course, as allowing arbitrary JavaScript to execute means that any and all data an origin has to offer is up for grabs. We'll mitigate the risk of Bad Things™ happening by ensuring that the code is executed inside of a sandbox, which makes it quite a bit safer. We'll work our way through the code from the inside out, starting with the frame's contents:

<!-- frame.html -->
<!DOCTYPE html>
<html>
    <head>
    <title>Evalbox's Frame</title>
    <script>
        window.addEventListener('message', function (e) {
        var mainWindow = e.source;
        var result = '';
        try {
            result = eval(e.data);
        } catch (e) {
            result = 'eval() threw an exception.';
        }
        mainWindow.postMessage(result, event.origin);
        });
    </script>
    </head>
</html>

Inside the frame, we have a minimal document that simply listens for messages from its parent by hooking into the message event of the window object. Whenever the parent executes postMessage on the iframe's contents, this event will trigger, giving us access to the string our parent would like us to execute.

In the handler, we grab the source attribute of the event, which is the parent window. We'll use this to send the result of our hard work back up once we're done. Then we'll do the heavy lifting, by passing the data we've been given into eval(). This call has been wrapped up in a try block, as banned operations inside a sandboxed iframe will frequently generate DOM exceptions; we'll catch those and report a friendly error message instead. Finally, we post the result back to the parent window. This is pretty straightforward stuff.

The parent is similarly uncomplicated. We'll create a tiny UI with a textarea for code, and a button for execution, and we'll pull in frame.html via a sandboxed iframe, allowing only script execution:

<textarea id='code'></textarea>
<button id='safe'>eval() in a sandboxed frame.</button>
<iframe sandbox='allow-scripts'
        id='sandboxed'
        src='frame.html'></iframe>

Now we'll wire things up for execution. First, we'll listen for responses from the iframe and alert() them to our users. Presumably a real application would do something less annoying:

window.addEventListener('message',
    function (e) {
        // Sandboxed iframes which lack the 'allow-same-origin'
        // header have "null" rather than a valid origin. This means you still
        // have to be careful about accepting data via the messaging API you
        // create. Check that source, and validate those inputs!
        var frame = document.getElementById('sandboxed');
        if (e.origin === "null" &amp;&amp; e.source === frame.contentWindow)
        alert('Result: ' + e.data);
    });

Next, we'll hook up an event handler to clicks on the button. When the user clicks, we'll grab the current contents of the textarea, and pass them into the frame for execution:

function evaluate() {
    var frame = document.getElementById('sandboxed');
    var code = document.getElementById('code').value;
    // Note that we're sending the message to "*", rather than some specific
    // origin. Sandboxed iframes which lack the 'allow-same-origin' header
    // don't have an origin which you can target: you'll have to send to any
    // origin, which might alow some esoteric attacks. Validate your output!
    frame.contentWindow.postMessage(code, '*');
}

document.getElementById('safe').addEventListener('click', evaluate);

Easy, right? We've created a very simple evaluation API, and we can be sure that code that's evaluated doesn't have access to sensitive information like cookies or DOM storage. Likewise, evaluated code can't load plugins, pop up new windows, or any of a number of other annoying or malicious activities.

You can do the same for your own code by breaking monolithic applications into single-purpose components. Each can be wrapped in a simple messaging API, just like what we've written above. The high-privilege parent window can act as a controller and dispatcher, sending messages into specific modules that each have the fewest privileges possible to do their jobs, listening for results, and ensuring that each module is well-fed with only the information it requires.

Note, however, that you need to be very careful when dealing with framed content that comes from the same origin as the parent. If a page on https://example.com/ frames another page on the same origin with a sandbox that includes both the allow-same-origin and allow-scripts flags, then the framed page can reach up into the parent, and remove the sandbox attribute entirely.

Play in your sandbox #

Sandboxing is available for you now in a variety of browsers: Firefox 17+, IE10+, and Chrome at the time of writing (caniuse, of course, has an up-to-date support table). Applying the sandbox attribute to iframes you include allows you to grant certain privileges to the content they display, only those privileges which are necessary for the content to function correctly. This gives you the opportunity to reduce the risk associated with the inclusion of third-party content, above and beyond what is already possible with Content Security Policy.

Moreover, sandboxing is a powerful technique for reducing the risk that a clever attacker will be able to exploit holes in your own code. By separating a monolithic application into a set of sandboxed services, each responsible for a small chunk of self-contained functionality, attackers will be forced to not only compromise specific frames' content, but also their controller. That's a much more difficult task, especially since the controller can be greatly reduced in scope. You can spend your security-related effort auditing that code if you ask the browser for help with the rest.

That's not to say that sandboxing is a complete solution to the problem of security on the internet. It offers defense in depth, and unless you have control over your users' clients, you can't yet rely on browser support for all your users (if you do control your users clients -- an enterprise environment, for example -- hooray!). Someday… but for now sandboxing is another layer of protection to strengthen your defenses, it's not a complete defense upon which you can soley rely. Still, layers are excellent. I suggest making use of this one.

Content security policy

2012-06-15T00:00:00Z

The web's security model is rooted in the same-origin policy. Code from https://mybank.com should only have access to https://mybank.com's data, and https://evil.example.com should certainly never be allowed access. Each origin is kept isolated from the rest of the web, giving developers a safe sandbox in which to build and play. In theory, this is perfectly brilliant. In practice, attackers have found clever ways to subvert the system.

Cross-site scripting (XSS) attacks, for example, bypass the same origin policy by tricking a site into delivering malicious code along with the intended content. This is a huge problem, as browsers trust all of the code that shows up on a page as being legitimately part of that page's security origin. The XSS Cheat Sheet is an old but representative cross-section of the methods an attacker might use to violate this trust by injecting malicious code. If an attacker successfully injects any code at all, it's pretty much game over: user session data is compromised and information that should be kept secret is exfiltrated to The Bad Guys. We'd obviously like to prevent that if possible.

This overview highlights a defense that can significantly reduce the risk and impact of XSS attacks in modern browsers: Content Security Policy (CSP).

Summary #

Use allowlists to tell the client what's allowed and what isn't.
Learn what directives are available.
Learn the keywords they take.
Inline code and eval() are considered harmful.
Report policy violations to your server before enforcing them.

Source allowlists #

The issue exploited by XSS attacks is the browser's inability to distinguish between script that's part of your application and script that's been maliciously injected by a third-party. For example, the Google +1 button at the bottom of this page loads and executes code from https://apis.google.com/js/plusone.js in the context of this page's origin. We trust that code, but we can't expect the browser to figure out on its own that code from apis.google.com is awesome, while code from apis.evil.example.com probably isn't. The browser happily downloads and executes any code a page requests, regardless of source.

Instead of blindly trusting everything that a server delivers, CSP defines the Content-Security-Policy HTTP header, which allows you to create an allowlist of sources of trusted content, and instructs the browser to only execute or render resources from those sources. Even if an attacker can find a hole through which to inject script, the script won't match the allowlist, and therefore won't be executed.

Since we trust apis.google.com to deliver valid code, and we trust ourselves to do the same, let's define a policy that only allows script to execute when it comes from one of those two sources:

Content-Security-Policy: script-src 'self' https://apis.google.com

Simple, right? As you probably guessed, script-src is a directive that controls a set of script-related privileges for a specific page. We've specified 'self' as one valid source of script, and https://apis.google.com as another. The browser dutifully downloads and executes JavaScript from apis.google.com over HTTPS, as well as from the current page's origin.

With this policy defined, the browser simply throws an error instead of loading script from any other source. When a clever attacker manages to inject code into your site, they'll run headlong into an error message rather than the success they were expecting.

Policy applies to a wide variety of resources #

While script resources are the most obvious security risks, CSP provides a rich set of policy directives that enable fairly granular control over the resources that a page is allowed to load. You've already seen script-src, so the concept should be clear.

Let's quickly walk through the rest of the resource directives. The list below represents the state of the directives as of level 2. A level 3 spec has been published, but is largely unimplemented in the major browsers.

base-uri restricts the URLs that can appear in a page's <base> element.
child-src lists the URLs for workers and embedded frame contents. For example: child-src https://youtube.com would enable embedding videos from YouTube but not from other origins.
connect-src limits the origins that you can connect to (via XHR, WebSockets, and EventSource).
font-src specifies the origins that can serve web fonts. Google's web fonts could be enabled via font-src https://themes.googleusercontent.com.
form-action lists valid endpoints for submission from <form> tags.
frame-ancestors specifies the sources that can embed the current page. This directive applies to <frame>, <iframe>, <embed>, and <applet> tags. This directive can't be used in <meta> tags and applies only to non-HTML resources.
frame-src was deprecated in level 2, but is restored in level 3. If not present it still falls back to child-src as before.
img-src defines the origins from which images can be loaded.
media-src restricts the origins allowed to deliver video and audio.
object-src allows control over Flash and other plugins.
plugin-types limits the kinds of plugins a page may invoke.
report-uri specifies a URL where a browser will send reports when a content security policy is violated. This directive can't be used in <meta> tags.
style-src is script-src's counterpart for stylesheets.
upgrade-insecure-requests instructs user agents to rewrite URL schemes, changing HTTP to HTTPS. This directive is for websites with large numbers of old URL's that need to be rewritten.
worker-src is a CSP Level 3 directive that restricts the URLs that may be loaded as a worker, shared worker, or service worker. As of July 2017, this directive has limited implementations.

By default, directives are wide open. If you don't set a specific policy for a directive, let's say font-src, then that directive behaves by default as though you'd specified * as the valid source (for example, you could load fonts from anywhere, without restriction).

You can override this default behavior by specifying a default-src directive. This directive defines the defaults for most directives that you leave unspecified. Generally, this applies to any directive that ends with -src. If default-src is set to https://example.com, and you fail to specify a font-src directive, then you can load fonts from https://example.com, and nowhere else. We specified only script-src in our earlier examples, which means that images, fonts, and so on can be loaded from any origin.

The following directives don't use default-src as a fallback. Remember that failing to set them is the same as allowing anything.

base-uri
form-action
frame-ancestors
plugin-types
report-uri
sandbox

You can use as many or as few of these directives as makes sense for your specific application, simply listing each in the HTTP header, separating directives with semicolons. Make sure that you list all required resources of a specific type in a single directive. If you wrote something like script-src https://host1.com; script-src https://host2.com the second directive would simply be ignored. Something like the following would correctly specify both origins as valid:

script-src https://host1.com https://host2.com

If, for example, you have an application that loads all of its resources from a content delivery network (say, https://cdn.example.net), and know that you don't need any framed content or plugins, then your policy might look something like the following:

Content-Security-Policy: default-src https://cdn.example.net; child-src 'none'; object-src 'none'

Implementation details #

You will see X-WebKit-CSP and X-Content-Security-Policy headers in various tutorials on the web. Going forward, you should ignore these prefixed headers. Modern browsers (with the exception of IE) support the unprefixed Content-Security-Policy header. That's the header you should use.

Regardless of the header you use, policy is defined on a page-by-page basis: you'll need to send the HTTP header along with every response that you'd like to ensure is protected. This provides a lot of flexibility, as you can fine-tune the policy for specific pages based on their specific needs. Perhaps one set of pages in your site has a +1 button, while others don't: you could allow the button code to be loaded only when necessary.

The source list in each directive is flexible. You can specify sources by scheme (data:, https:), or ranging in specificity from hostname-only (example.com, which matches any origin on that host: any scheme, any port) to a fully qualified URI (https://example.com:443, which matches only HTTPS, only example.com, and only port 443). Wildcards are accepted, but only as a scheme, a port, or in the leftmost position of the hostname: *://*.example.com:* would match all subdomains of example.com (but not example.com itself), using any scheme, on any port.

The source list also accepts four keywords:

'none', as you might expect, matches nothing.
'self' matches the current origin, but not its subdomains.
'unsafe-inline' allows inline JavaScript and CSS. (We'll touch on this in more detail in a bit.)
'unsafe-eval' allows text-to-JavaScript mechanisms like eval. (We'll get to this too.)

These keywords require single-quotes. For example, script-src 'self' (with quotes) authorizes the execution of JavaScript from the current host; script-src self (no quotes) allows JavaScript from a server named "self" (and not from the current host), which probably isn't what you meant.

Sandboxing #

There's one more directive worth talking about: sandbox. It's a bit different from the others we've looked at, as it places restrictions on actions that the page can take rather than on resources that the page can load. If the sandbox directive is present, the page is treated as though it was loaded inside of an <iframe> with a sandbox attribute. This can have a wide range of effects on the page: forcing the page into a unique origin, and preventing form submission, among others. It's a bit beyond the scope of this article, but you can find full details on valid sandboxing attributes in the "Sandboxing" section of the HTML5 spec.

The meta tag #

CSPs preferred delivery mechanism is an HTTP header. It can be useful, however, to set a policy on a page directly in the markup. Do that using a <meta> tag with an http-equiv attribute:

<meta http-equiv="Content-Security-Policy" content="default-src https://cdn.example.net; child-src 'none'; object-src 'none'">

This can't be used for frame-ancestors, report-uri, or sandbox.

Inline code is considered harmful #

It should be clear that CSP is based on allowlist origins, as that's an unambiguous way of instructing the browser to treat specific sets of resources as acceptable and to reject the rest. Origin-based allowlists don't, however, solve the biggest threat posed by XSS attacks: inline script injection. If an attacker can inject a script tag that directly contains some malicious payload (<script>sendMyDataToEvilDotCom()</script>), the browser has no mechanism by which to distinguish it from a legitimate inline script tag. CSP solves this problem by banning inline script entirely: it's the only way to be sure.

This ban includes not only scripts embedded directly in script tags, but also inline event handlers and javascript: URLs. You'll need to move the content of script tags into an external file, and replace javascript: URLs and <a ... onclick="[JAVASCRIPT]"> with appropriate addEventListener() calls. For example, you might rewrite the following from:

<script>
    function doAmazingThings() {
    alert('YOU AM AMAZING!');
    }
</script>
<button onclick='doAmazingThings();'>Am I amazing?</button>

to something more like:

<!-- amazing.html -->
<script src='amazing.js'></script>
<button id='amazing'>Am I amazing?</button>

// amazing.js
function doAmazingThings() {
    alert('YOU AM AMAZING!');
}
document.addEventListener('DOMContentLoaded', function () {
    document.getElementById('amazing')
    .addEventListener('click', doAmazingThings);
});

The rewritten code has a number of advantages above and beyond working well with CSP; it's already best practice, regardless of your use of CSP. Inline JavaScript mixes structure and behavior in exactly the way you shouldn't. External resources are easier for browsers to cache, more understandable for developers, and conducive to compilation and minification. You'll write better code if you do the work to move code into external resources.

Inline style is treated in the same way: both the style attribute and style tags should be consolidated into external stylesheets to protect against a variety of surprisingly clever data exfiltration methods that CSS enables.

If you must have inline script and style, you can enable it by adding 'unsafe-inline' as an allowed source in a script-src or style-src directive. You can also use a nonce or a hash (see below), but you really shouldn't. Banning inline script is the biggest security win CSP provides, and banning inline style likewise hardens your application. It's a little bit of effort up front to ensure that things work correctly after moving all the code out-of-line, but that's a tradeoff that's well worth making.

If you absolutely must use it #

CSP Level 2 offers backward compatibility for inline scripts by allowing you to add specific inline scripts to the allowlist using either a cryptographic nonce (number used once) or a hash. Although this may be cumbersome, it is useful in a pinch.

To use a nonce, give your script tag a nonce attribute. Its value must match one in the list of trusted sources. For example:

<script nonce="EDNnf03nceIOfn39fn3e9h3sdfa">
    // Some inline code I can't remove yet, but need to asap.
</script>

Now, add the nonce to your script-src directive appended to the nonce- keyword.

Content-Security-Policy: script-src 'nonce-EDNnf03nceIOfn39fn3e9h3sdfa'

Remember that nonces must be regenerated for every page request and they must be unguessable.

Hashes work in much the same way. Instead of adding code to the script tag, create a SHA hash of the script itself and add it to the script-src directive. For example, let's say your page contained this:

<script>alert('Hello, world.');</script>

Your policy would contain this:

Content-Security-Policy: script-src 'sha256-qznLcsROx4GACP2dm0UCKCzCG-HiZ1guq6ZZDob_Tng='

There are a few things to note here. The sha*- prefix specifies the algorithm that generates the hash. In the example above, sha256- is used. CSP also supports sha384- and sha512-. When generating the hash, do not include the <script> tags. Also capitalization and whitespace matter, including leading or trailing whitespace.

A Google search on generating SHA hashes will lead you to solutions in any number of languages. Using Chrome 40 or later, you can open DevTools and then reload your page. The Console tab will contain error messages with the correct sha256 hash for each of your inline scripts.

Eval too #

Even when an attacker can't inject script directly, they might be able to trick your application into converting otherwise inert text into executable JavaScript and executing it on their behalf. eval(), new Function(), setTimeout([string], …), and setInterval([string], ...) are all vectors through which injected text might end up executing something unexpectedly malicious. CSP's default response to this risk is to completely block all of these vectors.

This has more than a few impacts on the way you build applications:

You must parse JSON via the built-in JSON.parse, rather than relying on eval. Native JSON operations are available in every browser since IE8, and they're completely safe.
Rewrite any setTimeout or setInterval calls you're currently making with inline functions rather than strings. For example:

setTimeout("document.querySelector('a').style.display = 'none';", 10);

would be better written as:

setTimeout(function () {
    document.querySelector('a').style.display = 'none';
}, 10);

Avoid inline templating at runtime: Many templating libraries use new Function() liberally to speed up template generation at runtime. It's a nifty application of dynamic programming, but comes at the risk of evaluating malicious text. Some frameworks support CSP out of the box, falling back to a robust parser in the absence of eval. AngularJS's ng-csp directive is a good example of this.

However, a better choice would be a templating language that offers precompilation (Handlebars does, for instance). Precompiling your templates can make the user experience even faster than the fastest runtime implementation, and it's safer too. If eval and its text-to-JavaScript brethren are essential to your application, you can enable them by adding 'unsafe-eval' as an allowed source in a script-src directive, but we strongly discourage this. Banning the ability to execute strings makes it much more difficult for an attacker to execute unauthorized code on your site.

Reporting #

CSP's ability to block untrusted resources client-side is a huge win for your users, but it would be quite helpful to have some sort of notification sent back to the server so that you can identify and squash any bugs that allow malicious injection in the first place. To this end, you can instruct the browser to POST JSON-formatted violation reports to a location specified in a report-uri directive.

Content-Security-Policy: default-src 'self'; ...; report-uri /my_amazing_csp_report_parser;

Those reports will look something like the following:

{
    "csp-report": {
    "document-uri": "http://example.org/page.html",
    "referrer": "http://evil.example.com/",
    "blocked-uri": "http://evil.example.com/evil.js",
    "violated-directive": "script-src 'self' https://apis.google.com",
    "original-policy": "script-src 'self' https://apis.google.com; report-uri http://example.org/my_amazing_csp_report_parser"
    }
}

This contains a good chunk of information that will help you track down the specific cause of the violation, including the page on which the violation occurred (document-uri), that page's referrer (note that unlike the HTTP header field, the key is not misspelled), the resource that violated the page's policy (blocked-uri), the specific directive it violated (violated-directive), and the page's complete policy (original-policy).

Report-Only #

If you're just starting out with CSP, it makes sense to evaluate the current state of your application before rolling out a draconian policy to your users. As a stepping stone to a complete deployment, you can ask the browser to monitor a policy, reporting violations but not enforcing the restrictions. Instead of sending a Content-Security-Policy header, send a Content-Security-Policy-Report-Only header.

Content-Security-Policy-Report-Only: default-src 'self'; ...; report-uri /my_amazing_csp_report_parser;

The policy specified in report-only mode won't block restricted resources, but it will send violation reports to the location you specify. You can even send both headers, enforcing one policy while monitoring another. This is a great way to evaluate the effect of changes to your application's CSP: turn on reporting for a new policy, monitor the violation reports and fix any bugs that turn up; when you're satisfied with its effect, start enforcing the new policy.

Real World Usage #

CSP 1 is quite usable in Chrome, Safari, and Firefox, but has very limited support in IE 10. You can view specifics at caniuse.com. CSP Level 2 has been available in Chrome since version 40. Massive sites like Twitter and Facebook have deployed the header (Twitter's case study is worth a read), and the standard is very much ready for you to start deploying on your own sites.

The first step towards crafting a policy for your application is to evaluate the resources you're actually loading. Once you think you have a handle on how things are put together in your app, set up a policy based on those requirements. Let's walk through a few common use cases and determine how we'd best be able to support them within the protective confines of CSP.

Facebook's Like button has a number of implementation options. We recommend sticking with the <iframe> version as it's safely sandboxed from the rest of your site. It requires a child-src https://facebook.com directive to function properly. Note that, by default, the <iframe> code that Facebook provides loads a relative URL, //facebook.com. Change that to explicitly specify HTTPS: https://facebook.com. There's no reason to use HTTP if you don't have to.
Twitter's Tweet button relies on access to a script and a frame, both hosted at https://platform.twitter.com. (Twitter likewise provides a relative URL by default; edit the code to specify HTTPS when copy/pasting it locally.) You'll be all set with script-src https://platform.twitter.com; child-src https://platform.twitter.com, as long as you move the JavaScript snippet that Twitter provides out into an external JavaScript file.
Other platforms have similar requirements, and can be addressed similarly. We suggest just setting a default-src of 'none', and watching your console to determine which resources you'll need to enable to make the widgets work.

Including multiple widgets is straightforward: simply combine the policy directives, remembering to merge all resources of a single type into a single directive. If you wanted all three social media widgets, the policy would look like this:

script-src https://apis.google.com https://platform.twitter.com; child-src https://plusone.google.com https://facebook.com https://platform.twitter.com

Use case #2: lockdown #

Assume for a moment that you run a banking site and want to make sure that only those resources you've written yourself can be loaded. In this scenario, start with a default policy that blocks absolutely everything (default-src 'none'), and build up from there.

Let's say the bank loads all images, style, and script from a CDN at https://cdn.mybank.net, and connects via XHR to https://api.mybank.com/ to pull various bits of data down. Frames are used, but only for pages local to the site (no third-party origins). There's no Flash on the site, no fonts, no extras. The most restrictive CSP header that we could send is this:

Content-Security-Policy: default-src 'none'; script-src https://cdn.mybank.net; style-src https://cdn.mybank.net; img-src https://cdn.mybank.net; connect-src https://api.mybank.com; child-src 'self'

Use case #3: SSL only #

A wedding-ring discussion forum admin wants to ensure that all resources are only loaded via secure channels, but doesn't really write much code; rewriting large chunks of the third-party forum software that's filled to the brim with inline script and style is beyond his abilities. The following policy would be effective:

Content-Security-Policy: default-src https:; script-src https: 'unsafe-inline'; style-src https: 'unsafe-inline'

Even though https: is specified in default-src, the script and style directives don't automatically inherit that source. Each directive completely overwrites the default for that specific type of resource.

The future #

Content Security Policy Level 2 is a Candidate Recommendation. The W3C's Web Application Security Working Group has already begun work on the specification's next iteration, Content Security Policy Level 3.

If you're interested in the discussion around these upcoming features, skim the public-webappsec@ mailing list archives, or join in yourself.