安全

清理用户输入

¥Sanitizing User Input

对于 ion-alert 等组件，开发者可以允许自定义或用户提供的内容。此内容可以是纯文本或 HTML，应被视为不可信。与任何不受信任的输入一样，在对其进行任何其他操作之前对其进行清理非常重要。特别是，在未经清理的情况下使用 innerHTML 等内容为不良行为者提供了输入恶意内容并可能启动 跨站脚本攻击 (XSS) 的攻击媒介。

¥For components such as ion-alert developers can allow for custom or user-provided content. This content can be plain text or HTML and should be considered untrusted. As with any untrusted input, it is important to sanitize it before doing anything else with it. In particular, using things like innerHTML without sanitization provides an attack vector for bad actors to input malicious content and potentially launch a Cross Site Scripting attack (XSS).

Ionic 内置了对其提供的组件的基本清理实现。然而，这并不是一个全面的解决方案。开发者有责任确保所有传递的数据都经过清理。不同的框架有不同的解决方案来清理用户输入，因此开发者应该熟悉其特定框架提供的功能。

¥Ionic comes built in with a basic sanitization implementation for the components it provides. However, it is not a comprehensive solution. It is up to the developer to make sure all data that is passed is sanitized. Different frameworks have different solutions for sanitizing user input, so developers should familiarize themselves with what their specific framework offers.

对于不使用框架的开发者，或者框架不提供所需清理方法的开发者，我们建议使用 sanitize-html。该包提供了一个简单的 HTML 清理程序，允许开发者指定他们希望在应用中允许的确切标签和属性。

¥For developers who are not using a framework, or for developers whose framework does not provide the sanitization methods they need, we recommend using sanitize-html. This package provides a simple HTML sanitizer that allows the developer to specify the exact tags and attributes that they want to allow in their application.

Angular

Angular 内置了 DomSanitizer 类。这有助于确保值在 DOM 中安全使用，从而防止 XSS 问题。默认情况下，Angular 会标记它认为不安全的任何值。例如，以下链接将被 Angular 标记为不安全，因为它会尝试执行一些 JavaScript。

¥Angular comes built in with the DomSanitizer class. This helps prevent XSS issues by ensuring that values are safe to be used in the DOM. By default, Angular will mark any values it deems unsafe. For example, the following link would be marked as unsafe by Angular because it would attempt to execute some JavaScript.

public myUrl: string = 'javascript:alert("oh no!")';

...

<a [href]="myUrl">Click Me!</a>

要了解有关 Angular 提供的内置保护的更多信息，请参阅 角度安全指南。

¥To learn more about the built-in protections that Angular provides, see the Angular Security Guide.

React

React DOM 在渲染 JSX 中嵌入的值之前将其转换为字符串，对它们进行转义。例如，以下内容是安全的，因为 name 在渲染之前会转换为字符串：

¥React DOM escapes values embedded in JSX before rendering them by converting them to strings. For example, the following would be safe as name is converted to a string before being rendered:

const name = values.name;
const element = <h1>Hello, {name}!</h1>;

但是，这并不能阻止某人将 JavaScript 注入到锚元素的 href 属性等位置。以下内容是不安全的，可能会导致 XSS 攻击发生：

¥However, this does not stop someone from injecting JavaScript into places such as the href attribute of an anchor element. The following is unsafe and can potentially allow an XSS attack to occur:

const userInput = 'javascript:alert("Oh no!")';
const element = <a href={userInput}>Click Me!</a>;

如果开发者需要实现更全面的清理，他们可以使用 sanitize-html 包。

¥If the developer needs to achieve more comprehensive sanitization, they can use the sanitize-html package.

要了解有关 React 和 JSX 提供的内置保护的更多信息，请参阅 React JSX 文档。

¥To learn more about the built-in protections that React and JSX provide, see the React JSX Documentation.

Vue

Vue 不提供任何类型的内置清理方法。建议开发者使用 sanitize-html 之类的包。

¥Vue does not provide any type of sanitizing methods built in. It is recommended that developers use a package such as sanitize-html.

要了解有关绑定到 v-html 等指令的安全建议的更多信息，请参阅 Vue 语法指南。

¥To learn more about the security recommendations for binding to directives such as v-html, see the Vue Syntax Guide.

通过 innerHTML 启用自定义 HTML 解析

¥Enabling Custom HTML Parsing via innerHTML

