Skip to main content

ASAR 集成

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

¥ASAR integrity is an experimental 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

    ¥macOS as of electron>=16.0.0

  • Windows 自 electron>=30.0.0 年起

    ¥Windows as of electron>=30.0.0

为了启用 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 contain 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

目前，ASAR 完整性检查在 Electron 中默认处于禁用状态，可以通过切换 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
  }
)
Electron Forge 中的保险丝

使用 Electron Forge，你可以在 Forge 配置文件中使用 @electron-forge/plugin-fuses 配置应用的熔断器。

¥With Electron Forge, you can configure your app's fuses with @electron-forge/plugin-fuses in your Forge configuration file.

提供标头哈希​

¥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

Electron Forge 和 Electron Packager 自动为你完成此设置，无需额外配置。ASAR 完整性所需的最低版本是：

¥Electron Forge and Electron Packager do this setup automatically for you with no additional configuration. 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 的有效 resource 条目。该资源的值应该是 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"
  }
]
信息

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

¥For an implementation example, see src/resedit.ts in the Electron Packager code.