第6章 Electron ASAR 完整性校验机制解析

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

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

• macOS：Electron 16.0.0 及以上版本
• Windows：Electron 30.0.0 及以上版本

注意
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 完整性
在 Electron 中，ASAR 完整性检查默认处于禁用状态。你可以通过在构建时切换 EnableEmbeddedAsarIntegrityValidation Electron 熔丝（Fuse）来启用它。
启用该熔丝时，通常还需要启用 onlyLoadAppFromAsar 熔丝。否则，ASAR 有效性的验证可能通过 Electron 应用代码搜索路径被绕过。

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

flipFuses(
  // 示例路径：/a/b/Foo.app
  pathToPackagedApp,
  {
    version: FuseVersion.V1,
    [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
    [FuseV1Options.OnlyLoadAppFromAsar]: true
  }
)

提示：使用 Electron Forge 时，可以在 Forge 配置文件中通过 @electron-forge/plugin-fuses 来配置应用的 fuses。 提供 header hash ASAR integrity 会将 ASAR 归档的内容与你打包时提供的 header hash 进行比对校验。macOS 和 Windows 提供该打包 hash 的方式有所不同。 使用 Electron 官方工具 只要启用了 asar，Electron Forge 和 Electron Packager 就会自动完成相关配置，无需额外设置。支持 ASAR integrity 的最低版本要求如下： @electron/packager@18.3.1 @electron/forge@7.4.0 使用其他构建系统 macOS 为 macOS 打包时，你需要在打包后应用的 Info.plist 中填入有效的 ElectronAsarIntegrity 字典块，示例如下。 Info.plistElectronAsarIntegrity

Resources/app.asar

algorithm
SHA256
hash
9d1f61ea03c4bb62b4416387a521101b81151da0cfbe18c9f8c8b818c5cebfac


目前有效的 algorithm 取值仅支持 SHA256。hash 是使用指定算法对 ASAR header 计算得到的哈希值。@electron/asar 包提供了 getRawHeader 方法，其返回结果经哈希计算后即可生成该值（例如使用 node:crypto 模块）。 Windows 为 Windows 打包时，你需要填入一个类型为 Integrity、名称为 ElectronAsar 的有效资源项。该资源的值应为如下格式的 JSON 字典： [
{
"file": "resources\\app.asar",
"alg": "sha256",
"value": "9d1f61ea03c4bb62b4416387a521101b81151da0cfbe18c9f8c8b818c5cebfac"
}
]
注意：具体实现示例可参考 Electron Packager 源码中的 src/resedit.ts。