跳转到主内容

ASAR完整性

ASAR 完整性是一种安全特性，其会在运行时验证你应用的 ASAR 归档文件的内容。

版本支持​

目前，以下版本支持 ASAR 完整性检查：

  • 对于 macOS：electron>=16.0.0
  • 对于 Windows：electron>=30.0.0
note

ASAR 完整性在 Mac 应用商店（MAS）构建版本里得到完全支持并被推荐为最佳实践。 虽然通过应用商店安装的应用程序的 Resources/ 文件夹已经受到系统保护（拥有者为 root），但是 ASAR 完整性还会在此之上提供额外一层安全层。 如果你使用 Electron 的 MAS 构建版本，但是通过 Mac 应用商店以外的渠道分发应用（比如直接下载），这一特性就会显得尤其重要，因为以这种方式安装的应用不会有系统级的只读保护。

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

该特性在 asar@3.1.0 中得到支持。 需注意该 npm 包已经迁移到 @electron/asar。 @electron/asar 的所有版本都支持 ASAR 完整性。

工作原理​

每个 ASAR 归档文件都包含一个 JSON 字符串头部。 头部格式包含了一个 integrity 对象，里面包含了十六进制编码的整个归档文件的哈希值，以及由每个长度为 blockSize 字节的数据块的十六进制编码哈希值组成的数组。

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

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

启用 ASAR 完整性后，您的 Electron 应用将在运行时验证 ASAR 归档文件的头部哈希。 如果没有提供哈希值或者哈希值不一致，应用将会被强制终止运行。

在二进制文件内启用 ASAR 完整性​

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

启用该 Fuse 时，你通常也想要启用 onlyLoadAppFromAsar Fuse。 否则可以通过 Electron 应用代码搜索路径绕过有效性验证。

const { flipFuses, FuseVersion, FuseV1Options } = require('@electron/fuses')

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

使用 Electron Forge，你可以在 Forge 配置文件里使用 @electron-forge/plugin-fuses 配置你的应用的 Fuse。

提供头部哈希值​

ASAR 完整性会用你打包时提供的头部哈希值验证 ASAR 归档文件的内容。 提供这个打包哈希值的过程在 macOS 和 Windows 上有所不同。

使用 Electron 工具​

asar 启用后，Electron Forge 和 Electron Packager 会自动为你完成这一设置工作，无需额外配置。 ASAR 完整性的最低版本要求是：

  • @electron/packager@18.3.1
  • @electron/forge@7.4.0

使用其他构建系统​

macOS​

在为 macOS 打包时，你必须要在打包应用的 Info.plist 中填充有效的 ElectronAsarIntegrity 字典块。 下面是一个例子。

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 。