docs(API): 翻译完了 DomSanitizer
This commit is contained in:
parent
7e8b60ce31
commit
84f95e5864
|
@ -89,7 +89,7 @@
|
||||||
[x] | core/AfterViewInit | 0.18
|
[x] | core/AfterViewInit | 0.18
|
||||||
[x] | forms/ReactiveFormsModule | 0.18
|
[x] | forms/ReactiveFormsModule | 0.18
|
||||||
[x] | common/http/HTTP_INTERCEPTORS | 0.18
|
[x] | common/http/HTTP_INTERCEPTORS | 0.18
|
||||||
[ ] | platform-browser/DomSanitizer | 0.18
|
[x] | platform-browser/DomSanitizer | 0.18
|
||||||
[ ] | core/PipeTransform | 0.18
|
[ ] | core/PipeTransform | 0.18
|
||||||
[ ] | core/SimpleChange | 0.18
|
[ ] | core/SimpleChange | 0.18
|
||||||
[ ] | core/SimpleChanges | 0.18
|
[ ] | core/SimpleChanges | 0.18
|
||||||
|
|
|
@ -18,6 +18,7 @@ export {SecurityContext};
|
||||||
* Marker interface for a value that's safe to use in a particular context.
|
* Marker interface for a value that's safe to use in a particular context.
|
||||||
*
|
*
|
||||||
*
|
*
|
||||||
|
* 一个标记性接口,用于表示一个值可以安全的用在特定的上下文中。
|
||||||
*/
|
*/
|
||||||
export interface SafeValue {}
|
export interface SafeValue {}
|
||||||
|
|
||||||
|
@ -25,6 +26,7 @@ export interface SafeValue {}
|
||||||
* Marker interface for a value that's safe to use as HTML.
|
* Marker interface for a value that's safe to use as HTML.
|
||||||
*
|
*
|
||||||
*
|
*
|
||||||
|
* 一个标记性接口,用于表示一个值可以安全地用在 HTML 上下文中。
|
||||||
*/
|
*/
|
||||||
export interface SafeHtml extends SafeValue {}
|
export interface SafeHtml extends SafeValue {}
|
||||||
|
|
||||||
|
@ -32,6 +34,7 @@ export interface SafeHtml extends SafeValue {}
|
||||||
* Marker interface for a value that's safe to use as style (CSS).
|
* Marker interface for a value that's safe to use as style (CSS).
|
||||||
*
|
*
|
||||||
*
|
*
|
||||||
|
* 一个标记性接口,用于表示一个值可以安全地用在样式(CSS)上下文中。
|
||||||
*/
|
*/
|
||||||
export interface SafeStyle extends SafeValue {}
|
export interface SafeStyle extends SafeValue {}
|
||||||
|
|
||||||
|
@ -39,6 +42,7 @@ export interface SafeStyle extends SafeValue {}
|
||||||
* Marker interface for a value that's safe to use as JavaScript.
|
* Marker interface for a value that's safe to use as JavaScript.
|
||||||
*
|
*
|
||||||
*
|
*
|
||||||
|
* 一个标记性接口,用于表示一个值可以安全地用在 JavaScript 上下文中。
|
||||||
*/
|
*/
|
||||||
export interface SafeScript extends SafeValue {}
|
export interface SafeScript extends SafeValue {}
|
||||||
|
|
||||||
|
@ -46,6 +50,7 @@ export interface SafeScript extends SafeValue {}
|
||||||
* Marker interface for a value that's safe to use as a URL linking to a document.
|
* Marker interface for a value that's safe to use as a URL linking to a document.
|
||||||
*
|
*
|
||||||
*
|
*
|
||||||
|
* 一个标记性接口,用于表示一个值可以安全地用作 URL 链接到一个文档。
|
||||||
*/
|
*/
|
||||||
export interface SafeUrl extends SafeValue {}
|
export interface SafeUrl extends SafeValue {}
|
||||||
|
|
||||||
|
@ -53,6 +58,7 @@ export interface SafeUrl extends SafeValue {}
|
||||||
* Marker interface for a value that's safe to use as a URL to load executable code from.
|
* Marker interface for a value that's safe to use as a URL to load executable code from.
|
||||||
*
|
*
|
||||||
*
|
*
|
||||||
|
* 一个标记性接口,用于表示一个值可以安全地用作 URL 以加载可执行代码。
|
||||||
*/
|
*/
|
||||||
export interface SafeResourceUrl extends SafeValue {}
|
export interface SafeResourceUrl extends SafeValue {}
|
||||||
|
|
||||||
|
@ -60,41 +66,65 @@ export interface SafeResourceUrl extends SafeValue {}
|
||||||
* DomSanitizer helps preventing Cross Site Scripting Security bugs (XSS) by sanitizing
|
* DomSanitizer helps preventing Cross Site Scripting Security bugs (XSS) by sanitizing
|
||||||
* values to be safe to use in the different DOM contexts.
|
* values to be safe to use in the different DOM contexts.
|
||||||
*
|
*
|
||||||
|
* DomSanitizer 可以把值净化为在不同 DOM 上下文中的安全内容,来帮你防范跨站脚本攻击(XSS)类的安全问题。
|
||||||
|
*
|
||||||
* For example, when binding a URL in an `<a [href]="someValue">` hyperlink, `someValue` will be
|
* For example, when binding a URL in an `<a [href]="someValue">` hyperlink, `someValue` will be
|
||||||
* sanitized so that an attacker cannot inject e.g. a `javascript:` URL that would execute code on
|
* sanitized so that an attacker cannot inject e.g. a `javascript:` URL that would execute code on
|
||||||
* the website.
|
* the website.
|
||||||
*
|
*
|
||||||
|
* 比如,如果要在 `<a [href]="someValue">` 的链接中绑定一个 URL,`someValue` 将会被净化,
|
||||||
|
* 以防范攻击者注入 `javascript:` 之类的 URL,并借此在网站上执行代码。
|
||||||
|
*
|
||||||
* In specific situations, it might be necessary to disable sanitization, for example if the
|
* In specific situations, it might be necessary to disable sanitization, for example if the
|
||||||
* application genuinely needs to produce a `javascript:` style link with a dynamic value in it.
|
* application genuinely needs to produce a `javascript:` style link with a dynamic value in it.
|
||||||
* Users can bypass security by constructing a value with one of the `bypassSecurityTrust...`
|
* Users can bypass security by constructing a value with one of the `bypassSecurityTrust...`
|
||||||
* methods, and then binding to that value from the template.
|
* methods, and then binding to that value from the template.
|
||||||
*
|
*
|
||||||
|
* 在特定场景下,可能要禁用净化机制,比如,如果应用程序真的需要生成具有动态值的 `javascript:` 链接。
|
||||||
|
* 用户可以通过使用 `bypassSecurityTrust...` 方法来构建出一个值,以绕过安全性检查,并在模板中绑定它。
|
||||||
|
*
|
||||||
* These situations should be very rare, and extraordinary care must be taken to avoid creating a
|
* These situations should be very rare, and extraordinary care must be taken to avoid creating a
|
||||||
* Cross Site Scripting (XSS) security bug!
|
* Cross Site Scripting (XSS) security bug!
|
||||||
*
|
*
|
||||||
|
* 这种场景其实非常罕见,必须特别小心,避免引入跨站脚本攻击(XSS)类的安全风险。
|
||||||
|
*
|
||||||
* When using `bypassSecurityTrust...`, make sure to call the method as early as possible and as
|
* When using `bypassSecurityTrust...`, make sure to call the method as early as possible and as
|
||||||
* close as possible to the source of the value, to make it easy to verify no security bug is
|
* close as possible to the source of the value, to make it easy to verify no security bug is
|
||||||
* created by its use.
|
* created by its use.
|
||||||
*
|
*
|
||||||
|
* 当使用 `bypassSecurityTrust...` 时,请尽量确保尽早调用该方法,并且让他尽可能接近值的来源,以便能更容易地验证使用它时有没有引入安全风险。
|
||||||
|
*
|
||||||
* It is not required (and not recommended) to bypass security if the value is safe, e.g. a URL that
|
* It is not required (and not recommended) to bypass security if the value is safe, e.g. a URL that
|
||||||
* does not start with a suspicious protocol, or an HTML snippet that does not contain dangerous
|
* does not start with a suspicious protocol, or an HTML snippet that does not contain dangerous
|
||||||
* code. The sanitizer leaves safe values intact.
|
* code. The sanitizer leaves safe values intact.
|
||||||
*
|
*
|
||||||
|
* 如果该值本身是安全的,则不需要绕过安全性检查,比如那些没有使用可疑协议的 URL 或者不包含危险代码的 HTML 片段。
|
||||||
|
* 净化器会确保值的安全性。
|
||||||
|
*
|
||||||
* @security Calling any of the `bypassSecurityTrust...` APIs disables Angular's built-in
|
* @security Calling any of the `bypassSecurityTrust...` APIs disables Angular's built-in
|
||||||
* sanitization for the value passed in. Carefully check and audit all values and code paths going
|
* sanitization for the value passed in. Carefully check and audit all values and code paths going
|
||||||
* into this call. Make sure any user data is appropriately escaped for this security context.
|
* into this call. Make sure any user data is appropriately escaped for this security context.
|
||||||
* For more detail, see the [Security Guide](http://g.co/ng/security).
|
* For more detail, see the [Security Guide](http://g.co/ng/security).
|
||||||
*
|
*
|
||||||
*
|
*
|
||||||
|
* 调用任何 `bypassSecurityTrust...` API 都会禁用 Anuglar 对传入的值的内置净化机制。
|
||||||
|
* 要小心翼翼的检查和审计所有的值和到该调用的代码执行路径。
|
||||||
|
* 要确保任何一个用户数据都针对这个安全上下文进行过适当的转义(escape)。
|
||||||
|
* 欲知详情,参见[安全](http://g.co/ng/security)。
|
||||||
*/
|
*/
|
||||||
export abstract class DomSanitizer implements Sanitizer {
|
export abstract class DomSanitizer implements Sanitizer {
|
||||||
/**
|
/**
|
||||||
* Sanitizes a value for use in the given SecurityContext.
|
* Sanitizes a value for use in the given SecurityContext.
|
||||||
*
|
*
|
||||||
|
* 为在给定的 SecurityContext 中使用而对 `value` 进行转义。
|
||||||
|
*
|
||||||
* If value is trusted for the context, this method will unwrap the contained safe value and use
|
* If value is trusted for the context, this method will unwrap the contained safe value and use
|
||||||
* it directly. Otherwise, value will be sanitized to be safe in the given context, for example
|
* it directly. Otherwise, value will be sanitized to be safe in the given context, for example
|
||||||
* by replacing URLs that have an unsafe protocol part (such as `javascript:`). The implementation
|
* by replacing URLs that have an unsafe protocol part (such as `javascript:`). The implementation
|
||||||
* is responsible to make sure that the value can definitely be safely used in the given context.
|
* is responsible to make sure that the value can definitely be safely used in the given context.
|
||||||
|
*
|
||||||
|
* 如果这个值在这个上下文中是可信的,则该方法会解开所包含的安全值,并且直接使用它;否则,这个值就会根据给定的安全上下文净化成安全的,比如替换那些具有不安全协议(例如 `javascript:`)的 URL。
|
||||||
|
* 该实现负责确保在给定的上下文中可以绝对安全的使用该值。
|
||||||
*/
|
*/
|
||||||
abstract sanitize(context: SecurityContext, value: SafeValue|string|null): string|null;
|
abstract sanitize(context: SecurityContext, value: SafeValue|string|null): string|null;
|
||||||
|
|
||||||
|
@ -103,24 +133,37 @@ export abstract class DomSanitizer implements Sanitizer {
|
||||||
* is unsafe (e.g. contains `<script>` tags) and the code should be executed. The sanitizer will
|
* is unsafe (e.g. contains `<script>` tags) and the code should be executed. The sanitizer will
|
||||||
* leave safe HTML intact, so in most situations this method should not be used.
|
* leave safe HTML intact, so in most situations this method should not be used.
|
||||||
*
|
*
|
||||||
|
* 绕过安全检查,并信任给定的值是一个安全的 HTML。只有当要绑定的 HTML 是不安全内容(比如包含 `<script>`)而且你确实希望运行这些代码时,才需要使用它。
|
||||||
|
* 净化器会确保安全 HTML 的完整性,因此在大多数场景下都不需要使用该方法。
|
||||||
|
*
|
||||||
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
||||||
* security risks!
|
* security risks!
|
||||||
|
*
|
||||||
|
* **警告:** 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!
|
||||||
*/
|
*/
|
||||||
abstract bypassSecurityTrustHtml(value: string): SafeHtml;
|
abstract bypassSecurityTrustHtml(value: string): SafeHtml;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Bypass security and trust the given value to be safe style value (CSS).
|
* Bypass security and trust the given value to be safe style value (CSS).
|
||||||
*
|
*
|
||||||
|
* 绕过安全检查,并信任给定的值是一个安全的样式(CSS)。
|
||||||
|
*
|
||||||
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
||||||
* security risks!
|
* security risks!
|
||||||
|
*
|
||||||
|
* **警告:** 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!
|
||||||
*/
|
*/
|
||||||
abstract bypassSecurityTrustStyle(value: string): SafeStyle;
|
abstract bypassSecurityTrustStyle(value: string): SafeStyle;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Bypass security and trust the given value to be safe JavaScript.
|
* Bypass security and trust the given value to be safe JavaScript.
|
||||||
*
|
*
|
||||||
|
* 绕过安全检查,并信任给定的值是一个安全的JavaScript。
|
||||||
|
*
|
||||||
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
||||||
* security risks!
|
* security risks!
|
||||||
|
*
|
||||||
|
* **警告:** 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!
|
||||||
*/
|
*/
|
||||||
abstract bypassSecurityTrustScript(value: string): SafeScript;
|
abstract bypassSecurityTrustScript(value: string): SafeScript;
|
||||||
|
|
||||||
|
@ -128,8 +171,12 @@ export abstract class DomSanitizer implements Sanitizer {
|
||||||
* Bypass security and trust the given value to be a safe style URL, i.e. a value that can be used
|
* Bypass security and trust the given value to be a safe style URL, i.e. a value that can be used
|
||||||
* in hyperlinks or `<img src>`.
|
* in hyperlinks or `<img src>`.
|
||||||
*
|
*
|
||||||
|
* 绕过安全检查,并信任给定的值是一个安全的样式 URL。也就是说该值可安全地用在链接或 `<img src>` 中。
|
||||||
|
*
|
||||||
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
||||||
* security risks!
|
* security risks!
|
||||||
|
*
|
||||||
|
* **警告:** 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!
|
||||||
*/
|
*/
|
||||||
abstract bypassSecurityTrustUrl(value: string): SafeUrl;
|
abstract bypassSecurityTrustUrl(value: string): SafeUrl;
|
||||||
|
|
||||||
|
@ -137,8 +184,12 @@ export abstract class DomSanitizer implements Sanitizer {
|
||||||
* Bypass security and trust the given value to be a safe resource URL, i.e. a location that may
|
* Bypass security and trust the given value to be a safe resource URL, i.e. a location that may
|
||||||
* be used to load executable code from, like `<script src>`, or `<iframe src>`.
|
* be used to load executable code from, like `<script src>`, or `<iframe src>`.
|
||||||
*
|
*
|
||||||
|
* 绕过安全检查,并信任给定的值是一个安全的资源 URL。也就是说该地址可以安全的用于加载可执行代码,比如 `<script src>` 或 `<iframe src>`。
|
||||||
|
*
|
||||||
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
* **WARNING:** calling this method with untrusted user data exposes your application to XSS
|
||||||
* security risks!
|
* security risks!
|
||||||
|
*
|
||||||
|
* **警告:** 使用不可信的用户数据调用此方法将会让你的应用暴露在 XSS 安全风险之下!
|
||||||
*/
|
*/
|
||||||
abstract bypassSecurityTrustResourceUrl(value: string): SafeResourceUrl;
|
abstract bypassSecurityTrustResourceUrl(value: string): SafeResourceUrl;
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue