浏览器策略

¥Browser Policy

browser-policy 系列软件包是 Webapp 的一部分，可让你设置将由较新的浏览器强制执行的安全相关策略。这些策略可帮助你预防和缓解常见攻击，如跨站点脚本和点击劫持。

¥The browser-policy family of packages, part of Webapp, lets you set security-related policies that will be enforced by newer browsers. These policies help you prevent and mitigate common attacks like cross-site scripting and clickjacking.

详细信息

¥Details

将 browser-policy 添加到应用时，你将获得 HTTP 标头 X-Frame-Options 和 Content-Security-Policy 的默认配置。X-Frame-Options 告诉浏览器哪些网站可以框架你的应用。你应该只让受信任的网站构建你的应用，因为恶意网站可能会使用 点击劫持攻击 损害你的用户。Content-Security-Policy 告诉浏览器你的应用可以从哪里加载内容，这鼓励了安全实践并减轻了跨站点脚本攻击的危害。如果默认值不合适，browser-policy 还为你提供配置这些策略的功能。

¥When you add browser-policy to your app, you get default configurations for the HTTP headers X-Frame-Options and Content-Security-Policy. X-Frame-Options tells the browser which websites are allowed to frame your app. You should only let trusted websites frame your app, because malicious sites could harm your users with clickjacking attacks. Content-Security-Policy tells the browser where your app can load content from, which encourages safe practices and mitigates the damage of a cross-site-scripting attack. browser-policy also provides functions for you to configure these policies if the defaults are not suitable.

如果你只想使用 Content-Security-Policy 或 X-Frame-Options 而不是两者，则可以添加单独的包 browser-policy-content 或 browser-policy-framing 而不是 browser-policy。

¥If you only want to use Content-Security-Policy or X-Frame-Options but not both, you can add the individual packages browser-policy-content or browser-policy-framing instead of browser-policy.

对于大多数应用，我们建议你采取以下步骤：

¥For most apps, we recommend that you take the following steps:

• 将 browser-policy 添加到你的应用以启用启动策略。使用此入门策略，你的应用的客户端代码将能够仅从其自己的来源加载内容（图片、脚本、字体等），但 XMLHttpRequests 和 WebSocket 连接可以转到任何来源。此外，你的应用的客户端代码将无法使用将字符串转换为代码的函数（例如 eval()）。用户的浏览器只会让你的应用被与你的应用同源的网页框架。

  ¥Add browser-policy to your app to enable a starter policy. With this starter policy, your app's client code will be able to load content (images, scripts, fonts, etc.) only from its own origin, except that XMLHttpRequests and WebSocket connections can go to any origin. Further, your app's client code will not be able to use functions such as eval() that convert strings to code. Users' browsers will only let your app be framed by web pages on the same origin as your app.

• 你可以使用下面描述的函数自定义策略。如果你的应用不需要任何内联 Javascript（例如内联 <script> 标签），我们建议你通过在服务器代码中调用 BrowserPolicy.content.disallowInlineScripts() 来修改策略。这将导致你的应用加载时产生一次额外的往返，但通过禁用除从 script src 属性加载的脚本之外的所有脚本，将有助于防止跨站点脚本攻击。

  ¥You can use the functions described below to customize the policies. If your app does not need any inline Javascript such as inline <script> tags, we recommend that you modify the policy by calling BrowserPolicy.content.disallowInlineScripts() in server code. This will result in one extra round trip when your app is loaded, but will help prevent cross-site scripting attacks by disabling all scripts except those loaded from a script src attribute.

Meteor 在服务器启动时确定浏览器策略，因此你应该在顶层应用代码或 Meteor.startup 中调用服务器上的 BrowserPolicy 函数。BrowserPolicy 函数不能在客户端代码中使用。

¥Meteor determines the browser policy when the server starts up, so you should call BrowserPolicy functions on the server in top-level application code or in Meteor.startup. BrowserPolicy functions cannot be used in client code.

用法

¥Usage

框架选项

¥Frame options

默认情况下，如果你添加 browser-policy 或 browser-policy-framing，则只有与你的应用同源的网页才允许构建你的应用。你可以使用以下函数来修改此策略。

