암호화

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

Capgo는 앱 번들에 강력한 종단간 암호화를 제공하여, 전송 및 저장 과정에서 JavaScript code와 에셋을 안전하게 보호합니다. 이 암호화 시스템은 Live Update의 편의성을 유지하면서도 앱 보안에 대한 완전한 제어권을 제공하도록 설계되었습니다.

개요

Capgo의 암호화 시스템은 업계 표준 암호화 방식을 사용해 번들을 무단 액세스로부터 보호합니다. 암호화를 활성화하면 번들은 개발 환경을 떠나기 전에 암호화되고, 사용자 기기에서 앱이 복호화할 때까지 암호화된 상태로 유지됩니다.

암호화가 실제로 보호하는 것: 업데이트에 서명만 하는 OTA 시스템과 달리, Capgo는 업로드된 번들을 저장하고 전달하기 전에 암호화합니다. 이렇게 하면 저장 또는 전송 중 번들 내용에 쉽게 접근하는 것을 막고, private key를 가진 사람만 유효한 암호화 업데이트를 생성할 수 있습니다. 다만, 하지 마세요 배포된 웹 에셋을 리버스 엔지니어링하는 것을 불가능하게 만들지는 않습니다. 클라이언트가 업데이트 복호화에 사용하는 public key는 앱에 포함되어 있으므로, 공격자가 마음먹고 충분히 노력하면 이를 추출해 번들 내용을 검사할 수 있습니다.

보안 모델

Capgo에 대한 기밀성

RSA 개인 키는 사용자의 머신에서 생성되고 보관됩니다. Capgo CLI에서는 개인 키를 절대 전송하지 않으며, Capgo 역시 이를 저장하지 않습니다. Capgo 역시 전체 RSA 공개 키를 저장하지 않으며, 업로드에는 짧은 key_id (PEM 본문의 처음 20자) 채널에서 사용한 키 쌍을 매칭할 수 있도록 합니다.

암호화된 전체 번들은 다음과 같이 저장 및 전달됩니다. AES-128-CBC 암호문. Capgo 서비스, CDN, 오브젝트 스토리지, 그리고 전달 경로에 있는 누구도 개인 키 없이는 호스팅된 아티팩트에 담긴 JavaScript, HTML, 에셋을 읽을 수 없습니다.

Capgo로부터의 최대 기밀성

기본 암호화만으로도 번들의 내용이 Capgo 스토리지에 저장될 때와 전송 중에 기밀로 유지됩니다. 업데이트 채널을 특정 스토어 바이너리와 연결해 Capgo이 알 수 있는 정보를 더 줄이고 싶다면 다음 가이드를 따르세요.

전용 Capgo 앱 ID를 사용하세요. 설정 plugins.CapacitorUpdater.appId (사용자의 Capgo app_id)를 값으로 설정하세요. 이 값은 하지 마세요 iOS bundle ID 또는 Android application ID와 같아야 합니다. 스토어 및 MDM 빌드는 RSA 공개 키를 포함합니다. capacitor.config. Capgo가 app_id 스토어 패키지 이름과 일치하면, 해당 공개 키를 포함하는 배포된 바이너리와 Capgo 앱을 연결하기가 더 쉽습니다. 별도의 Capgo 앱 ID를 사용하면 이런 직접 연결을 피할 수 있습니다.

Capgo Builder 및 공개 키. Capgo Builder 업로드는 프로젝트를 zip으로 묶으며, 이때 capacitor.config (및 네이티브 트리)를 포함하여 plugins.CapacitorUpdater.publicKey 후 key save. Builder 업로드에서 공개 키를 제외하려면:

Capgo로부터의 보안이 중요하다면 네이티브 앱을 로컬 또는 자체 CI에서 빌드하세요. 또한 설정에 공개 키가 포함된 상태에서 Capgo Builder를 통해 해당 트리를 업로드하지 않도록 주의하세요. 또는
다음 명령어로 공개 키를 추가하세요: key save 키가 노출되면 안 되는 Builder의 업로드가 모두 완료된 후에만, 또는
네이티브 빌드에 Capgo Builder를 사용한다면, 이 워크플로우가 강력한 무결성 (서명된 체크섬)을 제공한다고 간주하되, 하지 마세요 공개 키가 Builder 업로드에 포함된 이후에는 Capgo의 기밀성을 보장할 수 없음을 유의하세요.

Delta 업로드를 암호화하세요. Delta(부분) 파일 본문은 다음을 사용하지 않으면 평문으로 전송됩니다: @capgo/capacitor-updater 6.14.4 이상의 버전 (지원되는 updater 버전에서 암호화된 업로드는 부분 암호화가 자동 활성화됨) 또는 --encrypt-partial 켜짐 bundle upload. 부분 암호화를 적용하더라도, 파일 이름 delta manifest에 나열된 파일 이름은 암호화되지 않으며, 파일별 해시만 RSA로 래핑됩니다.

무결성

복호화 후, updater는 SHA-256 번들에 대한 해시를 계산하여 RSA-wrapped 서명에서 추출한 체크섬과 비교합니다. 불일치하면 번들은 삭제되고 절대 활성화되지 않습니다:

Android 복호화 후 체크섬을 확인하고 첫 번째 제출이 승인되기 아카이브 압축 해제 중.
iOS 먼저 복호화하고 압축을 푼 다음 체크섬을 검증합니다 첫 번째 제출이 승인되기 번들을 활성화할 수 있습니다.

공개 키가 설정된 경우, 체크섬이 누락되었거나 RSA 서명이 올바르지 않으면 거부됩니다.

키 관리

전체 zip 업로드마다 CLI는 새로운 랜덤 AES-128 세션 키와 16바이트 IV, 번들을 다음 방식으로 암호화합니다: AES-128-CBC, 그리고 세션 키를 사용자의 RSA-2048 개인 키로 암호화하며, PKCS#1 v1.5 type 1 패딩 방식을 사용합니다. 디바이스는 앱에 내장된 RSA 공개 키를 통해 AES 키를 복구합니다. 키와 IV는 별도의 CLI 번들 upload 시 재사용되지 않습니다. 단일 delta upload 내에서는 모든 암호화된 부분 파일이 해당 upload의 세션 키와 IV를 공유합니다.

복호화에 사용되는 공개 키는 배포된 앱에 내장됩니다. 평문 번들 콘텐츠는 업데이트 프로세스와 동일한 복호화 경로를 사용하는 디바이스에서 앱 패키지의 다른 에셋과 마찬가지로 접근 가능합니다.

실패 및 보고

복호화 및 체크섬 실패는 통계 이벤트로 보고됩니다 ("download_fail, checksum_fail, decrypt_fail")를 Capgo stats 엔드포인트 또는 귀하의 셀프 호스팅 통계 핸들러. 통계는 기기에서 전송되며, 복호화 성공 여부에 따라 제3자 번들 호스트로 데이터가 보고되지 않습니다. 각 시도는 보통 기기에서 시작하는 전체 다운로드 방식이므로, padding-oracle 방식의 프로빙은 실효성이 없으며 수정된 평문은 서명된 체크섬 검증을 통과할 수 없습니다.

향후 보안 강화

향후 메이저 릴리스에서는 다음을 포함한 버전화된 포맷이 추가될 수 있습니다: AES-GCM 및 RSA-PSS 현재 설계와 함께 심층 방어(defense in depth)를 위해 해시 위에 적용하는 방식입니다. 이는 현재 포맷에 대한 긴급 보안 패치가 아닌, 점진적인 보안 강화 단계가 될 것입니다.

암호화 작동 원리

Capgo는 최적의 보안과 성능을 위해 RSA와 AES 암호화를 결합한 하이브리드 암호화 방식을 사용합니다:

Capgo 암호화 흐름

1. 키 생성

개인 키: 개발 환경에서 생성되어 안전하게 저장됨 (암호화에 사용)
공개 키: 개인 키에서 파생되어 앱의 Capacitor 설정에 저장됨 (복호화에 사용)
세션 키: 번들 업로드마다 생성되는 무작위 AES 키

2. 암호화 프로세스

번들 업로드마다 무작위 AES 세션 키가 생성됩니다
AES 세션 키를 사용하여 번들을 암호화합니다
번들 체크섬을 계산합니다
AES 세션 키와 체크섬을 RSA 개인 키로 함께 암호화하여 “서명(signature)”을 생성합니다
암호화된 번들과 암호화된 서명을 저장합니다

변조를 방지하기 위해 AES 키와 함께 체크섬을 암호화합니다. RSA 개인 키로만 이 서명을 생성할 수 있고 대응하는 공개 키로만 복호화할 수 있으므로, AES 세션 키와 예상 체크섬이 모두 유효하며 공격자에 의해 수정되지 않았음을 보장합니다.

3. 복호화 프로세스

앱이 암호화된 번들과 암호화된 서명을 다운로드합니다
Capgo SDK는 앱에 저장된 RSA 공개 키를 사용하여 서명을 복호화합니다
이를 통해 AES 세션 키와 원본 체크섬을 확인합니다
AES 세션 키를 사용하여 번들을 복호화합니다
복호화된 번들의 체크섬을 계산하여 원본 체크섬과 비교함으로써 무결성을 검증합니다

이 프로세스를 통해 공격자가 암호화된 번들을 가로채더라도 AES 세션 키를 수정하거나 가짜 체크섬을 제공할 수 없습니다. 유효한 서명을 생성하여 공개 키로 복호화하려면 반드시 사용자의 개인 키가 필요하기 때문입니다.

Capgo vs 다른 플랫폼

기능	Capgo	기타 OTA 플랫폼
번들 콘텐츠	저장/전송 시 암호화되나, 앱 바이너리가 있다면 숙련된 리버스 엔지니어가 분석 가능함	공개적으로 읽기 가능
보안 방식	진정한 종단간 암호화(E2EE)	Code 서명만
개인정보 보호 수준	강력한 전송/저장 보호; 리버스 엔지니어링 방지는 아님	플랫폼이 code에 접근할 수 있음
보호 범위	콘텐츠 + 무결성 + 진본성	무결성 + 진본성만

왜 중요한가:

Code 서명은 업데이트가 변조되지 않았으며 올바른 출처에서 왔는지만 확인합니다
Capgo 암호화 번들이 저장되고 전달되는 동안 보호하며, 공격자가 개인 키를 필요로 하므로 위조된 암호화 업데이트를 만들기가 훨씬 어려워집니다.
리버스 엔지니어링은 여전히 가능합니다. 앱 출시 후에는 클라이언트에 업데이트를 복호화하고 로드하는 데 필요한 공개 키가 포함되어 있기 때문입니다.

암호화 방식

Capgo는 표준 암호화 방식으로 Encryption V2를 사용합니다:

Encryption V2 (현재 표준)

보안 강화를 위해 RSA-4096 사용
인증 암호화를 위한 AES-256-GCM 사용
무결성 검증 기능 제공
성능 및 보안 향상

Encryption V1 (지원 중단)

키 암호화에 RSA-2048 사용
번들 암호화에 AES-256-CBC 사용
현재 CLI에서 더 이상 사용할 수 없음
V1을 사용하는 레거시 앱은 V2로 마이그레이션해야 합니다

암호화 설정하기

1단계: 암호화 키 생성

먼저, 다음 Capgo CLI 명령어를 사용하여 암호화 키를 생성하세요:

# Generate new encryption keys (creates files in current directory)
npx @capgo/cli@latest key create

다음 파일들이 생성됩니다:

.capgo_key_v2: 개인키 (보안에 각별히 유의하세요!)
.capgo_key_v2.pub: 공개키 (앱에서 사용됨)

해당 파일들은 명령어를 실행한 현재 디렉토리에 생성됩니다.

저장 시 주의사항:

개인 키 (.capgo_key_v2): 버전 관리 시스템에 절대 커밋하지 마세요. 이 파일은 안전하게 보관해야 하며, bundle upload 시 암호화 용도로만 사용해야 합니다.
공개 키 (.capgo_key_v2.pub): 공개 키의 백업 파일이므로 버전 관리 시스템에 커밋해도 안전합니다.
파일 위치: 키는 다음 명령어를 실행하는 현재 디렉토리에 생성됩니다. key create 명령어.
Config 내 Public Key: 다음 명령어를 실행해야 합니다. key save 모바일 앱에서 사용할 수 있도록 Capacitor 설정에 공개 키를 저장합니다.

프로덕션 환경에서는 개인 키를 안전하게(환경 변수, 키 관리 서비스 등) 저장하고, 설정이 완료되면 로컬 프로젝트에서 삭제하세요.

