Skip to main content

ASAR 集成

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

🌐 ASAR integrity is a security feature that validates the contents of your app's ASAR archives at runtime.

版本支持​

🌐 Version support

目前，ASAR 完整性检查支持：

🌐 Currently, ASAR integrity checking is supported on:

  • 截至 electron>=16.0.0 的 macOS
  • 截至 electron>=30.0.0 的 Windows
note

ASAR 完整性在 Mac 应用商店 (MAS) 构建中完全支持，并且被推荐作为最佳实践。虽然通过 MAS 安装的应用其 Resources/ 文件夹由系统保护（属于 root 所有），ASAR 完整性仍提供额外的安全层。如果你使用 Electron 的 MAS 构建但通过 Mac 应用商店以外的渠道分发应用（例如直接下载），这一点尤为重要，因为那些安装不会具备系统级的只读保护。

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

🌐 In order to enable ASAR integrity checking, you also need to ensure that your app.asar file was generated by a version of the @electron/asar npm package that supports ASAR integrity.

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

🌐 Support was introduced in asar@3.1.0. Note that this package has since migrated over to @electron/asar. All versions of @electron/asar support ASAR integrity.

工作原理​

🌐 How it works

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

🌐 Each ASAR archive contains a JSON string header. The header format includes an integrity object that contains a hex encoded hash of the entire archive as well as an array of hex encoded hashes for each block of blockSize bytes.

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

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

🌐 Separately, you need to define a hex encoded hash of the entire ASAR header when packaging your Electron app.

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

🌐 When ASAR integrity is enabled, your Electron app will verify the header hash of the ASAR archive on runtime. If no hash is present or if there is a mismatch in the hashes, the app will forcefully terminate.

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

🌐 Enabling ASAR integrity in the binary

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

🌐 ASAR integrity checking is currently disabled by default in Electron and can be enabled on build time by toggling the EnableEmbeddedAsarIntegrityValidation Electron fuse.

启用此保险丝时，通常也需要启用 onlyLoadAppFromAsar 保险丝。否则，通过 Electron 应用的代码搜索路径可以绕过有效性检查。

🌐 When enabling this fuse, you typically also want to enable the onlyLoadAppFromAsar fuse. Otherwise, the validity checking can be bypassed via the Electron app code search path.

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 配置你的应用的保险丝。

提供标头哈希​

🌐 Providing the header hash

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

🌐 ASAR integrity validates the contents of the ASAR archive against the header hash that you provide on package time. The process of providing this packaged hash is different for macOS and Windows.

使用 Electron 工具​

🌐 Using Electron tooling

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

🌐 Electron Forge and Electron Packager do this setup automatically for you with no additional configuration whenever asar is enabled. The minimum required versions for ASAR integrity are:

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

使用其他构建系统​

🌐 Using other build systems

macOS​

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

🌐 When packaging for macOS, you must populate a valid ElectronAsarIntegrity dictionary block in your packaged app's Info.plist. An example is included below.

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 模块）。

🌐 Valid algorithm values are currently SHA256 only. The hash is a hash of the ASAR header using the given algorithm. The @electron/asar package exposes a getRawHeader method whose result can then be hashed to generate this value (e.g. using the node:crypto module).

Windows​

在为 Windows 打包时，你必须填充一个有效的 Integrity 类型且名称为 ElectronAsar 的 资源 条目。该资源的值应为 JSON 编码的字典，格式如下所示：

🌐 When packaging for Windows, you must populate a valid resource entry of type Integrity and name ElectronAsar. The value of this resource should be a JSON encoded dictionary in the form included below:

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

有关实现示例，请参见 src/resedit.ts 在 Electron Packager 代码中。