Skip to content

GitLab

T
tangled
Commit d0fb4db3 authored by mkwst@chromium.org's avatar mkwst@chromium.org
Browse files
Options

Describing the `sandbox` workflow for extension developers. 

BUG=117154
TEST=Just docs, no tests.

Review URL: https://chromiumcodereview.appspot.com/10810054

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@148728 0039d316-1c4b-4281-b951-d872f2087c98
parent 2385272b
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2739 additions and 0 deletions
chrome/common/extensions/docs/apps/sandboxingEval.html 0 → 100644
View file @ d0fb4db3
This diff is collapsed.
chrome/common/extensions/docs/examples/howto/sandbox/LICENSE.handlebars 0 → 100644
View file @ d0fb4db3
Copyright (C) 2011 by Yehuda Katz
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
chrome/common/extensions/docs/examples/howto/sandbox/eventpage.html 0 → 100644
View file @ d0fb4db3
<!--
- Copyright (c) 2012 The Chromium Authors. All rights reserved.
- Use of this source code is governed by a BSD-style license that can be
- found in the LICENSE file.
-->
<!doctype html>
<html>
<head>
<script src="eventpage.js"></script>
</head>
<body>
<iframe id="theFrame" src="sandbox.html"></iframe>
</body>
</html>
chrome/common/extensions/docs/examples/howto/sandbox/eventpage.js 0 → 100644
View file @ d0fb4db3
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
chrome.browserAction.onClicked.addListener(function() {
var iframe = document.getElementById('theFrame');
var message = {
command: 'render',
context: {thing: 'world'}
};
iframe.contentWindow.postMessage(message, '*');
});
window.addEventListener('message', function(event) {
if (event.data.html) {
var notification = webkitNotifications.createNotification(
'icon.png',
'Templated!',
'HTML Received for "' + event.data.name + '": `' + event.data.html + '`'
);
notification.show();
}
});
chrome/common/extensions/docs/examples/howto/sandbox/manifest.json 0 → 100644
View file @ d0fb4db3
{
"name": "Sandboxed Frame",
"version": "1.0",
"manifest_version": 2,
"permissions": ["notifications"],
"background": {
"page": "eventpage.html",
"persistent": false
},
"browser_action": {
"default_icon" : "icon.png",
"default_title": "Start Event Page"
},
"sandbox": {
"pages": ["sandbox.html"]
},
"web_accessible_resources": ["icon.png"]
}
chrome/common/extensions/docs/examples/howto/sandbox/sandbox.html 0 → 100644
View file @ d0fb4db3
<!--
- Copyright (c) 2012 The Chromium Authors. All rights reserved.
- Use of this source code is governed by a BSD-style license that can be
- found in the LICENSE file.
-->
<!doctype html>
<html>
<head>
<script src="handlebars-1.0.0.beta.6.js"></script>
</head>
<body>
<script id="hello-world-template" type="text/x-handlebars-template">
<div class="entry">
<h1>Hello, {{thing}}!</h1>
</div>
</script>
<script>
var templates = [];
var source = document.getElementById('hello-world-template').innerHTML;
templates['hello'] = Handlebars.compile(source);
// Set up message event handler:
window.addEventListener('message', function(event) {
var command = event.data.command;
var name = event.data.name || 'hello';
switch(command) {
case 'render':
event.source.postMessage({
name: name,
html: templates[name](event.data.context)
}, event.origin);
break;
// You could imagine additional functionality. For instance:
//
// case 'new':
// templates[event.data.name] = Handlebars.compile(event.data.source);
// event.source.postMessage({name: name, success: true}, event.origin);
// break;
}
});
</script>
</body>
</html>
chrome/common/extensions/docs/extensions/sandboxingEval.html 0 → 100644
View file @ d0fb4db3
This diff is collapsed.
chrome/common/extensions/docs/samples.json
View file @ d0fb4db3
...@@ -2327,6 +2327,34 @@ ...@@ -2327,6 +2327,34 @@
"source_hash": "194d8d5d6ec2ef0e06d8ed8134fcaf174dc7e811", "source_hash": "194d8d5d6ec2ef0e06d8ed8134fcaf174dc7e811",
"zip_path": "examples/extensions/oauth_contacts.zip" "zip_path": "examples/extensions/oauth_contacts.zip"
}, },
{
"api_calls": [
"chrome.browserAction.onClicked"
],
"crx_path": null,
"description": "",
"features": [
"background_page",
"browser_action",
"notifications"
],
"icon": null,
"id": "3c6dfba67f6a7480d931b5a4a646c151ad1a049b",
"name": "Sandboxed Frame",
"packaged_app": false,
"path": "examples/howto/sandbox/",
"protocols": [],
"search_string": "SANDBOXED FRAME BACKGROUND_PAGE BROWSER_ACTION NOTIFICATIONS CHROME.BROWSERACTION.ONCLICKED",
"source_files": [
"eventpage.html",
"eventpage.js",
"handlebars-1.0.0.beta.6.js",
"manifest.json",
"sandbox.html"
],
"source_hash": "5e3132df5468ab2cbec3f21fced28b492bc26ca9",
"zip_path": "examples/howto/sandbox.zip"
},
{ {
"api_calls": [ "api_calls": [
"chrome.experimental.infobars.show" "chrome.experimental.infobars.show"
......
chrome/common/extensions/docs/static/sandboxingEval.html 0 → 100644
View file @ d0fb4db3
<div id="pageData-name" class="pageData">Using eval in Chrome Extensions. Safely.</div>
<div id="pageData-showTOC" class="pageData">true</div>
<p>
Chrome's extension system enforces a fairly strict default
<a href='contentSecurityPolicy.html'>
<strong>Content Security Policy (CSP)</strong>
</a>. The policy restrictions are straightforward: script must be moved
out-of-line into separate JavaScript files, inline event handlers must be
converted to use <code>addEventListener</code>, and <code>eval()</code> is
disabled. Chrome Apps have an
<a href='http://developer.chrome.com/trunk/apps/app_csp.html'>even more strict
policy</a>, and we're quite happy with the security properties these policies
provide.
</p>
<p>
We recognize, however, that a variety of libraries use <code>eval()</code> and
<code>eval</code>-like constructs such as <code>new Function()</code> for
performance optimization and ease of expression. Templating libraries are
especially prone to this style of implementation. While some (like
<a href='http://angularjs.org/'>Angular.js</a>) support CSP out of the box,
many popular frameworks haven't yet updated to a mechanism that is compatible
with extensions' <code>eval</code>-less world. Removing support for that
functionality has therefore proven <a href='http://crbug.com/107538'>more
problematic than expected</a> for developers.
</p>
<p>
This document introduces sandboxing as a safe mechanism to include these
libraries in your projects without compromising on security. For brevity,
we'll be using the term <em>extensions</em> throughout, but the concept
applies equally to applications.
</p>
<h2>Why sandbox?</h2>
<p>
<code>eval</code> is dangerous inside an extension because the code it
executes has access to everything in the extension's high-permission
environment. A slew of powerful <code>chrome.*</code> APIs are available that
could severely impact a user's security and privacy; simple data exfiltration
is the least of our worries. The solution on offer is a sandbox in which
<code>eval</code> can execute code without access either to the extension's
data or the extension's high-value APIs. No data, no APIs, no problem.
</p>
<p>
We accomplish this by listing specific HTML files inside the extension package
as being sandboxed. Whenever a sandboxed page is loaded, it will be moved to a
<a href='http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#sandboxed-origin-browsing-context-flag'>unique origin</a>,
and will be denied access to <code>chrome.*</code> APIs. If we load this
sandboxed page into our extension via an <code>iframe</code>, we can pass it
messages, let it act upon those messages in some way, and wait for it to pass
us back a result. This simple messaging mechanism gives us everything we need
to safely include <code>eval</code>-driven code in our extension's workflow.
</p>
<h2>Creating and using a sandbox.</h2>
<p>
If you'd like to dive straight into code, please grab the
<a href='http://code.google.com/chrome/extensions/samples.html#3c6dfba67f6a7480d931b5a4a646c151ad1a049b'>sandboxing
sample extension and take off</a>. It's a working example of a tiny messaging
API built on top of the <a href='http://handlebarsjs.com'>Handlebars</a>
templating library, and it should give you everything you need to get going.
For those of you who'd like a little more explanation, let's walk through that
sample together here.
</p>
<h3>List files in manifest</h3>
<p>
Each file that ought to be run inside a sandbox must be listed in the
extension manifest by adding a <code>sandbox</code> property. This is a
critical step, and it's easy to forget, so please double check that your
sandboxed file is listed in the manifest. In this sample, we're sandboxing the
file cleverly named "sandbox.html". The manifest entry looks like this:
</p>
<pre>{
...,
"sandbox": {
"pages": ["sandbox.html"]
},
...
}</pre>
<h3>Load the sandboxed file</h3>
<p>
In order to do something interesting with the sandboxed file, we need to load
it in a context where it can be addressed by the extension's code. Here,
<a href='http://code.google.com/chrome/extensions/examples/howto/sandbox/sandbox.html'>sandbox.html</a>
has been loaded into the extension's <a href='http://code.google.com/chrome/extensions/dev/event_pages.html'>Event
Page</a> (<a href='http://code.google.com/chrome/extensions/examples/howto/sandbox/eventpage.html'>eventpage.html</a>)
via an <code>iframe</code>. <a href='http://code.google.com/chrome/extensions/examples/howto/sandbox/eventpage.js'>eventpage.js</a>
contains code that sends a message into the sandbox whenever the browser
action is clicked by finding the <code>iframe</code> on the page, and
executing the <code>postMessage</code> method on its
<code>contentWindow</code>. The message is an object containing two
properties: <code>context</code> and <code>command</code>. We'll dive into
both in a moment.
</p>
<pre>chrome.browserAction.onClicked.addListener(function() {
var iframe = document.getElementById('theFrame');
var message = {
command: 'render',
context: {thing: 'world'}
};
iframe.contentWindow.postMessage(message, '*');
});</pre>
<p class="note">
For general information about the <code>postMessage</code> API, take a look at
the <a href="https://developer.mozilla.org/en/DOM/window.postMessage">
<code>postMessage</code> documentation on MDN
</a>. It's quite complete and worth reading. In particular, note that data can
only be passed back and forth if it's serializable. Functions, for instance,
are not.
</p>
<h3>Do something dangerous</h3>
<p>
When <code>sandbox.html</code> is loaded, it loads the Handlebars library, and
creates and compiles an inline template in the way Handlebars suggests:
</p>
<pre>&lt;script src="handlebars-1.0.0.beta.6.js"&gt;&lt;/script&gt;
&lt;script id="hello-world-template" type="text/x-handlebars-template"&gt;
&lt;div class="entry"&gt;
&lt;h1&gt;Hello, {{thing}}!&lt;/h1&gt;
&lt;/div&gt;
&lt;/script&gt;
&lt;script&gt;
var templates = [];
var source = document.getElementById('hello-world-template').innerHTML;
templates['hello'] = Handlebars.compile(source);
&lt;/script&gt;</pre>
<p>
This doesn't fail! Even though <code>Handlebars.compile</code> ends up using
<code>new Function</code>, things work exactly as expected, and we end up with
a compiled template in <code>templates[‘hello']</code>.
</p>
<h3>Pass the result back</h3>
<p>
We'll make this template available for use by setting up a message listener
that accepts commands from the Event Page. We'll use the <code>command</code>
passed in to determine what ought to be done (you could imagine doing more
than simply rendering; perhaps creating templates? Perhaps managing them in
some way?), and the <code>context</code> will be passed into the template
directly for rendering. The rendered HTML will be passed back to the Event
Page so the extension can do something useful with it later on:
</p>
<pre>window.addEventListener('message', function(event) {
var command = event.data.command;
var name = event.data.name || 'hello';
switch(command) {
case 'render':
event.source.postMessage({
name: name,
html: templates[name](event.data.context)
}, event.origin);
break;
// case 'somethingElse':
// ...
}
});</pre>
<p>
Back in the Event Page, we'll receive this message, and do something
interesting with the <code>html</code> data we've been passed. In this case,
we'll just echo it out via a <a href='http://code.google.com/chrome/extensions/notifications.html'>Desktop
Notification</a>, but it's entirely possible to use this HTML safely as part
of the extension's UI. Inserting it via <code>innerHTML</code> doesn't pose a
significant security risk, as even a complete compromise of the sandboxed code
through some clever attack would be unable to inject dangerous script or
plugin content into the high-permission extension context.
</p>
<p>
This mechanism makes templating straightforward, but it of course isn't
limited to templating. Any code that doesn't work out of the box under a
strict Content Security Policy can be sandboxed; in fact, it's often useful
to sandbox components of your extensions that <em>would</em> run correctly in
order to restrict each piece of your program to the smallest set of privileges
necessary for it to properly execute. The
<a href="http://www.youtube.com/watch?v=GBxv8SaX0gg">Writing Secure Web Apps
and Chrome Extensions</a> presentation from Google I/O 2012 gives some good
examples of these technique in action, and is worth 56 minutes of your time.
</p>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment