メインコンテンツへ飛ぶ

ASAR 整合性

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

バージョンサポート​

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

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

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

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

動作の仕組み​

各 ASAR アーカイブには JSON 文字列のヘッダが含まれています。 ヘッダのフォーマットには、アーカイブ全体を 16 進数で符号化したハッシュと、blockSize バイトの各ブロックの 16 進数でエンコードされたハッシュの配列を含む integrity オブジェクトが含まれています。

{
  "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
  }
)
Electron Forge での Fuse

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

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

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

Electron のツールを使用する​

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 パッケージは、結果をハッシュ化 (例えば node:crypto モジュールを使用) してこの値を生成することができる getRawHeader メソッドを公開しています。

Windows​

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

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

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