¥By default, if you add browser-policy or browser-policy-framing, only web pages on the same origin as your app are allowed to frame your app. You can use the following functions to modify this policy.

BrowserPolicy.framing.disallow()

你的应用永远不会在框架或 iframe 内渲染。

¥Your app will never render inside a frame or iframe.

BrowserPolicy.framing.restrictToOrigin(origin)

你的应用将仅在 origin 加载的框架内渲染。你只能使用单个来源调用此函数一次，并且不能使用通配符或指定允许构建应用的多个来源。（这是 X-Frame-Options 标头的限制。）origin 的示例值包括 "http://example.com" 和 "https://foo.example.com"。Chrome 或 Safari 尚不支持 X-Frame-Options 标头的此值，并将在这些浏览器中被忽略。如果你需要 Chrome 和/或 Safari 支持，或者需要允许多个域来构建你的应用，则可以通过 BrowserPolicy.content.allowFrameAncestorsOrigin() 函数使用 frame-ancestors CSP 选项。

¥Your app will only render inside frames loaded by origin. You can only call this function once with a single origin, and cannot use wildcards or specify multiple origins that are allowed to frame your app. (This is a limitation of the X-Frame-Options header.) Example values of origin include "http://example.com" and "https://foo.example.com". This value of the X-Frame-Options header is not yet supported in Chrome or Safari and will be ignored in those browsers. If you need Chrome and/or Safari support, or need to allow multiple domains to frame your application, you can use the frame-ancestors CSP option via the BrowserPolicy.content.allowFrameAncestorsOrigin() function.

BrowserPolicy.framing.allowAll()

这会取消设置 X-Frame-Options 标头，以便你的应用可以被任何网页框架。

¥This unsets the X-Frame-Options header, so that your app can be framed by any webpage.

内容选项

¥Content options

你可以使用本节中的函数控制如何在你的网站上加载不同类型的内容。

¥You can use the functions in this section to control how different types of content can be loaded on your site.

你可以使用以下函数来调整可以在何处运行 Javascript 和 CSS 的策略：

¥You can use the following functions to adjust policies on where Javascript and CSS can be run:

BrowserPolicy.content.allowInlineScripts()

允许内联 <script> 标签、javascript: URL 和内联事件处理程序。默认策略已经允许内联脚本。

¥Allows inline <script> tags, javascript: URLs, and inline event handlers. The default policy already allows inline scripts.

BrowserPolicy.content.disallowInlineScripts()

不允许内联 Javascript。调用此函数会导致页面加载时额外往返一次以检索通常是内联脚本标记一部分的 Meteor 运行时配置。

¥Disallows inline Javascript. Calling this function results in an extra round-trip on page load to retrieve Meteor runtime configuration that is usually part of an inline script tag.

BrowserPolicy.content.allowEval()

允许使用 eval() 等函数从字符串创建 Javascript 代码。

¥Allows the creation of Javascript code from strings using function such as eval().

BrowserPolicy.content.disallowEval()

不允许 eval 和相关函数。注意：默认策略不允许 eval，但对于几乎所有 Meteor 应用，它都由 dynamic-imports 包启用

¥Disallows eval and related functions. Note: The default policy disallows eval, though for almost all Meteor apps it is enabled by the dynamic-imports package

BrowserPolicy.content.allowInlineStyles()

允许内联样式标签和样式属性。默认策略已经允许内联样式。

¥Allows inline style tags and style attributes. The default policy already allows inline styles.

BrowserPolicy.content.disallowInlineStyles()

不允许内联 CSS。

¥Disallows inline CSS.

最后，你可以配置允许各种类型的内容发出的请求的白名单。为内容类型脚本、对象、图片、媒体、字体、框架、框架祖级、样式和连接定义以下函数。

¥Finally, you can configure a whitelist of allowed requests that various types of content can make. The following functions are defined for the content types script, object, image, media, font, frame, frame-ancestors, style, and connect.

BrowserPolicy.content.allowContentTypeOrigin(origin)