2단계: 공개 키를 Capacitor 설정에 저장 (필수)

귀하 해야 합니다 모바일 앱이 번들을 복호화할 수 있도록 공개 키를 Capacitor 설정에 저장하세요:

# Save public key from file to Capacitor config (required)
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

# Or save public key data directly
npx @capgo/cli@latest key save --key-data "$CAPGO_PUBLIC_KEY"

3단계: Capacitor 플랫폼 동기화 (필수)

공개 키를 저장한 후에는, 해야 합니다 업데이트된 설정을 네이티브 레이어로 복사하려면 Capacitor 플랫폼을 동기화하세요:

# Sync the platform to copy config to native
npx cap sync

Bundle 암호화

방법 1: 업로드 시 암호화

가장 간단한 방법은 업로드 과정에서 암호화하는 것입니다:

# Upload with automatic encryption
npx @capgo/cli@latest bundle upload --key-v2

# For external storage, you must encrypt first (see Manual Encryption Workflow below)

방법 2: 수동 암호화 워크플로우

더 세밀한 제어가 필요하다면 번들을 수동으로 암호화할 수 있습니다:

zip 번들 생성:

npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

번들 암호화:

npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1

스토리지(예: S3)에 업로드한 후 Capgo에 등록하세요:

# First upload the encrypted bundle to your storage (e.g., AWS S3)
aws s3 cp ./encrypted-bundle.zip s3://your-bucket/encrypted-bundle.zip

# Then register with Capgo using the external URL
npx @capgo/cli@latest bundle upload --external https://your-storage.com/encrypted-bundle.zip --iv-session-key IV_SESSION_KEY_FROM_STEP_2

키 관리

키를 안전하게 저장하기

Private Key 옵션:

파일 기반 (로컬 개발용):

# Key stored as .capgo_key_v2 file in project root
npx @capgo/cli@latest bundle upload --key-v2

환경 변수 (CI/CD):

# Store in environment variable for CI
export CAPGO_PRIVATE_KEY="$(cat .capgo_key_v2)"
npx @capgo/cli@latest bundle upload --key-data-v2 "$CAPGO_PRIVATE_KEY"

공개 키 설정 (필수):

# Must save public key to Capacitor config for mobile app
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

운영 환경:

비밀 키는 보안 키 관리 서비스(AWS KMS, Azure Key Vault 등)에 저장하세요
비밀 키 관리에 CI/CD secret management를 사용하세요
비밀 키를 버전 관리 시스템에 절대 커밋하지 마세요

키 사용법:

개인 키: CLI가 번들 upload 시 암호화에 사용합니다 (보안 유지 필수)
공개 키: 기기에서 복호화하기 위해 앱 설정에 저장됩니다 (커밋 가능)

개인 키 침해 시 키 교체

개인 키가 유출되었거나 유출이 의심되는 경우 키 쌍을 교체하세요. 정기적인 일정에 따른 교체는 필요하지 않습니다. 이는 OTA 전용 변경이 아닌 native-key 마이그레이션입니다.

교체할 키 쌍 생성:
터미널 창
```
npx @capgo/cli@latest key create
```
교체된 공개 키를 Capacitor 설정에 저장하세요:
터미널 창
```
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub
```
네이티브 릴리스를 동기화하고 배포하세요: 실행 npx cap sync, 그 다음 교체된 공개 키를 포함하는 새로운 네이티브 앱 버전을 배포합니다.
새로운 네이티브 버전을 대상으로 지정하세요: 이전 네이티브 바이너리를 실행 중인 기기는 교체된 키로 암호화된 업데이트를 복호화할 수 없습니다. 다음을 사용하세요: 버전 타겟팅 를 사용하여 나머지 기기들이 스토어나 MDM을 통해 업데이트되는 동안, 교체 키 번들은 새로운 네이티브 버전으로만 제한할 수 있습니다.
업로드 시크릿을 교체하세요: 네이티브 릴리스가 배포되는 즉시 CI의 개인 키를 교체하고, 교체된 공개 키를 포함하는 네이티브 버전을 대상으로 하는 번들만 upload 하세요.

보안 모범 사례

키 보안

