Skip to main content

ASAR Integrity

ASAR 무결성 검증은 앱의 ASAR 아카이브 내용을 런타임에 검증하는 실험적인 기능이다.

버전 지원​

현재 ASAR 무결성 검사는 다음 플랫폼에서 지원된다:

  • macOS: electron>=16.0.0 버전부터
  • Windows: electron>=30.0.0 버전부터

ASAR 무결성 검사를 활성화하려면, app.asar 파일이 ASAR 무결성을 지원하는 @electron/asar npm 패키지 버전으로 생성되었는지 확인해야 한다.

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 퓨즈를 활성화하면 이 기능을 사용할 수 있다.

이 퓨즈를 활성화할 때는 일반적으로 onlyLoadAppFromAsar 퓨즈도 함께 활성화하는 것이 좋다. 그렇지 않으면 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에서 퓨즈 설정하기

Electron Forge를 사용하면 Forge 설정 파일에서 @electron-forge/plugin-fuses를 통해 앱의 퓨즈를 구성할 수 있다.

헤더 해시 제공​

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 패키지는 getRawHeader 메서드를 제공하며, 이 메서드의 결과를 해시해 이 값을 생성할 수 있다 (예: node:crypto 모듈 사용).

Windows 환경​

Windows에서 패키징할 때 Integrity 타입의 리소스 항목을 만들어야 한다. 이 리소스의 이름은 ElectronAsar로 지정한다. 리소스 값은 아래와 같은 형태의 JSON으로 인코딩된 딕셔너리여야 한다.

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

구현 예제는 Electron Packager 코드의 src/resedit.ts 파일을 참고한다.