ASAR integrity is a runtime security feature
ASAR integrity validates the contents of your app's ASAR archives at runtime, ensuring the validity of packaged application files.
Electron · Tutorial · all subjects
security/asar-integrity
17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
ASAR integrity platform and version support
ASAR integrity checking is supported on macOS as of Electron 16.0.0 and on Windows as of Electron 30.0.0.
ASAR integrity with Mac App Store builds
ASAR integrity is fully supported in Mac App Store (MAS) builds and is recommended as a best practice. It provides an additional layer of security beyond the system-level read-only protections. This 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 system-level protections.
ASAR package version required for integrity support
To enable ASAR integrity checking, your app.asar file must be generated by a version of the @electron/asar npm package that supports ASAR integrity. Support was introduced in asar@3.1.0, and the package has since migrated to @electron/asar. All versions of @electron/asar support ASAR integrity.
ASAR integrity header format
Each ASAR archive contains a JSON string header with an integrity object that contains: algorithm (SHA256), hash (hex encoded hash of the entire archive), blockSize (bytes per block), and blocks (array of hex encoded hashes for each block).
ASAR integrity validation process
When ASAR integrity is enabled, the Electron app verifies the header hash of the ASAR archive at runtime. If no hash is present or if there is a mismatch in the hashes, the app will forcefully terminate.
ASAR integrity is disabled by default in Electron
ASAR integrity checking is currently disabled by default in Electron and can be enabled at build time by toggling the EnableEmbeddedAsarIntegrityValidation Electron fuse.
Enable ASAR integrity using fuses
To enable ASAR integrity checking, use the @electron/fuses package to set the EnableEmbeddedAsarIntegrityValidation fuse to true. When enabling this fuse, you should also enable the OnlyLoadAppFromAsar fuse to prevent bypassing the validity checking via the Electron app code search path.
ASAR integrity fuse configuration example
Example code using @electron/fuses to enable ASAR integrity: ```js 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 ASAR integrity configuration
With Electron Forge, you can configure your app's fuses using @electron-forge/plugin-fuses in your Forge configuration file to enable ASAR integrity.
Automatic ASAR integrity setup with Electron tooling
Electron Forge and Electron Packager automatically set up ASAR integrity for you with no additional configuration whenever asar is enabled. Minimum required versions are @electron/packager@18.3.1 and @electron/forge@7.4.0.
ASAR integrity header hash in macOS Info.plist
When packaging for macOS using other build systems, populate a valid ElectronAsarIntegrity dictionary block in your packaged app's Info.plist with the algorithm (SHA256 only) and hex-encoded hash of the ASAR header. The @electron/asar package exposes a getRawHeader method whose result can be hashed to generate this value.
macOS Info.plist ASAR integrity entry example
Example Info.plist ASAR integrity entry for macOS: ```xml <key>ElectronAsarIntegrity</key> <dict> <key>Resources/app.asar</key> <dict> <key>algorithm</key> <string>SHA256</string> <key>hash</key> <string>9d1f61ea03c4bb62b4416387a521101b81151da0cfbe18c9f8c8b818c5cebfac</string> </dict> </dict> ```
ASAR integrity for Windows using resource entry
When packaging for Windows using other build systems, populate a valid resource entry of type Integrity and name ElectronAsar. The value should be a JSON encoded dictionary with file path, algorithm (sha256), and hex-encoded hash value.
Windows ASAR integrity resource entry example
Example Windows resource entry for ASAR integrity: ```json [ { "file": "resources\\app.asar", "alg": "sha256", "value": "9d1f61ea03c4bb62b4416387a521101b81151da0cfbe18c9f8c8b818c5cebfac" } ] ```
embeddedAsarIntegrityValidation fuse - validate app.asar content
The embeddedAsarIntegrityValidation fuse toggles validation of the app.asar file content when loaded. Default is Disabled. Available on macOS and Windows. It is designed to have minimal performance impact but may marginally slow down file reads from inside the app.asar archive. Most apps can safely enable this fuse.
onlyLoadAppFromAsar fuse - restrict app loading to asar only
The onlyLoadAppFromAsar fuse changes the search system for app code location. Default is Disabled. By default, Electron searches in order: app.asar, app, default_app.asar. When enabled, Electron only searches for app.asar. When combined with embeddedAsarIntegrityValidation fuse, this ensures impossible to load non-validated code.