이 문서에서는 키가 손실되거나 해킹당한 경우 개발자가 따라야 하는 단계와 키 순환이 필요한 시기를 비롯하여 격리된 웹 앱 (IWA)의 키 순환 프로세스에 관한 필수 정보를 제공합니다.
IWA의 키 순환
키 순환은 유출 또는 손실 시 IWA에 서명하는 데 사용되는 비공개 키를 대체할 수 있는 메커니즘입니다. 이 프로세스를 통해 앱이 계속 작동하고 안정적인 번들 ID와 출처가 유지되어 앱의 배포 및 업데이트가 지속적으로 이루어집니다.
키 순환 프로세스에는 관리자 또는 사용자 변경사항이 필요하지 않으며 올바르게 실행되면 관리자나 사용자가 이를 인식하지 못합니다. 초기 허용 목록 작성 프로세스 중에 설정된 신뢰할 수 있는 연락 채널은 키 순환을 사용 설정하는 데 필수적입니다.
키 순환의 필요성
키 순환은 다음 두 가지 기본 시나리오에서 엄격히 필요합니다.
- 키 유출 또는 해킹: 비공개 서명 키가 해킹당했거나 유출될 가능성이 있는 경우 애플리케이션을 보호하기 위해 즉시 키 순환 프로세스를 시작해야 합니다. 유출된 키는 개발자를 사칭하고 앱 사용자에게 피해를 주며 회사의 평판을 위험에 빠뜨리는 데 사용될 수 있습니다.
- 키 손실: 비공개 서명 키에 액세스할 수 없으며 새 업데이트에 서명할 수 없는 경우 애플리케이션을 배포하는 기능을 다시 설정하려면 키 순환이 필요합니다.
개발자 요구사항
키 순환을 시작하기 전에 다음 기준을 충족해야 합니다.
- 허용 목록에 추가된 앱: 허용 목록에 추가된 앱만 키 순환의 대상이 될 수 있습니다.
- 신뢰할 수 있는 이메일: 허용 목록 작성 프로세스 중에 제공된 신뢰할 수 있는 이메일 주소를 사용하여 키 순환을 요청해야 합니다.
호스팅된 앱 다시 서명 및 새 버전 출시
키를 순환한 후 유효한 키로 서명되지 않은 설치된 모든 앱 인스턴스가 차단됩니다. 사용자에게 중단을 방지하려면 새 키 (또는 두 키 모두)로 서명된 앱을 제공해야 합니다. 번들 다시 서명의 기술 세부정보는 섹션 여러 키로 번들에 서명하는 방법을 참고하세요. 특정 상황에 따라 다음과 같은 여러 시나리오가 있습니다.
시나리오 A: 키가 손실되지 않음 (예: 사전 순환 또는 유출)
두 키 (이전 키와 새 키) 모두로 앱에 서명하고 다음 중 한 가지 방법으로 사용자에게 제공해야 합니다.
- 새 앱 버전 출시 (업데이트 매니페스트에 새 버전 추가) 또는
- 두 키 모두로 서명되도록 호스팅된
.swbn파일 (업데이트 매니페스트에 연결됨) 업데이트. CLI 도구를 사용하면 기존swbn번들에 서명을 하나 더 추가할 수 있습니다.
사용자가 변경사항을 인식하지 못하도록 Google에서 키 순환을 처리하기 전에 이 작업을 실행해야 합니다.
시나리오 B: 키가 손실됨
이 경우 손실된 키로 앱에 서명할 수 없으므로 더 복잡합니다. 키 순환을 요청하고 Google 담당자에게 추가 단계를 문의하세요. 다음 안내에 따라 호스팅된 번들에 새 서명을 추가하라는 메시지가 표시될 수 있습니다.
키 순환 프로세스
키 순환 프로세스에는 다음 단계가 포함됩니다.
| 단계 | 작업 | 세부정보 | Responsible |
|---|---|---|---|
| 1 | 키 순환 요청 | 개발자/파트너가 허용 목록 작성 프로세스에서 제공된 신뢰할 수 있는 이메일 을 통해 Google 담당자 (파트너 엔지니어링 또는 기타 담당자)에게 연락하여 이유를 설명하는 키 순환 안내를 요청합니다. 키가 해킹당한 경우 프로세스 속도를 높이기 위해 이전 키와 새 키로 서명된 번들이 포함된 업데이트 매니페스트를 첨부하는 것이 좋습니다. | 개발자 / 파트너 |
| 2 | 요청자에게 응답 | Google 담당자가 요청자에게 추가 안내 및 질문을 제공합니다. 이 단계에는 몇 번의 주고받기가 포함될 수 있습니다. | Google 담당자 |
| 3 | 데이터 제공 | 개발자/파트너가 안내를 따릅니다. 여기에는 다음이 포함될 수 있습니다.
|
개발자 / 파트너 |
| 4 | 요청 처리 및 의견 제공 |
Google에서 키 순환 요청을 검토하고 영업일 기준 1일 이내에 승인 또는 거부하거나 추가 질문이 있는 경우 개발자에게 연락합니다. 승인되면 Google에서 키를 순환하고 의견을 제공합니다. | Google 담당자 |
업데이트 채널 및 버전 고정
관리자는 클라이언트 기기에서 앱 버전을 관리할 수 있는 맞춤 업데이트 채널 또는 버전 고정을 사용하는 경우가 있습니다. 키 순환 후 유효하지 않은 키로 설치된 모든 앱이 유효하지 않게 되고 차단됩니다. 이를 방지하려면 키 순환 전에 update_manifest.json에 제공된 링크에서 호스팅되는 이전 버전의 앱도 업데이트하고 두 개의 서명으로 서명해야 합니다. 이전 키가 손실되고 앱에 두 개의 키로 서명할 수 없는 경우 즉시 Google 담당자에게 알리세요. Google에서는 사용자의 워크플로를 방해하지 않고 앱을 업데이트할 수 있도록 상황을 완화하기 위해 개발자와 협력할 것입니다.
여러 키로 번들에 서명하는 방법
이 섹션에서는 CLI 도구 또는 Webpack/Rollup/Vite 플러그인 구성을 통해 하나 또는 두 개의 키로 웹 번들에 서명하는 방법을 설명합니다. CLI 도구를 사용하면 기존 swbn 번들에 서명을 하나 더 추가할 수도 있습니다. 이는 키가 손실된 경우 또는 이전 호스팅된 번들을 업데이트하는 데 유용할 수 있습니다.
CLI 도구
먼저 npm으로 wbn-sign 패키지가 설치되어 있는지 확인합니다.
$ npm i wbn-sign
현재 폴더에서만 패키지를 설치하는 대신 전역으로 설치하려면 -g를 추가합니다.
하나의 키로 서명
$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem
두 개의 키로 서명
$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>
앱의 초기 버전에 서명하는 데 사용된 첫 번째 키가 old_key인 경우 --web-bundle-id <id> 인수를 건너뛸 수 있습니다. 그러면 번들 ID가 키에서 파생됩니다. wbn-sign info signed.swbn 명령어를 사용하여 번들 ID를 확인할 수 있습니다.
기존 번들에 서명 추가
$ wbn-sign add-signature signed.swbn key3.pem --in-place
번들을 재정의하지 않고 새 이중 서명된 번들을 만들려면 -o를 사용합니다.
CLI 도구에 관한 추가 정보
CLI 도구 사용에 관한 자세한 내용은 npm wbn-sign
페이지를 참고하세요. 또는 wnb-sign
help.를 사용하세요.
Webpack 플러그인
하나의 키로 서명
단일 비공개 키를 사용하여 IWA에 서명하도록 Webpack 플러그인을 구성하려면 다음 안내를 따르세요.
WebBundlePlugin을 설정하여 이 키에서 필요한 기본 URL을 자동으로 파생합니다.- 단일
NodeCryptoSigningStrategy를 사용하여 서명된.swbn파일을 생성합니다.
// key is parsePemKey(private.pem)
plugins.push(
new WebBundlePlugin({
baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public' },
output: 'signed.swbn',
integrityBlockSign: {
strategy: new NodeCryptoSigningStrategy(key)
}
})
)
두 개의 키로 서명
키 순환 중에 애플리케이션에 이중 서명해야 하는 경우 다음 안내를 따르세요.
- 앱의 ID가 사용자에게 안정적으로 유지되도록 원래 키 (
old_key)를 기반으로webBundleId및 기본 URL을 정의합니다. - 서명 전략 배열을 사용하여 이전 비공개 키와 새 비공개 키를 모두 적용합니다.
// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)
plugins.push(
new WebBundlePlugin({
baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public') },
output: 'signed.swbn',
integrityBlockSign: {
strategies: [
new NodeCryptoSigningStrategy(old_key),
new NodeCryptoSigningStrategy(new_key)
],
webBundleId: new WebBundleId(old_key).serialize()
}
})
)
Rollup 또는 Vite 플러그인
하나의 키로 서명
Webpack 설정과 마찬가지로 Rollup 또는 Vite 플러그인을 사용하여 단일 비공개 키로 애플리케이션에 서명하려면 플러그인이 단일 서명 전략을 사용하고 제공된 키에서 기본 URL을 파생하여 서명된 출력을 생성합니다.
// key is parsePemKey(private.pem)
plugins.push({
...wbn({
baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public' },
output: 'signed.swbn',
integrityBlockSign: {
strategy: new NodeCryptoSigningStrategy(key)
}
}),
enforce: 'post'
})
두 개의 키로 서명
Rollup 또는 Vite를 사용하여 애플리케이션에 이중 서명하려면 여러 키를 허용하도록 플러그인을 구성해야 합니다. 이 스니펫은 전략 배열을 사용하여 이전 비공개 키와 새 비공개 키를 모두 적용합니다. 원래 기존 키에서 파생된 기본 URL과 webBundleId를 명시적으로 유지하여 원활한 전환을 보장합니다.
// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)
plugins.push({
...wbn({
baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public' },
output: 'signed.swbn',
integrityBlockSign: {
strategies: [
new NodeCryptoSigningStrategy(old_key),
new NodeCryptoSigningStrategy(new_key)
],
webBundleId: new WebBundleId(old_key).serialize()
}
}),
enforce: 'post'
})
결론
IWA의 키 순환을 성공적으로 관리하는 것은 애플리케이션 배포의 보안과 연속성을 유지하는 데 매우 중요합니다. 키가 손실되었는지 여부와 같은 특정 상황과 관계없이 설명된 단계를 따르면 사용자에게 최소한의 중단이 발생합니다. Webpack, Rollup 또는 Vite에 제공된 CLI 도구 또는 플러그인 구성을 활용하면 앱의 서명을 효율적으로 관리하고 키 순환 프로세스를 원활하게 탐색할 수 있습니다. 비상 상황에서는 지정된 신뢰할 수 있는 이메일을 통해 Google 담당자에게 즉시 연락하세요.