docs(ngCsp): update explanation of CSP rules and how they affect Angular

davidcigital · petebacondarwin · commit 77b5cf87ed43 · 2016-11-21T23:11:08.000Z
Update the description of CSP, mainly regarding `unsafe-eval` and `unsafe-inline`. The way it was presented previously was slightly misleading as it indicated that these were rules forbidding certain things, when in fact it's a keyword in the CSP that disables the very rule that was described. The updated text clarifies this better. Closes angular#15142
diff --git a/src/ng/directive/ngCsp.js b/src/ng/directive/ngCsp.js
@@ -7,28 +7,34 @@
  * @element html
  * @description
  *
- * Angular has some features that can break certain
+ * Angular has some features that can conflict with certain restrictions that are applied when using
  * [CSP (Content Security Policy)](https://developer.mozilla.org/en/Security/CSP) rules.
  *
- * If you intend to implement these rules then you must tell Angular not to use these features.
+ * If you intend to implement CSP with these rules then you must tell Angular not to use these
+ * features.
  *
  * This is necessary when developing things like Google Chrome Extensions or Universal Windows Apps.
  *
  *
- * The following rules affect Angular:
+ * The following default rules in CSP affect Angular:
  *
- * * `unsafe-eval`: this rule forbids apps to use `eval` or `Function(string)` generated functions
- * (among other things). Angular makes use of this in the {@link $parse} service to provide a 30%
- * increase in the speed of evaluating Angular expressions.
+ * * The use of `eval()`, `Function(string)` and similar functions to dynamically create and execute
+ * code from strings is forbidden. Angular makes use of this in the {@link $parse} service to
+ * provide a 30% increase in the speed of evaluating Angular expressions. (This CSP rule can be
+ * disabled with the CSP keyword `unsafe-eval`, but it is generally not recommended as it would
+ * weaken the protections offered by CSP.)
  *
- * * `unsafe-inline`: this rule forbids apps from inject custom styles into the document. Angular
- * makes use of this to include some CSS rules (e.g. {@link ngCloak} and {@link ngHide}).
- * To make these directives work when a CSP rule is blocking inline styles, you must link to the
- * `angular-csp.css` in your HTML manually.
+ * * The use of inline resources, such as inline `<script>` and `<style>` elements, are forbidden.
+ * This prevents apps from injecting custom styles directly into the document. Angular makes use of
+ * this to include some CSS rules (e.g. {@link ngCloak} and {@link ngHide}). To make these
+ * directives work when a CSP rule is blocking inline styles, you must link to the `angular-csp.css`
+ * in your HTML manually. (This CSP rule can be disabled with the CSP keyword `unsafe-inline`, but
+ * it is generally not recommended as it would weaken the protections offered by CSP.)
  *
- * If you do not provide `ngCsp` then Angular tries to autodetect if CSP is blocking unsafe-eval
- * and automatically deactivates this feature in the {@link $parse} service. This autodetection,
- * however, triggers a CSP error to be logged in the console:
+ * If you do not provide `ngCsp` then Angular tries to autodetect if CSP is blocking dynamic code
+ * creation from strings (e.g., `unsafe-eval` not specified in CSP header) and automatically
+ * deactivates this feature in the {@link $parse} service. This autodetection, however, triggers a
+ * CSP error to be logged in the console:
  *
  * ```
  * Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of
@@ -53,15 +59,15 @@
  *
  *
  * * No declaration means that Angular will assume that you can do inline styles, but it will do
- * a runtime check for unsafe-eval. E.g. `<body>`. This is backwardly compatible with previous versions
- * of Angular.
+ * a runtime check for unsafe-eval. E.g. `<body>`. This is backwardly compatible with previous
+ * versions of Angular.
  *
  * * A simple `ng-csp` (or `data-ng-csp`) attribute will tell Angular to deactivate both inline
- * styles and unsafe eval. E.g. `<body ng-csp>`. This is backwardly compatible with previous versions
- * of Angular.
+ * styles and unsafe eval. E.g. `<body ng-csp>`. This is backwardly compatible with previous
+ * versions of Angular.
  *
- * * Specifying only `no-unsafe-eval` tells Angular that we must not use eval, but that we can inject
- * inline styles. E.g. `<body ng-csp="no-unsafe-eval">`.
+ * * Specifying only `no-unsafe-eval` tells Angular that we must not use eval, but that we can
+ * inject inline styles. E.g. `<body ng-csp="no-unsafe-eval">`.
  *
  * * Specifying only `no-inline-style` tells Angular that we must not inject styles, but that we can
  * run eval - no automatic check for unsafe eval will occur. E.g. `<body ng-csp="no-inline-style">`

Original file line number	Diff line number	Diff line change
`@@ -7,28 +7,34 @@`
`7`	`7`	`* @element html`
`8`	`8`	`* @description`
`9`	`9`	`*`
`10`		`- * Angular has some features that can break certain`
	`10`	`+ * Angular has some features that can conflict with certain restrictions that are applied when using`
`11`	`11`	`* [CSP (Content Security Policy)](https://developer.mozilla.org/en/Security/CSP) rules.`
`12`	`12`	`*`
`13`		`- * If you intend to implement these rules then you must tell Angular not to use these features.`
	`13`	`+ * If you intend to implement CSP with these rules then you must tell Angular not to use these`
	`14`	`+ * features.`
`14`	`15`	`*`
`15`	`16`	`* This is necessary when developing things like Google Chrome Extensions or Universal Windows Apps.`
`16`	`17`	`*`
`17`	`18`	`*`
`18`		`- * The following rules affect Angular:`
	`19`	`+ * The following default rules in CSP affect Angular:`
`19`	`20`	`*`
`20`		- * * `unsafe-eval`: this rule forbids apps to use `eval` or `Function(string)` generated functions
`21`		`- * (among other things). Angular makes use of this in the {@link $parse} service to provide a 30%`
`22`		`- * increase in the speed of evaluating Angular expressions.`
	`21`	+ * * The use of `eval()`, `Function(string)` and similar functions to dynamically create and execute
	`22`	`+ * code from strings is forbidden. Angular makes use of this in the {@link $parse} service to`
	`23`	`+ * provide a 30% increase in the speed of evaluating Angular expressions. (This CSP rule can be`
	`24`	+ * disabled with the CSP keyword `unsafe-eval`, but it is generally not recommended as it would
	`25`	`+ * weaken the protections offered by CSP.)`
`23`	`26`	`*`
`24`		- * * `unsafe-inline`: this rule forbids apps from inject custom styles into the document. Angular
`25`		`- * makes use of this to include some CSS rules (e.g. {@link ngCloak} and {@link ngHide}).`
`26`		`- * To make these directives work when a CSP rule is blocking inline styles, you must link to the`
`27`		- * `angular-csp.css` in your HTML manually.
	`27`	+ * * The use of inline resources, such as inline `<script>` and `<style>` elements, are forbidden.
	`28`	`+ * This prevents apps from injecting custom styles directly into the document. Angular makes use of`
	`29`	`+ * this to include some CSS rules (e.g. {@link ngCloak} and {@link ngHide}). To make these`
	`30`	+ * directives work when a CSP rule is blocking inline styles, you must link to the `angular-csp.css`
	`31`	+ * in your HTML manually. (This CSP rule can be disabled with the CSP keyword `unsafe-inline`, but
	`32`	`+ * it is generally not recommended as it would weaken the protections offered by CSP.)`
`28`	`33`	`*`
`29`		- * If you do not provide `ngCsp` then Angular tries to autodetect if CSP is blocking unsafe-eval
`30`		`- * and automatically deactivates this feature in the {@link $parse} service. This autodetection,`
`31`		`- * however, triggers a CSP error to be logged in the console:`
	`34`	+ * If you do not provide `ngCsp` then Angular tries to autodetect if CSP is blocking dynamic code
	`35`	+ * creation from strings (e.g., `unsafe-eval` not specified in CSP header) and automatically
	`36`	`+ * deactivates this feature in the {@link $parse} service. This autodetection, however, triggers a`
	`37`	`+ * CSP error to be logged in the console:`
`32`	`38`	`*`
`33`	`39`	* ```
`34`	`40`	`* Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of`
`@@ -53,15 +59,15 @@`
`53`	`59`	`*`
`54`	`60`	`*`
`55`	`61`	`* * No declaration means that Angular will assume that you can do inline styles, but it will do`
`56`		- * a runtime check for unsafe-eval. E.g. `<body>`. This is backwardly compatible with previous versions
`57`		`- * of Angular.`
	`62`	+ * a runtime check for unsafe-eval. E.g. `<body>`. This is backwardly compatible with previous
	`63`	`+ * versions of Angular.`
`58`	`64`	`*`
`59`	`65`	* * A simple `ng-csp` (or `data-ng-csp`) attribute will tell Angular to deactivate both inline
`60`		- * styles and unsafe eval. E.g. `<body ng-csp>`. This is backwardly compatible with previous versions
`61`		`- * of Angular.`
	`66`	+ * styles and unsafe eval. E.g. `<body ng-csp>`. This is backwardly compatible with previous
	`67`	`+ * versions of Angular.`
`62`	`68`	`*`
`63`		- * * Specifying only `no-unsafe-eval` tells Angular that we must not use eval, but that we can inject
`64`		- * inline styles. E.g. `<body ng-csp="no-unsafe-eval">`.
	`69`	+ * * Specifying only `no-unsafe-eval` tells Angular that we must not use eval, but that we can
	`70`	+ * inject inline styles. E.g. `<body ng-csp="no-unsafe-eval">`.
`65`	`71`	`*`
`66`	`72`	* * Specifying only `no-inline-style` tells Angular that we must not inject styles, but that we can
`67`	`73`	* run eval - no automatic check for unsafe eval will occur. E.g. `<body ng-csp="no-inline-style">`