允许从给定来源加载此类内容。origin 是一个字符串，可以包含一个可选方案（例如 http 或 https）、一个开头的可选通配符和一个可以作为通配符的可选端口。示例包括 example.com、https://*.example.com 和 example.com:*。你可以使用不同的来源多次调用这些函数来指定允许来源的白名单。未指定协议的来源将允许通过 HTTP 和 HTTPS 传输内容：传递 example.com 将允许来自 http://example.com 和 https://example.com 的内容。

¥Allows this type of content to be loaded from the given origin. origin is a string and can include an optional scheme (such as http or https), an optional wildcard at the beginning, and an optional port which can be a wildcard. Examples include example.com, https://*.example.com, and example.com:*. You can call these functions multiple times with different origins to specify a whitelist of allowed origins. Origins that don't specify a protocol will allow content over both HTTP and HTTPS: passing example.com will allow content from both http://example.com and https://example.com.

BrowserPolicy.content.allowContentTypeDataUrl()

允许从 data: URL 加载此类内容。

¥Allows this type of content to be loaded from a data: URL.

BrowserPolicy.content.allowContentTypeSameOrigin()

允许从与你的应用相同的来源加载此类内容。

¥Allows this type of content to be loaded from the same origin as your app.

BrowserPolicy.content.disallowContentType()

不允许在你的应用中使用此类内容。

¥Disallows this type of content on your app.

你还可以使用以下函数一次为所有这些类型的内容设置策略：

¥You can also set policies for all these types of content at once, using these functions:

• BrowserPolicy.content.allowSameOriginForAll(),

• BrowserPolicy.content.allowDataUrlForAll(),

• BrowserPolicy.content.allowOriginForAll(origin)

• BrowserPolicy.content.disallowAll()

例如，如果你希望允许所有类型的内容使用来源 https://foo.com，但又希望禁用 <object> 标签，则可以调用 BrowserPolicy.content.allowOriginForAll("https://foo.com")，然后调用 BrowserPolicy.content.disallowObject()。

¥For example, if you want to allow the origin https://foo.com for all types of content but you want to disable <object> tags, you can call BrowserPolicy.content.allowOriginForAll("https://foo.com") followed by BrowserPolicy.content.disallowObject().

使用 BrowserPolicy.content API 的其他示例：

¥Other examples of using the BrowserPolicy.content API:

• BrowserPolicy.content.disallowFont() 导致浏览器禁止所有 <font> 标签。

  ¥BrowserPolicy.content.disallowFont() causes the browser to disallow all <font> tags.

• BrowserPolicy.content.allowImageOrigin("https://example.com") 允许图片将其 src 属性指向从 https://example.com 提供的图片。

  ¥BrowserPolicy.content.allowImageOrigin("https://example.com") allows images to have their src attributes point to images served from https://example.com.

• BrowserPolicy.content.allowConnectOrigin("https://example.com") 允许 XMLHttpRequest 和 WebSocket 连接到 https://example.com。

  ¥BrowserPolicy.content.allowConnectOrigin("https://example.com") allows XMLHttpRequest and WebSocket connections to https://example.com.

• BrowserPolicy.content.allowFrameOrigin("https://example.com") 允许你的网站在框架或 iframe 中加载源 https://example.com。BrowserPolicy.framing API 允许你控制哪些站点可以框架你的站点，而 BrowserPolicy.content.allowFrameOrigin 允许你控制哪些站点可以在你的站点的框架内加载。

  ¥BrowserPolicy.content.allowFrameOrigin("https://example.com") allows your site to load the origin https://example.com in a frame or iframe. The BrowserPolicy.framing API allows you to control which sites can frame your site, while BrowserPolicy.content.allowFrameOrigin allows you to control which sites can be loaded inside frames on your site.

将 browser-policy-content 添加到你的应用还会告诉某些浏览器避免使用 X-Content-Type-Options 标头嗅探声明类型之外的内容类型（例如，将文本文件解释为 JavaScript）。要重新启用内容嗅探，你可以调用 BrowserPolicy.content.allowContentTypeSniffing()。

¥Adding browser-policy-content to your app also tells certain browsers to avoid sniffing content types away from the declared type (for example, interpreting a text file as JavaScript), using the X-Content-Type-Options header. To re-enable content sniffing, you can call BrowserPolicy.content.allowContentTypeSniffing().