암호화

설치

Capgo은 앱 번들을 위한 강력한 종단 간 암호화를 제공하여, JavaScript code 및 자산이 전송 및 저장 중에 보호됩니다. 이 암호화 시스템은 앱의 보안에 대한 완전한 제어를 유지하면서 실시간 업데이트의 편의성을 유지하는 데 설계되었습니다.

개요

Capgo의 암호화 시스템은 업무 표준 암호화 방법을 사용하여 앱 번들을 비인가 접근으로부터 보호합니다. 암호화가 활성화되면, 개발 환경에서 앱 번들이 암호화되어 사용자 기기에서 앱이 암호화를 해제할 때까지 암호화 상태로 유지됩니다.

암호화가 실제로 보호하는 것: 업데이트를 서명하는 OTA 시스템과 달리, Capgo은 업로드한 앱 번들을 저장 및 전송하기 전에 암호화합니다. 이로 인해 저장소 또는 전송 중에 앱 번들의 내용에 대한 비인가 접근을 방지하고, 유효한 암호화된 업데이트를 생성할 수 있는 사람만이 개인 키를 보유한 경우에만 유효한 암호화된 업데이트를 생성할 수 있습니다. 업데이트를 서명하는 OTA 시스템과 달리, __CAPGO_KEEP_0__은 업로드한 앱 번들을 저장 및 전송하기 전에 암호화합니다. 이로 인해 저장소 또는 전송 중에 앱 번들의 내용에 대한 비인가 접근을 방지하고, 유효한 암호화된 업데이트를 생성할 수 있는 사람만이 개인 키를 보유한 경우에만 유효한 암호화된 업데이트를 생성할 수 있습니다. 암호화가 필요할 때

업로드 한 번들을 암호화하지 않으면, 그것을 공개 자산으로 간주합니다. 개인 채널은 업데이트 수신을 제한하는 데 도움이 되지만 업로드 한 번들을 비밀로 하는 것은 아닙니다. 암호화는 저장 및 전송에서 더 나은 보호를 원할 때, 그리고 개인 키를 보유한 사람들만 유효한 암호화된 업데이트를 발행할 수 있도록 하기 위해 유용합니다. 그러나 shipped JavaScript, HTML, 또는 CSS가 절대 검사될 수 없다는 보장을 제공하지는 않습니다.

암호화의 작동 방식

Capgo은 RSA 및 AES 암호화를 결합한 하이브리드 암호화 접근 방식을 사용하여 최적의 보안성과 성능을 제공합니다:

Capgo 암호화 흐름

1. 키 생성

개인 키: 개발 환경에서 안전하게 생성 및 저장되며 암호화에 사용됩니다
공개 키: 개인 키에서 파생되어 앱의 Capacitor 설정에 저장되며 복호화에 사용됩니다
세션 키: 각 업로드 배포에 대한 임의 AES 키를 생성합니다

2. 암호화 프로세스

각 업로드 배ंडल에 대해 랜덤 AES 세션 키가 생성됩니다.
배ंडल은 AES 세션 키를 사용하여 암호화됩니다.
배ंडल 체크섬이 계산됩니다.
AES 세션 키와 체크섬은 모두 RSA 개인 키를 사용하여 암호화됩니다 (‘서명’을 생성합니다).
암호화된 배ंडल과 암호화된 서명이 저장됩니다.

체크섬은 공격자가 체크섬을 변조하지 못하도록 AES 키와 함께 암호화됩니다. RSA 개인 키만이 이 서명을 생성할 수 있고, 이 서명을 복호화할 수 있는 공개 키만이 이 서명을 복호화할 수 있으므로, 이 서명은 AES 세션 키와 예상 체크섬이 공격자가 변조하지 않은 것으로 보장됩니다.

3. 복호화 프로세스

앱은 암호화된 배ंडल과 암호화된 서명을 다운로드합니다.
Capgo SDK은 앱에 저장된 RSA 공개 키를 사용하여 서명을 복호화합니다.
이것은 AES 세션 키와 원래 체크섬을 드러냅니다.
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

Capgo

