Improving `content_security_policy` documentation.

Improving `content_security_policy` documentation.

Added a document just for `content_security_policy` explaining the default
restrictions, and offering pointers regarding best practice. Also updated
the Analytics example and documentation accordingly.

BUG=111049
TEST=

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=119211

[Mike West, 2012-01-24 12:22:55]

Hi Adam, Meggin, and Ernest!

I've made a bunch of changes to the CSP documentation, and fiddled around with
the analytics extension to match. The CSP doc is a strawman... I'm not actually
sure what we want to say about it, but this is a first pass just to give us
something to talk about (and to land _this week_. :) ).

Updated docs staged at
http://www.corp.google.com/~mkwst/no_crawl/docs/contentSecurityPolicy.html and
http://www.corp.google.com/~mkwst/no_crawl/docs/tut_analytics.html and
http://www.corp.google.com/~mkwst/no_crawl/docs/manifest.html

Thanks!

[abarth-chromium, 2012-01-24 16:42:36]

Technical content LGTM

http://codereview.chromium.org/9212044/diff/1/chrome/common/extensions/docs/c...
File chrome/common/extensions/docs/contentSecurityPolicy.html (right):

http://codereview.chromium.org/9212044/diff/1/chrome/common/extensions/docs/c...
chrome/common/extensions/docs/contentSecurityPolicy.html:308: <a
href="#H3-1">Inline JavaScript will not be executed</a>
Also, eval is banned.

http://codereview.chromium.org/9212044/diff/1/chrome/common/extensions/docs/c...
chrome/common/extensions/docs/contentSecurityPolicy.html:529: effect. This is
intentional.
Maybe explain why allowing HTTP scripts would be problematic (man-in-the-middle
attacks)?

[Mike West, 2012-01-25 16:08:29]

Incorporated Adam's feedback, and restaged
http://www.corp.google.com/~mkwst/no_crawl/docs/contentSecurityPolicy.html

Thanks!

http://codereview.chromium.org/9212044/diff/1/chrome/common/extensions/docs/c...
File chrome/common/extensions/docs/contentSecurityPolicy.html (right):

http://codereview.chromium.org/9212044/diff/1/chrome/common/extensions/docs/c...
chrome/common/extensions/docs/contentSecurityPolicy.html:308: <a
href="#H3-1">Inline JavaScript will not be executed</a>
On 2012/01/24 16:42:36, abarth wrote:
> Also, eval is banned.

I note that down in the body. This line is just the autogenerated table of
contents up in the top-right. Perhaps we don't need a table of contents, though?
The doc is pretty short.

What do you think, Meggin?

http://codereview.chromium.org/9212044/diff/1/chrome/common/extensions/docs/c...
chrome/common/extensions/docs/contentSecurityPolicy.html:529: effect. This is
intentional.
On 2012/01/24 16:42:36, abarth wrote:
> Maybe explain why allowing HTTP scripts would be problematic
(man-in-the-middle
> attacks)?

Good idea. I've added a sentence or two, and linked off to everyone's best
friend: Wikipedia.

[mkearney, 2012-01-25 22:39:22]

I like this doc - the before and after code samples are very cool.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
File chrome/common/extensions/docs/static/contentSecurityPolicy.html (right):

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:6: content that
can be loaded and executed by your extension. In order to
Is there any value in defining CSP in the larger, global content, similar to how
it is defined in the specification? This seems to imply that CSP is specifically
for extensions.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:15: or execute
by your extensions. Defining a reasonable policy for your extension
Change 'execute' to be 'executed'.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:38: <a
href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html">
What about linking directly to the syntax (#syntax)?

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:147: //
`DOMContentLoaded` event on the docuent, and adding your listeners to
'docuent' should be 'document'.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:237:
<code>https://example.com/</code> might look like:
This is coming up as a link, and when you click it, the link is broken. Maybe
try [verbatim]...[endverbatim] around the <code> tags. I haven't tried this in
chromium, mind you, so not too sure if this is the right solution.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:264: allows in
order to increase security at the expense of convinience. To specify
Spelling - 'convinience' should be 'convenience'.

[Mike West, 2012-01-25 23:34:36]

Thanks Meggin! Revisions attached and staged (same URL:
http://www/~mkwst/no_crawl/docs/contentSecurityPolicy.html )

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
File chrome/common/extensions/docs/static/contentSecurityPolicy.html (right):

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:6: content that
can be loaded and executed by your extension. In order to
Rephrased.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:15: or execute
by your extensions. Defining a reasonable policy for your extension
On 2012/01/25 22:39:22, mkearney wrote:
> Change 'execute' to be 'executed'.

Done.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:38: <a
href="http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html">
On 2012/01/25 22:39:22, mkearney wrote:
> What about linking directly to the syntax (#syntax)?

Done.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:147: //
`DOMContentLoaded` event on the docuent, and adding your listeners to
On 2012/01/25 22:39:22, mkearney wrote:
> 'docuent' should be 'document'.

Done.

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:237:
<code>https://example.com/</code> might look like:
On 2012/01/25 22:39:22, mkearney wrote:
> This is coming up as a link, and when you click it, the link is broken. Maybe
> try [verbatim]...[endverbatim] around the <code> tags. I haven't tried this in
> chromium, mind you, so not too sure if this is the right solution.

Dunno. Reworded to avoid the URL. :)

http://codereview.chromium.org/9212044/diff/9001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/contentSecurityPolicy.html:264: allows in
order to increase security at the expense of convinience. To specify
On 2012/01/25 22:39:22, mkearney wrote:
> Spelling - 'convinience' should be 'convenience'.

Spelling a word only one way is boring.

[mkearney, 2012-01-26 00:12:24]

lgtm... 

For some reason the link to #syntax in the specification doesn't go to the
syntax location in the doc, even though that is the link when you manual go to
it. The anchor in the specification must be a bit dodgy.

[abarth-chromium, 2012-01-26 00:28:20]

On Wed, Jan 25, 2012 at 4:12 PM,  <mkearney@google.com> wrote:
> For some reason the link to #syntax in the specification doesn't go to the
> syntax location in the doc, even though that is the link when you manual go
> to
> it. The anchor in the specification must be a bit dodgy.

That's the script that makes the table of contents.  It's a W3C thing.

Adam

[Mike West, 2012-01-26 08:32:39]

On 2012/01/26 00:28:20, abarth wrote:
> On Wed, Jan 25, 2012 at 4:12 PM,  <mailto:mkearney@google.com> wrote:
> > For some reason the link to #syntax in the specification doesn't go to the
> > syntax location in the doc, even though that is the link when you manual go
> > to
> > it. The anchor in the specification must be a bit dodgy.
> 
> That's the script that makes the table of contents.  It's a W3C thing.

I'll leave it for now, might fiddle with it later.

Landing this regardless, just to make sure it makes the M18 cut.