개인키를 절대 공유하지 마세요 환경 간 또는 팀원 간 공유 금지
환경별로 다른 키를 사용하세요 각 환경(dev, staging, production)마다 별도 사용
유출 시 키 교체(Rotate): 개인키 유출이 의심되거나 확인되면 키 쌍을 교체하세요. 정기적인 일정에 따른 교체는 필수가 아닙니다.
키를 안전하게 보관하세요 적절한 키 관리 시스템 사용

Bundle 보안

항상 검증하세요 복호화 후 bundle 무결성 확인
모니터링 비정상적인 download 패턴 또는 실패 감지
HTTPS 사용 모든 bundle URL에 적용 (모바일 앱 필수)
구현하기 복호화 실패 시 적절한 에러 핸들링

접근 제어

액세스 제한 암호화 키는 승인된 인원에게만 허용하세요
역할 기반 액세스를 사용하세요 키 관리 작업에 적용하세요
감사 키 사용 및 액세스를 정기적으로 감사하세요
구현하기 적절한 백업 및 복구 절차

암호화 문제 해결

일반적인 이슈

복호화 실패 시:

개인키가 암호화에 사용된 공개키와 일치하는지 확인하세요
다음 사항을 확인하세요: ivSessionKey 이(가) 올바른지
Encryption V2를 사용 중인지 확인하세요 (V1은 더 이상 지원되지 않음)

키 관련 오류:

개인키 형식이 올바른지 확인하세요 (PEM 형식)
저장 또는 전송 과정에서 키가 손상되지 않았는지 확인하세요
앱 설정에 키 권한이 올바르게 부여되었는지 확인하세요

성능 문제:

번들 크기가 크면 암호화/복호화에 시간이 더 걸릴 수 있습니다
번들 크기를 줄이려면 Delta updates 사용을 고려하세요
복호화 중 기기 성능을 모니터링하세요

디버그 명령어

암호화 상태 확인:

npx @capgo/cli@latest app debug

암호화/복호화 워크플로우 테스트:

# Test the complete workflow: zip → encrypt → decrypt → unzip
npx @capgo/cli@latest bundle zip com.example.app --key-v2
npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM --json
npx @capgo/cli@latest bundle decrypt ./encrypted-bundle.zip IV_SESSION_KEY

컴플라이언스 및 표준

Capgo의 암호화 구현은 업계 표준을 따릅니다:

AES-256: FIPS 140-2 인증 암호화 알고리즘
RSA-4096: 키 보호를 위한 강력한 비대칭 암호화
GCM 모드: 기밀성과 무결성을 모두 제공
보안 랜덤 생성: 암호학적으로 안전한 난수 생성

이를 통해 Capgo는 다음 규정을 준수해야 하는 애플리케이션에 적합합니다:

GDPR (일반 개인정보 보호 규정)
HIPAA (미국 의료정보 보호법)
SOC 2 (Service Organization Control 2)
ISO 27001 (정보 보안 관리)

성능 고려 사항

암호화 오버헤드

Bundle 크기: 암호화된 bundle은 크기가 약간 더 큼 (~1-2% 오버헤드)
처리 시간: 암호화/복호화로 인한 지연 시간은 미미함
메모리 사용량: 암호화/복호화 작업 중 일시적으로 증가

최적화 팁

Delta update를 사용하여 암호화된 데이터 전송 최소화
이미지를 WebP 형식으로 변환하여 bundle 크기 최적화
bundling 전 JavaScript 및 CSS 파일 최소화
사용하지 않는 의존성 및 code 제거
구형 또는 저사양 기기에서의 디바이스 성능 모니터링

다음 단계

자세히 알아보기 커스텀 스토리지 자체 인프라에서 암호화 기능을 사용하려면
둘러보기 채널 환경별 암호화된 bundle 관리
설정하기 CI/CD 통합 암호화된 배포 자동화

암호화 다음 단계

사용 중이라면 암호화 보안 및 컴플라이언스 계획을 세우려면, 다음 항목과 연결하세요: 컴플라이언스 컴플라이언스 구현 상세 정보: Capgo 보안 스캐너 Capgo Security Scanner 제품 워크플로우: Capgo 보안 Capgo Security의 제품 워크플로의 경우, Capgo 신뢰 센터 Capgo Trust Center의 제품 워크플로의 경우, 조직 보안 Organization Security의 구현 세부 사항의 경우.