ion-alert、ion-infinite-scroll-content、ion-loading、ion-refresher-content 和 ion-toast 可以接受自定义 HTML 作为某些属性的字符串。这些字符串使用 innerHTML 添加到 DOM，并且必须由开发者正确清理。默认情况下禁用此行为，这意味着传递到受影响组件的值将始终被解释为纯文本。开发者可以通过在 IonicConfig 中设置 innerHTMLTemplatesEnabled: true 来启用此自定义 HTML 行为。

¥ion-alert, ion-infinite-scroll-content, ion-loading, ion-refresher-content, and ion-toast can accept custom HTML as strings for certain properties. These strings are added to the DOM using innerHTML and must be properly sanitized by the developer. This behavior is disabled by default which means values passed to the affected components will always be interpreted as plaintext. Developers can enable this custom HTML behavior by setting innerHTMLTemplatesEnabled: true in the IonicConfig.

从内置删除系统中弹出

¥Ejecting from the built-in sanitizer

对于希望向 ion-toast 等组件添加复杂 HTML 的开发者，他们需要从 Ionic Framework 内置的清理程序中弹出。开发者可以在整个应用中禁用消毒剂，也可以根据具体情况绕过它。

¥For developers who wish to add complex HTML to components such as ion-toast, they will need to eject from the sanitizer that is built into Ionic Framework. Developers can either disable the sanitizer across their entire app or bypass it on a case-by-case basis.

注意

绕过清理功能可能会使你的应用容易受到 XSS 攻击 的攻击。禁用消毒剂时请格外小心。

¥Bypassing sanitization functionality can make your application vulnerable to XSS attacks. Please exercise extreme caution when disabling the sanitizer.

通过配置禁用删除系统

¥Disabling the sanitizer via config

Ionic Framework 提供了一个名为 sanitizerEnabled 的应用配置选项，默认设置为 true。将此值设置为 false 以全局禁用 Ionic Framework 的内置清理程序。请注意，这不会禁用其他框架（例如 Angular）提供的任何清理功能。

¥Ionic Framework provides an application config option called sanitizerEnabled that is set to true by default. Set this value to false to globally disable Ionic Framework's built in sanitizer. Please note that this does not disable any sanitizing functionality provided by other frameworks such as Angular.

根据具体情况绕过删除系统

¥Bypassing the sanitizer on a case-by-case basis

在某些情况下，开发者还可以选择从消毒器中弹出。Ionic Framework 提供了 IonicSafeString 类，允许开发者做到这一点。

¥Developers can also choose to eject from the sanitizer in certain scenarios. Ionic Framework provides the IonicSafeString class that allows developers to do just that.

注意

为了绕过清理程序并在相关 Ionic 组件中使用未经清理的自定义 HTML，必须在 Ionic 配置中将 innerHTMLTemplatesEnabled 设置为 true。

¥In order to bypass the sanitizer and use unsanitized custom HTML in the relevant Ionic components, innerHTMLTemplatesEnabled must be set to true in the Ionic config.

如果 innerHTMLTemplatesEnabled 设置为 false，则不应使用 IonicSafeString。

¥IonicSafeString should not be used if innerHTMLTemplatesEnabled is set to false.

请参阅 启用自定义 HTML 解析 了解更多信息。

¥See Enabling Custom HTML Parsing for more information.

用法

¥Usage

Angular

import { IonicSafeString, ToastController } from '@ionic/angular';



...

constructor(private toastController: ToastController) {}

async presentToast() {
  const toast = await this.toastController.create({
      message: new IonicSafeString('<ion-button>Hello!</ion-button>'),
      duration: 2000
  });
  toast.present();
}

Angular (Standalone)

import { IonicSafeString, ToastController } from '@ionic/angular/standalone';



...

constructor(private toastController: ToastController) {}

async presentToast() {
  const toast = await this.toastController.create({
      message: new IonicSafeString('<ion-button>Hello!</ion-button>'),
      duration: 2000
  });
  toast.present();
}

JavaScript

import { IonicSafeString } from '@ionic/core';



...

const async presentToast = () => {
  const toast = document.createElement('ion-toast');
  toast.message = new IonicSafeString('<ion-button>Hello!</ion-button>');
  toast.duration = 2000;

  document.body.appendChild(toast);
  return toast.present();
}

React

import React, { useState } from 'react';


import { Animation, IonButton, IonContent, IonicSafeString, IonToast } from '@ionic/react';



