ASAR 完整性

ASAR 完整性是一项安全功能，用于在运行时验证您的应用的 ASAR 存档 内容。

版本支持¶

目前，ASAR 完整性检查支持以下平台：

• 自 electron>=16.0.0 起支持 macOS
• 自 electron>=30.0.0 起支持 Windows

[!NOTE] ASAR 完整性在 Mac App Store (MAS) 构建中完全受支持，并推荐 作为最佳实践。虽然通过 MAS 安装的应用程序的 Resources/ 文件夹 受系统保护（由 root 拥有），但 ASAR 完整性仍可提供额外的 安全层。如果您使用 Electron 的 MAS 构建，但 通过 Mac App Store 以外的渠道（例如直接 下载）分发您的应用，这一点尤为重要，因为这些安装方式不会具有系统级只读保护。

为了启用 ASAR 完整性检查，您还需要确保您的 app.asar 文件 是由支持 ASAR 完整性的 @electron/asar npm 包版本生成的。

该支持在 asar@3.1.0 中引入。请注意，该包此后已迁移到 @electron/asar。 所有版本的 @electron/asar 都支持 ASAR 完整性。

工作原理¶

每个 ASAR 存档都包含一个 JSON 字符串头部。头部格式包含一个 integrity 对象， 其中包含整个存档的十六进制编码哈希，以及每个 blockSize 字节块的十六进制编码哈希数组。

{
  "algorithm": "SHA256",
  "hash": "...",
  "blockSize": 1024,
  "blocks": ["...", "..."]
}

另外，在打包 Electron 应用时，您需要定义整个 ASAR 头部的十六进制编码哈希。

启用 ASAR 完整性后，您的 Electron 应用将在运行时验证 ASAR 存档的头部哈希。 如果不存在哈希或哈希不匹配，应用将强制终止。

在二进制文件中启用 ASAR 完整性¶

ASAR 完整性检查目前在 Electron 中默认禁用，可以在 构建时通过切换 EnableEmbeddedAsarIntegrityValidation Electron 熔丝 来启用。

启用此熔丝时，您通常也希望启用 onlyLoadAppFromAsar 熔丝。 否则，可以通过 Electron 应用代码搜索路径绕过有效性检查。

```js @ts-nocheck const { flipFuses, FuseVersion, FuseV1Options } = require('@electron/fuses')

flipFuses( // E.g. /a/b/Foo.app pathToPackagedApp, { version: FuseVersion.V1, [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true, [FuseV1Options.OnlyLoadAppFromAsar]: true } )

> [!TIP]
> 使用 Electron Forge 时，您可以在 Forge 配置文件中通过
> [@electron-forge/plugin-fuses](https://www.electronforge.io/config/plugins/fuses)
> 配置应用的熔丝。

## 提供头部哈希 {#providing-the-header-hash}

ASAR 完整性会根据您在打包时提供的头部哈希来验证
ASAR 存档的内容。提供此打包哈希的过程在 macOS 和 Windows 上有所不同。

### 使用 Electron 工具 {#using-electron-tooling}

Electron Forge 和 Electron Packager 会在启用 `asar` 时自动为您完成此设置，无需额外
配置。ASAR 完整性所需的最低版本为：

* `@electron/packager@18.3.1`
* `@electron/forge@7.4.0`

### 使用其他构建系统 {#using-other-build-systems}

#### macOS {#macos}

为 macOS 打包时，您必须在已打包应用的 `Info.plist` 中填充有效的 `ElectronAsarIntegrity` 字典块。
下面包含一个示例。

```xml title='Info.plist'
<key>ElectronAsarIntegrity</key>
<dict>
  <key>Resources/app.asar</key>
  <dict>
    <key>algorithm</key>
    <string>SHA256</string>
    <key>hash</key>
    <string>9d1f61ea03c4bb62b4416387a521101b81151da0cfbe18c9f8c8b818c5cebfac</string>
  </dict>
</dict>

当前有效的 algorithm 值仅为 SHA256。hash 是使用给定算法对 ASAR 头部进行哈希得到的哈希值。 @electron/asar 包暴露了一个 getRawHeader 方法，其结果可以再进行哈希以生成此值 （例如使用 node:crypto 模块）。

Windows¶

为 Windows 打包时，您必须填充一个类型为 Integrity、名称为 ElectronAsar 的有效 资源 条目。此资源的值应为如下形式的 JSON 编码字典：

[
  {
    "file": "resources\\app.asar",
    "alg": "sha256",
    "value": "9d1f61ea03c4bb62b4416387a521101b81151da0cfbe18c9f8c8b818c5cebfac"
  }
]

[!NOTE] 有关实现示例，请参阅 Electron Packager 代码中的 src/resedit.ts。