ASAR 整合性

ASAR 整合性は、実行時にアプリの ASAR アーカイブの内容を検証する機能です。

バージョンサポート

現在、ASAR 整合性検査は以下でサポートされています。

electron>=16.0.0 での macOS
electron>=30.0.0 での Windows

[!NOTE] ASAR integrity is fully supported in Mac App Store (MAS) builds and is recommended as a best practice. While MAS-installed applications have their Resources/ folder protected by the system (owned by root), ASAR integrity still provides an additional layer of security. It is especially important if you use Electron's MAS build but distribute your app through channels other than the Mac App Store (such as direct download), since those installations won't have the system-level read-only protections.

ASAR の整合性検査を有効にするには、@electron/asar npm パッケージが ASAR 整合性をサポートするバージョンで app.asar ファイルが生成されたことを確かめる必要もあります。

サポートは asar@3.1.0 で導入されました。このパッケージはその後 @electron/asar に移行されていることに注意してください。 @electron/asar は全バージョンで ASAR 整合性をサポートしています。

動作の仕組み

各 ASAR アーカイブには JSON 文字列のヘッダが含まれています。 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 ヘッダ全体の 16 進エンコードされたハッシュを定義する必要があります。

ASAR 整合性が有効になっている場合、Electron アプリは実行時に ASAR アーカイブのヘッダのハッシュを検証します。ハッシュが存在しない場合、またはハッシュが一致しない場合は、アプリが強制終了します。

バイナリでの ASAR 整合性の有効化

Electron の ASAR 整合性チェックは現在、デフォルトで無効になっていますが、ビルド時に EnableEmbeddedAsarIntegrityValidation の Electron Fuse を切り替えることで有効化できます。

このヒューズを有効にするときは通常、onlyLoadAppFromAsar の Fuse も有効にします。さもなくば、Electron アプリのコード検索パスを介して有効性チェックをバイパスできます。

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

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

[!TIP] Electron Forge を使用すると、Forge の構成ファイル内で @electron-forge/plugin-fuses を使用してアプリの Fuse を構成できます。

ヘッダのハッシュを提供する

ASAR 整合性は、パッケージ化する時に指定したヘッダのハッシュに対して ASAR アーカイブの内容を検証します。このパッケージ化されたハッシュを提供するプロセスは、macOS と Windows で異なります。

Electron のツールを使用する

Electron Forge と Electron Packager は、asar が有効であれば、追加の構成なしでこのセットアップを自動実行します。 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 パッケージは、結果をハッシュ化 (例えば node:crypto モジュールを使用) してこの値を生成することができる getRawHeader メソッドを公開しています。

Windows

Windows 向けにパッケージ化する場合は、タイプが Integrity で名前が ElectronAsar の有効なリソースエントリを入力する必要があります。このリソースの値は、以下に示す形式の JSON でエンコードされた辞書である必要があります。

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

[!NOTE] 実装例については、Electron Packager のコードの src/resedit.ts をご参照ください。

バージョンサポート​

動作の仕組み​

バイナリでの ASAR 整合性の有効化​

ヘッダのハッシュを提供する​

Electron のツールを使用する​

他のビルドシステムを使用する​

macOS​

Windows​