export const ToastExample: React.FC = () => {
  const [showToast, setShowToast] = useState(false);

  return (
    <IonContent>
      <IonButton onClick={() => setShowToast(true)} expand="block">Show Toast</IonButton>
      <IonToast
        isOpen={showToast}
        onDidDismiss={() => setShowToast(false)}
        message={new IonicSafeString('<ion-button>Hello!</ion-button>')}
        duration={2000}
      />
    </IonContent>
  )
};

内容安全策略 (CSP)

¥Content Security Policies (CSP)

内容安全策略 (CSP) 是一种安全机制，有助于保护 Web 应用免受某些类型的攻击，例如跨站点脚本 (XSS) 和数据注入。它是通过 HTTP 标头实现的，该标头指示浏览器允许在网页上加载和执行哪些内容源，例如脚本、样式表和图片。

¥A Content Security Policy (CSP) is a security mechanism that helps protect web applications against certain types of attacks, such as cross-site scripting (XSS) and data injection. It is implemented through an HTTP header that instructs the browser on which sources of content, such as scripts, stylesheets, and images, are allowed to be loaded and executed on a web page.

CSP 的主要目的是减轻与代码注入攻击相关的风险。通过定义策略，Web 开发者可以指定浏览器应允许从哪些域或源加载和执行各种类型的内容。这有效地限制了恶意脚本或未经授权的内容可能造成的潜在损害。

¥The main purpose of a CSP is to mitigate the risks associated with code injection attacks. By defining a policy, web developers can specify from which domains or sources the browser should allow the loading and execution of various types of content. This effectively limits the potential damage that can be caused by malicious scripts or unauthorized content.

启用 CSP

¥Enabling CSPs

开发者可以通过在脚本和样式标签上设置包含策略详细信息和预期随机数值的元标签来将 CSP 分配给他们的应用。

¥Developers can assign a CSP to their application by setting a meta tag with the policy details and the expected nonce value on script and style tags.

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' 'nonce-randomNonceGoesHere'; style-src 'self' 'nonce-randomNonceGoesHere';"
/>

Ionic 和 CSP

¥Ionic and CSP

Ionic Framework 提供了一个函数来帮助开发者设置构建 Web 组件样式表时使用的 nonce 值。应在加载任何 Ionic 组件之前调用此函数。这是将随机数值传递给 Web 组件所必需的，以便它们可以在 CSP 环境中使用。

¥Ionic Framework provides a function to help developers set the nonce value used when constructing the web component stylesheets. This function should be called before any Ionic components are loaded. This is required to pass the nonce value to the web components so that they can be used in a CSP environment.

import { setNonce } from '@ionic/core/loader';



setNonce('randomNonceGoesHere');

提示

在 Angular 中，可以在应用引导之前在 main.ts 文件中调用它。

¥In Angular this can be called in the main.ts file, before the application is bootstrapped.

有关如何将 CSP 与 Stencil Web 组件结合使用的更多信息，请参阅 模板文档。

¥For more information on how to use CSPs with Stencil web components, see the Stencil documentation.

Angular

从 Angular 16 开始，Angular 提供了两个设置 nonce 值的选项。

¥Starting in Angular 16, Angular provides two options for setting the nonce value.

1. 将根应用元素上的 ngCspNonce 属性设置为 <app ngCspNonce="randomNonceGoesHere"></app>。如果你有权访问服务器端模板，并且可以在构建响应时将随机数添加到标头和 index.html，请使用此方法。

   ¥Set the ngCspNonce attribute on the root application element as <app ngCspNonce="randomNonceGoesHere"></app>. Use this approach if you have access to server-side templating that can add the nonce both to the header and the index.html when constructing the response.

2. 使用 CSP_NONCE 注入令牌提供随机数。如果你可以在运行时访问随机数并且希望能够缓存 index.html，请使用此方法。

   ¥Provide the nonce using the CSP_NONCE injection token. Use this approach if you have access to the nonce at runtime and you want to be able to cache the index.html.

提示

如果提供 CSP_NONCE 注入令牌，请在 AppModule 中（对于模块项目）或 bootstrapApplication 中（对于独立项目）设置提供程序。

¥If providing the CSP_NONCE injection token, set the provider in your AppModule for module projects or within the bootstrapApplication for standalone projects.

有关如何将 CSP 与 Angular 结合使用的更多信息，请参阅 角度文档。

¥For more information on how to use CSPs with Angular, see the Angular documentation.