__CAPGO_KEEP_0__	Capgo	__CAPGO_KEEP_0__
__CAPGO_KEEP_0__	__CAPGO_KEEP_0__ 저장/전송 시 암호화; 여전히 앱 바이너리에서 결정된 역공학자에 의해 검사 가능합니다.	공개 가능한
보안 방법	완전한 종단 간 암호화	Code에 대한 서명만
privacylevel	강력한 전달/저장 보호; 역공학 방지가 아닌	플랫폼이 code에 접근할 수 있습니다.
보호	내용 + 무결성 + 진위	무결성 + 진위만

이것이 중요한 이유:

Code 서명 업데이트가 조작되지 않았는지와 올바른 출처인지만 확인합니다.
Capgo 암호화 업데이트가 저장되고 전송되는 동안 패키지를 보호하고 암호화된 업데이트를 위조하는 것이 훨씬 어려워집니다. 공격자가 개인 키를 필요로 하기 때문입니다.
앱이 배포된 후에도 역공학이 가능합니다. 클라이언트에는 암호화 및 업데이트를 로드하기 위해 필요한 공개 키가 포함되어 있기 때문입니다. 암호화 방법

암호화 방법

Capgo uses Encryption V2 as the standard encryption method:

현재 표준인 암호화 V2

암호화 V2 (현재 표준)
AES-256-GCM 인증 암호화
인증 암호화에 대한 무결성 검증을 제공합니다.
성능과 보안을 향상시킵니다.

V1 암호화 (deprecated)

키 암호화를 위해 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): 버전 관리에 이 파일을 커밋하지 마세요. 이 파일은 업로드 중인 패키지 암호화에만 사용하기 위해 안전하게 보관되어야 합니다.
공개 키 (.capgo_key_v2.pub): 이 파일은 버전 관리에 커밋할 수 있습니다. 이는 공개 키의 백업이기 때문입니다.
파일 위치: 키들은 명령어를 실행한 현재 디렉토리에서 생성됩니다. key create 공개 키 (Config)
Public Key in Config을 실행하여야 합니다. key save Capacitor 설정에 공개 키를 저장해야만 모바일 앱이 사용할 수 있습니다.

생산 환경에서 사용할 경우, 개인 키를 안전하게 보관하십시오 (환경 변수, 키 관리 서비스) 그리고 설정 후에 로컬 프로젝트에서 제거하십시오.

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

당신은 __CAPGO_KEEP_0__ 설정에 공개 키를 저장해야만 모바일 앱이 암호화된 패키지를 해독할 수 있습니다. save your public key to the Capacitor config so your mobile app can decrypt bundles:

# 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 플랫폼 동기화 (필수) 섹션

__CAPGO_KEEP_0__ 플랫폼을 저장한 공개 키 후에 해야 합니다 Capacitor 플랫폼을 동기화하여 업데이트된 구성 파일을 네이티브层로 복사해야 합니다

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

__CAPGO_KEEP_0__

__CAPGO_KEEP_2__

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

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

__CAPGO_KEEP_4__

__CAPGO_KEEP_0__

__CAPGO_KEEP_6__

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

Capgo와 함께 저장소(예: S3)에 업로드하고 등록하세요.

# 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

키 관리

키를 안전하게 저장하는 방법

개인 키 옵션:

파일 기반 (개발 환경):

# 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 비밀 관리를 사용하여 개인 키를 관리하십시오.
버전 관리에 개인 키를 커밋하지 마세요.

Key Usage:

개인 키: CLI에 의해 업로드 시 번들 암호화에 사용됩니다 (보안 유지)
공개 키: 장치에서 암호화에 사용되는 앱 구성에 저장됩니다 (커밋할 수 있음)

개인 키 compromis가 발생한 후 회전

개인 키가 의심되거나 확인된 경우 키 pair를 회전하세요. 정기적인 캘린더 회전은 필요하지 않습니다. 이건 원본 키 마이그레이션이며, OTA-Only 변경이 아닙니다.

