iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Copyedits in the "Security" page. There weren't many issues and I didn't add any comments on this one. (#3302)

This commit is contained in:
cfranger 2017-02-23 22:24:02 -08:00 committed by Jules Kremer
parent f1274f68be
commit f7ad4f565b
1 changed files with 59 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
public/docs/ts/latest/guide/security.jade
View File

@ -1,17 +1,17 @@
block includes block includes
include ../_util-fns include ../_util-fns
:marked :marked
This section describes Angular's built-in This page describes Angular's built-in
protections against common web application vulnerabilities and attacks such as cross-site protections against common web-application vulnerabilities and attacks such as cross-site
scripting attacks. It does not cover application-level security, such as authentication (_Who is scripting attacks. It doesn't cover application-level security, such as authentication (_Who is
this user?_) or authorization (_What can this user do?_). this user?_) and authorization (_What can this user do?_).
For more information about the attacks and mitigations described below, see [OWASP Guide Project](https://www.owasp.org/index.php/Category:OWASP_Guide_Project). For more information about the attacks and mitigations described below, see [OWASP Guide Project](https://www.owasp.org/index.php/Category:OWASP_Guide_Project).
+ifDocsFor('ts') +ifDocsFor('ts')
.l-main-section .l-main-section
:marked :marked
# Contents: # Contents
* [Reporting vulnerabilities](#report-issues). * [Reporting vulnerabilities](#report-issues).
* [Best practices](#best-practices). * [Best practices](#best-practices).
@ -21,13 +21,12 @@ block includes
* [Auditing Angular applications](#code-review). * [Auditing Angular applications](#code-review).
:marked :marked
Try the <live-example></live-example> of the code shown in this page. You can run the <live-example></live-example> in Plunker and download the code from there.
.l-main-section .l-main-section
h2#report-issues Reporting vulnerabilities h2#report-issues Reporting vulnerabilities
:marked :marked
Email us at [security@angular.io](mailto:security@angular.io) to report vulnerabilities in To report vulnerabilities in Angular itself, email us at [security@angular.io](mailto:security@angular.io).
Angular itself.
For more information about how Google handles security issues, see [Google's security For more information about how Google handles security issues, see [Google's security
philosophy](https://www.google.com/about/appsecurity/). philosophy](https://www.google.com/about/appsecurity/).
@ -36,7 +35,7 @@ h2#report-issues Reporting vulnerabilities
h2#best-practices Best practices h2#best-practices Best practices
:marked :marked
* **Keep current with the latest Angular library releases.** * **Keep current with the latest Angular library releases.**
We regularly update our Angular libraries, and these updates may fix security defects discovered in We regularly update the Angular libraries, and these updates may fix security defects discovered in
previous versions. Check the Angular [change previous versions. Check the Angular [change
log](https://github.com/angular/angular/blob/master/CHANGELOG.md) for security-related updates. log](https://github.com/angular/angular/blob/master/CHANGELOG.md) for security-related updates.
@ -45,63 +44,65 @@ h2#best-practices Best practices
important security fixes and enhancements. Instead, share your Angular improvements with the important security fixes and enhancements. Instead, share your Angular improvements with the
community and make a pull request. community and make a pull request.
* **Avoid Angular APIs marked in the documentation as “[_Security Risk_](#bypass-security-apis).”** * **Avoid Angular APIs marked in the documentation as “_Security Risk_.”**
For more information, see the [Trusting safe values](#bypass-security-apis) section of this page.
.l-main-section .l-main-section
h2#xss Preventing cross-site scripting (XSS) h2#xss Preventing cross-site scripting (XSS)
:marked :marked
[Cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) enables attackers [Cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) enables attackers
to inject malicious code into web pages. Such code can then, for example, steal user data (in to inject malicious code into web pages. Such code can then, for example, steal user data (in
particular, their login data) or perform actions impersonating the user. This is one of the most particular, login data) or perform actions to impersonate the user. This is one of the most
common attacks on the web. common attacks on the web.
To block XSS attacks, you must prevent malicious code from entering the DOM (Document Object Model). For example, if an To block XSS attacks, you must prevent malicious code from entering the DOM (Document Object Model). For example, if
attacker can trick you into inserting a `<script>` tag in the DOM, they can run arbitrary code on attackers can trick you into inserting a `<script>` tag in the DOM, they can run arbitrary code on
your website. The attack is not limited to `<script>` tags&mdash;many elements and properties in the your website. The attack isn't limited to `<script>` tags&mdash;many elements and properties in the
DOM allow code execution, for example, `<img onerror="...">` and `<a href="javascript:...">`. If DOM allow code execution, for example, `<img onerror="...">` and `<a href="javascript:...">`. If
attacker-controlled data enters the DOM, expect security vulnerabilities. attacker-controlled data enters the DOM, expect security vulnerabilities.
### Angular’s cross-site scripting security model ### Angular’s cross-site scripting security model
To systematically block XSS bugs, Angular treats all values as untrusted by default. When a value To systematically block XSS bugs, Angular treats all values as untrusted by default. When a value
is inserted into the DOM from a template, via property, attribute, style, class binding, or interpolation, Angular sanitizes and escapes untrusted values. is inserted into the DOM from a template, via property, attribute, style, class binding, or interpolation,
Angular sanitizes and escapes untrusted values.
_Angular templates are the same as executable code_: HTML, attributes, and binding expressions _Angular templates are the same as executable code_: HTML, attributes, and binding expressions
(but not the values bound!) in templates are trusted to be safe. This means that applications must (but not the values bound) in templates are trusted to be safe. This means that applications must
prevent values that an attacker can control from ever making it into the source code of a prevent values that an attacker can control from ever making it into the source code of a
template. Never generate template source code by concatenating user input and templates! Using template. Never generate template source code by concatenating user input and templates.
the [offline template compiler](#offline-template-compiler) is an effective way to prevent these To prevent these vulnerabilities, use
vulnerabilities, also known as _template injection_. the [offline template compiler](#offline-template-compiler), also known as _template injection_.
### Sanitization and security contexts ### Sanitization and security contexts
_Sanitization_ is the inspection of an untrusted value, turning it into a value that is safe to insert into _Sanitization_ is the inspection of an untrusted value, turning it into a value that's safe to insert into
the DOM. In many cases, sanitization does not change a value at all. Sanitization depends on context: the DOM. In many cases, sanitization doesn't change a value at all. Sanitization depends on context:
a value that is harmless in CSS is potentially dangerous in a URL. a value that's harmless in CSS is potentially dangerous in a URL.
Angular defines four security contexts&mdash;HTML, style, URL, and resource URL: Angular defines the following security contexts:
* **HTML** is used when interpreting a value as HTML, for example, when binding to `innerHtml` * **HTML** is used when interpreting a value as HTML, for example, when binding to `innerHtml`.
* **Style** is used when binding CSS into the `style` property * **Style** is used when binding CSS into the `style` property.
* **URL** is used for URL properties such as `<a href>` * **URL** is used for URL properties, such as `<a href>`.
* **Resource URL** is a URL that will be loaded and executed as code, for example, in `<script src>` * **Resource URL** is a URL that will be loaded and executed as code, for example, in `<script src>`.
Angular sanitizes untrusted values for the first three items; sanitizing resource URLs is not Angular sanitizes untrusted values for HTML, styles, and URLs; sanitizing resource URLs isn't
possible because they contain arbitrary code. In development mode, Angular prints a console warning possible because they contain arbitrary code. In development mode, Angular prints a console warning
when it has to change a value during sanitization. when it has to change a value during sanitization.
### Sanitization example ### Sanitization example
The template below binds the value of `htmlSnippet`, once by interpolating it into an element's The following template binds the value of `htmlSnippet`, once by interpolating it into an element's
content, and once by binding it to the `innerHTML` property of an element: content, and once by binding it to the `innerHTML` property of an element:
+makeExample('src/app/inner-html-binding.component.html') +makeExample('src/app/inner-html-binding.component.html')
:marked :marked
Interpolated content is always escaped&mdash;the HTML is not interpreted, and the browser displays Interpolated content is always escaped&mdash;the HTML isn't interpreted and the browser displays
angle brackets in the element's text content. angle brackets in the element's text content.
For the HTML to be interpreted, you must bind it to an HTML property such as `innerHTML`. But binding For the HTML to be interpreted, bind it to an HTML property such as `innerHTML`. But binding
a value that an attacker might control into `innerHTML` normally causes an XSS a value that an attacker might control into `innerHTML` normally causes an XSS
vulnerability. For example, code contained in a `<script>` tag is executed: vulnerability. For example, code contained in a `<script>` tag is executed:
@ -110,7 +111,7 @@ h2#xss Preventing cross-site scripting (XSS)
block html-sanitization block html-sanitization
:marked :marked
Angular recognizes the value as unsafe and automatically sanitizes it, which removes the `<script>` Angular recognizes the value as unsafe and automatically sanitizes it, which removes the `<script>`
tag but keeps safe content such as the text content of the `<script>` tag, or the `<b>` element. tag but keeps safe content such as the text content of the `<script>` tag and the `<b>` element.
figure.image-display figure.image-display
img(src='/resources/images/devguide/security/binding-inner-html.png' img(src='/resources/images/devguide/security/binding-inner-html.png'
@ -119,25 +120,28 @@ block html-sanitization
:marked :marked
### Avoid direct use of the DOM APIs ### Avoid direct use of the DOM APIs
The built-in browser DOM APIs do not automatically protect you from security vulnerabilities. The built-in browser DOM APIs don't automatically protect you from security vulnerabilities.
For example, `document`, the node available through `ElementRef`, and many third-party APIs For example, `document`, the node available through `ElementRef`, and many third-party APIs
contain unsafe methods. Avoid directly interacting with the DOM and instead use Angular contain unsafe methods. Avoid directly interacting with the DOM and instead use Angular
templates where possible. templates where possible.
### Content security policy ### Content security policy
[Content Security Policy (CSP)](http://www.html5rocks.com/en/tutorials/security/content-security-policy/) is a defense-in-depth Content Security Policy (CSP) is a defense-in-depth
technique to prevent XSS. To enable CSP, configure your web server to return an appropriate technique to prevent XSS. To enable CSP, configure your web server to return an appropriate
`Content-Security-Policy` HTTP header. `Content-Security-Policy` HTTP header. Read more about content security policy at
[An Introduction to Content Security Policy](http://www.html5rocks.com/en/tutorials/security/content-security-policy/)
on the HTML5Rocks website.
<a id="offline-template-compiler"></a> <a id="offline-template-compiler"></a>
### Use the offline template compiler ### Use the offline template compiler
The offline template compiler prevents a whole class of vulnerabilities called template injection, The offline template compiler prevents a whole class of vulnerabilities called template injection,
and also greatly improves application performance. Use the offline template compiler in production and greatly improves application performance. Use the offline template compiler in production
deployments; do not dynamically generate templates. Angular trusts template code, so generating deployments; don't dynamically generate templates. Angular trusts template code, so generating
templates, in particular templates containing user data, circumvents Angular's built-in protections. For information about how to dynamically construct forms in a safe way, see templates, in particular templates containing user data, circumvents Angular's built-in protections.
[Dynamic Forms Cookbook](../cookbook/dynamic-form.html). For information about dynamically constructing forms in a safe way, see the
[Dynamic Forms](../cookbook/dynamic-form.html) cookbook page.
### Server-side XSS protection ### Server-side XSS protection
@ -145,7 +149,7 @@ block html-sanitization
Angular application is the same as injecting executable code into the Angular application is the same as injecting executable code into the
application: it gives the attacker full control over the application. To prevent this, application: it gives the attacker full control over the application. To prevent this,
use a templating language that automatically escapes values to prevent XSS vulnerabilities on use a templating language that automatically escapes values to prevent XSS vulnerabilities on
the server. Do not generate Angular templates on the server side using a templating language; doing this the server. Don't generate Angular templates on the server side using a templating language; doing this
carries a high risk of introducing template-injection vulnerabilities. carries a high risk of introducing template-injection vulnerabilities.
block bypass-security-apis block bypass-security-apis
@ -155,11 +159,11 @@ block bypass-security-apis
Sometimes applications genuinely need to include executable code, display an `<iframe>` from some Sometimes applications genuinely need to include executable code, display an `<iframe>` from some
URL, or construct potentially dangerous URLs. To prevent automatic sanitization in any of these URL, or construct potentially dangerous URLs. To prevent automatic sanitization in any of these
situations, you can tell Angular that you inspected a value, checked how it was generated, and made situations, you can tell Angular that you inspected a value, checked how it was generated, and made
sure it will always be secure. But **be careful**! If you trust a value that might be malicious, you sure it will always be secure. But *be careful*. If you trust a value that might be malicious, you
are introducing a security vulnerability into your application. If in doubt, find a professional are introducing a security vulnerability into your application. If in doubt, find a professional
security reviewer. security reviewer.
You can mark a value as trusted by injecting `DomSanitizer` and calling one of the To mark a value as trusted, inject `DomSanitizer` and call one of the
following methods: following methods:
* `bypassSecurityTrustHtml` * `bypassSecurityTrustHtml`
@ -168,7 +172,7 @@ block bypass-security-apis
* `bypassSecurityTrustUrl` * `bypassSecurityTrustUrl`
* `bypassSecurityTrustResourceUrl` * `bypassSecurityTrustResourceUrl`
Remember, whether a value is safe depends on context, so you need to choose the right context for Remember, whether a value is safe depends on context, so choose the right context for
your intended use of the value. Imagine that the following template needs to bind a URL to a your intended use of the value. Imagine that the following template needs to bind a URL to a
`javascript:alert(...)` call: `javascript:alert(...)` call:
@ -177,7 +181,7 @@ block bypass-security-apis
:marked :marked
Normally, Angular automatically sanitizes the URL, disables the dangerous code, and Normally, Angular automatically sanitizes the URL, disables the dangerous code, and
in development mode, logs this action to the console. To prevent in development mode, logs this action to the console. To prevent
this, you can mark the URL value as a trusted URL using the `bypassSecurityTrustUrl` call: this, mark the URL value as a trusted URL using the `bypassSecurityTrustUrl` call:
+makeExcerpt('src/app/bypass-security.component.ts ()', 'trust-url') +makeExcerpt('src/app/bypass-security.component.ts ()', 'trust-url')
@ -187,11 +191,11 @@ block bypass-security-apis
:marked :marked
If you need to convert user input into a trusted value, use a If you need to convert user input into a trusted value, use a
controller method. The template below allows users to enter a YouTube video ID and load the controller method. The following template allows users to enter a YouTube video ID and load the
corresponding video in an `<iframe>`. The `<iframe src>` attribute is a resource URL security corresponding video in an `<iframe>`. The `<iframe src>` attribute is a resource URL security
context, because an untrusted source can, for example, smuggle in file downloads that unsuspecting users context, because an untrusted source can, for example, smuggle in file downloads that unsuspecting users
could execute. So call a method on the controller to construct a trusted video URL, that causes could execute. So call a method on the controller to construct a trusted video URL, which causes
Angular to then allow binding into `<iframe src>`: Angular to allow binding into `<iframe src>`:
+makeExcerpt('src/app/bypass-security.component.html', 'iframe') +makeExcerpt('src/app/bypass-security.component.html', 'iframe')
+makeExcerpt('src/app/bypass-security.component.ts ()', 'trust-video-url') +makeExcerpt('src/app/bypass-security.component.ts ()', 'trust-video-url')
@ -202,23 +206,23 @@ block http
:marked :marked
Angular has built-in support to help prevent two common HTTP vulnerabilities, cross-site request Angular has built-in support to help prevent two common HTTP vulnerabilities, cross-site request
forgery (CSRF or XSRF) and cross-site script inclusion (XSSI). Both of these must be mitigated primarily forgery (CSRF or XSRF) and cross-site script inclusion (XSSI). Both of these must be mitigated primarily
on the server side, but Angular ships helpers to make integration on the client side easier. on the server side, but Angular provides helpers to make integration on the client side easier.
h3#xsrf Cross-site request forgery h3#xsrf Cross-site request forgery
:marked :marked
In a cross-site request forgery (CSRF or XSRF), an attacker tricks the user into visiting In a cross-site request forgery (CSRF or XSRF), an attacker tricks the user into visiting
a different web page (e.g. `evil.com`) with malignant code that secretly sends a malicious request a different web page (such as `evil.com`) with malignant code that secretly sends a malicious request
to your application's web server (e.g. `example-bank.com`). to the application's web server (such as `example-bank.com`).
Assume the user is logged into the application at `example-bank.com`. Assume the user is logged into the application at `example-bank.com`.
The user opens an email and clicks a link to `evil.com` which opens in a new tab. The user opens an email and clicks a link to `evil.com`, which opens in a new tab.
The `evil.com` page immediately sends a malicious request to `example-bank.com`. The `evil.com` page immediately sends a malicious request to `example-bank.com`.
Perhaps it's a request to transfer money from the user's account to the attacker's account. Perhaps it's a request to transfer money from the user's account to the attacker's account.
The browser automatically sends the `example-bank.com` cookies (including the authentication cookie) with this request. The browser automatically sends the `example-bank.com` cookies (including the authentication cookie) with this request.
The `example-bank.com` server, if it lacks XSRF protection, can't tell the difference between a legitimate request from the application If the `example-bank.com` server lacks XSRF protection, it can't tell the difference between a legitimate
and the forged request from `evil.com`. request from the application and the forged request from `evil.com`.
To prevent this, the application must ensure that a user request originates from the real To prevent this, the application must ensure that a user request originates from the real
application, not from a different site. application, not from a different site.
@ -243,7 +247,7 @@ block http
includes a matching `XSRF-TOKEN` cookie and `X-XSRF-TOKEN` header. includes a matching `XSRF-TOKEN` cookie and `X-XSRF-TOKEN` header.
XSRF/CSRF tokens should be unique per user and session, have a large random value generated by a XSRF/CSRF tokens should be unique per user and session, have a large random value generated by a
cryptographically secure random number generator, and should expire in a day or two. cryptographically secure random number generator, and expire in a day or two.
Your server may use a different cookie or header name for this purpose. Your server may use a different cookie or header name for this purpose.
An Angular application can customize cookie and header names by providing its own `CookieXSRFStrategy` values. An Angular application can customize cookie and header names by providing its own `CookieXSRFStrategy` values.
@ -282,7 +286,7 @@ block http
post](https://security.googleblog.com/2011/05/website-security-for-webmasters.html). post](https://security.googleblog.com/2011/05/website-security-for-webmasters.html).
.l-main-section .l-main-section
h2#code-review Auditing angular applications h2#code-review Auditing Angular applications
:marked :marked
Angular applications must follow the same security principles as regular web applications, and Angular applications must follow the same security principles as regular web applications, and
must be audited as such. Angular-specific APIs that should be audited in a security review, must be audited as such. Angular-specific APIs that should be audited in a security review,