invisi/angular.js
1
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

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

Browse Source 
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 #15142
This commit is contained in:
davidcigital
2016-09-15 13:59:55 +01:00
committed by Georgios Kalpakas
parent f1cc58c7d2
commit b59bc0b01d
1 changed files with 25 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ng/directive/ngCsp.js
+25 -19
View File
@@ -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">`