대체 키 pair를 생성하세요:
터미널 창
```
npx @capgo/cli@latest key create
```
Capacitor 설정에 대체 공개 키를 저장하세요:
터미널 창
```
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub
```
대체 공개 키를 포함하는 새로운 네이티브 앱 버전을 배포하세요: 실행 npx cap sync, 그리고 대체 공개 키를 포함하는 새로운 네이티브 앱 버전을 배포하세요.
대체 공개 키를 포함하는 새로운 네이티브 버전을 대상하세요: 기존 네이티브 바이너리에서 실행 중인 장치들은 대체 키로 암호화된 업데이트를 해독할 수 없습니다. 대체 키로 암호화된 업데이트를 받으려면 버전 대상 을 사용하세요.
대체 키로 암호화된 업데이트를 받으려면 기존 네이티브 바이너리에서 실행 중인 장치들을 제외한 나머지 장치들을 업데이트하도록 대체 키로 암호화된 업데이트를 배포하세요. 업로드 비밀 키를 변경하세요:

보안 최적화

키 보안

개인 키를 절대 공유하지 마세요. 환경이나 팀원들 사이에
다른 환경(개발, 스테이징, 운영)에는 키를 교체하고
compromise 후 회전키 pair를 사전 예비 또는 확인된 키가 훼손된 경우 대체하십시오.
키를 안전하게 저장하십시오. 적절한 키 관리 시스템을 사용하십시오.

Bundle 보안

반드시 해독 후 Bundle의完整성을 확인하십시오. 비정상적인 다운로드 패턴 또는 실패를 모니터링하십시오.
https를 모든 Bundle URL에 사용하십시오 (모바일 앱의 경우 필수) 구현하십시오.
Section titled “Bundle Security” Always verify
using proper key management systems 복호화 실패 시 적절한 오류 처리

접근 제어

권한 제한 암호화 키에 대한 접근을 yalnızca 인증된 인원에게만 허용
역할 기반 접근 제어 키 관리 작업에 대한 역할 기반 접근
감사 키 사용 및 접근을 정기적으로 감사
구현 적절한 백업 및 복구 절차

암호화 문제 해결

일반적인 문제

해독 실패:

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

키 관련 오류:

개인 키 형식이 올바른지 확인하세요 (PEM 형식)
저장/전송 중 키가 손상되지 않았는지 확인하세요
앱 구성에서 키가 올바른 권한을 가지고 있는지 확인하세요

성능 문제:

대형 번들 암호화/복호화가 더 오래 걸릴 수 있습니다.
Delta(매니페스트) 업데이트를 사용하여 번들 크기를 줄이십시오.
디바이스의 성능을 모니터링하십시오.

Debug 명령어

암호화 상태를 확인하십시오:

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 모드: 신뢰성과 진위성을 제공하는 암호화
Secure Random: 암호학적으로 안전한 난수 생성

이로써 Capgo는 다음 규정 준수를 요구하는 애플리케이션에 적합합니다:

개인 정보 보호 규정(General Data Protection Regulation)
건강보험 및 책임성 관리법(Health Insurance Portability and Accountability Act)
서비스 조직 제2종 관리(Service Organization Control 2)
정보 보안 관리 표준(Information Security Management)

성능 고려 사항

암호화 오버헤드

배포 크기: 암호화된 배포는 약 1-2%의 오버헤드가 발생합니다.
처리 시간: 암호화/복호화는 최소한의 지연 시간을 추가합니다.
메모리 사용: 암호화/복호화 작업 중 임시적으로 증가하는 메모리 사용

최적화 팁

Delta (매니페스트) 업데이트 사용하여 암호화된 데이터 전송량을 최소화
이미지 형식을 WebP 형식으로 변환하여 번들 크기를 최적화
JavaScript 및 CSS 파일 크기를 최소화하기 전에 번들링
사용하지 않는 의존성을 제거하고 code
오래된/느린 장치에서 장치 성능 모니터링

다음 단계

알아보기 Custom Storage 자체 인프라에서 암호화를 사용하기 위해
Explore 채널 환경 간 암호화된 패키지를 관리하기 위해
설정 CI/CD 통합 환경 간 암호화된 배포를 자동화하기 위해

다음으로

암호화를 사용하고 있다면 암호화 보안 및 규정 준수 계획을 수립하기 위해 연결하세요. 규정 준수 규정 준수에 대한 구현 세부 정보 Capgo 보안 스캐너 Capgo 보안 스캐너의 제품 워크플로우 Capgo 보안 Capgo 보안의 제품 워크플로우 Capgo 신뢰 센터 Capgo 신뢰 센터의 제품 워크플로우 조직 보안 규정 준수에 대한 구현 세부 정보