暗号化

このプラグインのインストール手順と完全なMarkdownガイドを含むセットアッププロンプトをコピー

Capgo は、アプリの bundle に対して強力なエンドツーエンド暗号化を提供します。これにより、JavaScript の code やアセットが、転送中および保存中の両方で保護されます。この暗号化システムは、Live Update の利便性を維持しながら、アプリのセキュリティを完全にコントロールできるように設計されています。

概要

Capgoの暗号化システムは、業界標準の暗号化手法を用いて、不正アクセスからbundleを保護します。暗号化を有効にすると、bundleは開発環境を離れる前に暗号化され、ユーザーのデバイス上のアプリによって復号されるまで暗号化された状態が維持されます。

暗号化による保護対象: アップデートに署名のみを行うOTAシステムとは異なり、Capgoはアップロードされたbundleを保存・配信前に暗号化します。これにより、ストレージ内や転送中のbundleの内容への安易なアクセスを防ぎ、秘密鍵を持つユーザーのみが有効な暗号化アップデートを作成できることを保証します。ただし、 プッシュされません 配信済みのWebアセットのリバースエンジニアリングを完全に不可能にするわけではありません。クライアントがアップデートを復号するために使用する公開鍵はアプリ内に含まれているため、執拗な攻撃者が多大な労力をかければ、鍵を抽出してbundleの内容を解析することは可能です。

セキュリティモデル

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と同じものに設定してください。Store版や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でラップされます。

完全性（Integrity）

復号後、アップデーターは SHA-256 をbundleに対して計算し、RSAラップされた署名から復元されたチェックサムと比較します。不一致の場合、bundleは削除され、アクティベートされることはありません：

Android 復号後にチェックサムを確認し、前にアーカイブの解凍。
iOS まず復号と解凍を行い、その後にチェックサムを検証します前に bundle をアクティブに設定できます。

公開鍵が設定されている場合、チェックサムが不足しているものや RSA署名が正しくないものは拒否されます。

鍵の取り扱い

zipファイルをアップロードするたびに、CLI は新しいランダムな AES-128 セッション鍵と 16バイトのIV、を使用してbundleを暗号化し、 AES-128-CBC、さらにセッションキーをあなたの RSA-2048 秘密鍵で暗号化します。これには PKCS#1 v1.5 type 1 パディングが使用されます。デバイスは、アプリに組み込まれたRSA公開鍵を使用してAESキーを復元します。鍵とIVは、個別のCLI bundle upload間で再利用されません。単一のdelta upload内では、すべての暗号化された部分ファイルがそのuploadのセッションキーとIVを共有します。

復号に使用される公開鍵は、リリース済みのアプリに組み込まれています。平文のbundleコンテンツは、アップデーターと同じ復号パスを使用してアプリを実行するデバイス上で利用可能であり、アプリパッケージ内の他のアセットと同様に扱われます。

エラーとレポート

復号およびチェックサムの失敗は、統計イベントとして報告されます（download_fail, checksum_fail, decrypt_fail）Capgo statsエンドポイント、またはお客様のセルフホスト型統計ハンドラー統計データはデバイスから送信されます。復号の成否に基づいて、サードパーティのbundleホストへ情報が報告されることはありません。各試行は通常、デバイス側から開始されるフルダウンロードであるため、padding-oracle攻撃のようなプロービングは実用的ではなく、改ざんされた平文は署名付きチェックサムによって検知されます。

今後のセキュリティ強化

将来のメジャーリリースでは、現在の設計に加え、多層防御として以下の要素を含むバージョン管理されたフォーマットが追加される可能性があります： AES-GCM と RSA-PSS これらはハッシュに対する防御策として導入されます。これは段階的なセキュリティ強化であり、現在のフォーマットに対する緊急のセキュリティ修正ではありません。

暗号化の仕組み

Capgo は、セキュリティとパフォーマンスを最適化するため、RSAとAESを組み合わせたハイブリッド暗号化方式を採用しています：

Capgo の暗号化フロー

1. 鍵の生成

秘密鍵: 開発環境で安全に生成・保管（暗号化に使用）
公開鍵: 秘密鍵から導出され、アプリの Capacitor 設定に保存（復号に使用）
セッション鍵: bundle のアップロードごとに生成されるランダムな AES 鍵

2. 暗号化プロセス

bundle のアップロードごとに、ランダムな AES セッション鍵が生成されます
AESセッションキーを使用してbundleを暗号化します
bundleのチェックサムを算出します
AESセッションキーとチェックサムの両方をRSA秘密鍵でまとめて暗号化し、「署名」を作成します
暗号化されたbundleと暗号化された署名を保存します

改ざん防止のため、チェックサムはAESキーと共に暗号化されます。RSA秘密鍵でのみこの署名を作成でき、対応する公開鍵でのみ復号できるため、AESセッションキーと期待されるチェックサムの両方が真正であり、攻撃者によって改ざんされていないことが保証されます。

3. 復号プロセス

アプリが暗号化されたbundleと署名をダウンロードします
Capgo SDK は、アプリ内に保存されているRSA公開鍵を使用して署名を復号します
これにより、AESセッションキーと元のチェックサムが明らかになります
AESセッションキーを使用してbundleを復号します
復号されたbundleのチェックサムを算出し、元のチェックサムと比較して整合性を検証します

このプロセスにより、攻撃者が暗号化されたbundleを傍受しても、AESセッションキーの改ざんや偽のチェックサムの提供はできません。公開鍵で検証できる有効な署名を作るには、あなたの秘密鍵が必要だからです。

Capgo vs 他のプラットフォーム

機能	Capgo	その他のOTAプラットフォーム
bundleの内容	保存時・転送時は暗号化されますが、アプリのバイナリを持つ本気のリバースエンジニアなら検査可能です	公開状態で読み取り可能
セキュリティ方式	完全なエンドツーエンド暗号化	Code の署名のみ
プライバシーレベル	配信・保存の強力な保護（リバースエンジニアリング対策ではない）	プラットフォームが code にアクセス可能
保護対象	コンテンツ + 完全性 + 真正性	完全性 + 真正性のみ

重要性:

Code の署名 アップデートが改ざんされておらず、正しいソースから提供されていることのみを検証します
Capgo の暗号化 bundle の保存時と配信時に保護し、偽造された暗号化アップデートの作成を格段に難しくします。攻撃者にはあなたのプライベートキーが必要だからです。
リバースエンジニアリングは依然として可能です アプリ配信後でも、クライアント側にアップデートの復号とロードに必要な公開キーが含まれているためです。

暗号化方式

Capgo では、標準の暗号化方式として Encryption V2 を使用しています：

Encryption V2（現在の標準）

セキュリティ強化のため RSA-4096 を使用
認証付き暗号化に AES-256-GCM を使用
整合性の検証機能を提供
パフォーマンスとセキュリティの向上

Encryption V1 (非推奨)

鍵の暗号化に RSA-2048 を使用
bundle の暗号化に 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 command.
設定ファイル内の公開鍵: 次のコマンドを実行する必要があります key save モバイルアプリで使用するために、Capacitor の設定ファイルに公開鍵を保存します。

本番環境では、秘密鍵を安全な場所（環境変数や鍵管理サービスなど）に保存し、セットアップ完了後はローカルプロジェクトから削除してください。

ステップ 2: Capacitor 設定に公開鍵を保存する (必須)

お客様必ずモバイルアプリが bundle を復号できるように、公開鍵を 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

Bundles の暗号化

方法 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: 手動での暗号化ワークフロー

より詳細な制御が必要な場合は、手動で bundle を暗号化できます：

zip bundle を作成します：

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

bundleを暗号化:

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 が bundle upload 時の暗号化に使用します（機密保持が必要）
公開鍵: デバイス上での復号用にアプリ設定に保存します（コミットしても安全です）

秘密鍵の漏洩後にローテーション

秘密鍵の漏洩が疑われる、または確認された場合は、キーペアをローテーションしてください。定期的なカレンダーベースのローテーションは不要です。これは OTA のみの変更ではなく、ネイティブキーの移行となります。

新しいキーペアを生成します：
ターミナルウィンドウ
```
npx @capgo/cli@latest key create
```
新しい公開鍵を Capacitor の設定に保存します：
ターミナルウィンドウ
```
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub
```
ネイティブリリースを同期してリリースします： 実行する npx cap sync、その後、新しい公開鍵を含む新しいネイティブアプリのバージョンを配布します。
新しいネイティブバージョンをターゲットにする： 古いネイティブバイナリを実行中のデバイスは、新しい鍵で暗号化されたアップデートを復号できません。そのため、バージョンターゲティングを使用して、他のデバイスがストアやMDM経由で更新される間、新しい鍵のbundleを新しいネイティブバージョンのみに制限できます。
アップロード用のシークレットを切り替える： ネイティブリリースが公開されたらすぐに、CI内の秘密鍵を置き換え、新しい公開鍵を含むネイティブバージョンをターゲットとしたbundleのみをアップロードしてください。

セキュリティのベストプラクティス

キーのセキュリティ

秘密鍵は決して共有しないでください 環境間やチームメンバー間での共有は厳禁です
異なる鍵を使用してください 環境ごと（dev、staging、production）に異なる鍵を使用します
漏洩時はローテーションを実行: 秘密鍵の漏洩が疑われる、または確認された場合は鍵ペアを交換してください。定期的なスケジュールによるローテーションは必須ではありません
鍵を安全に保管する 適切な鍵管理システムを使用すること

Bundleのセキュリティ

常に検証してください 復号後のbundleの整合性を
モニタリング 異常なダウンロードパターンや失敗がないか
HTTPSの使用 すべてのbundle URLに対して（モバイルアプリでは必須）
実装: 復号失敗時の適切なエラーハンドリング

アクセス制御

アクセス制限 暗号化キーへのアクセスを権限を持つ担当者のみに限定してください
ロールベースのアクセス制御（RBAC）を キー管理操作に適用してください
監査キーの使用状況とアクセス履歴を定期的に監査してください
実装: 適切なバックアップとリカバリ手順を

暗号化のトラブルシューティング

よくある問題

復号エラー:

秘密鍵が暗号化に使用した公開鍵と一致しているか確認してください
以下を確認してください: ivSessionKey が正しいこと
Encryption V2を使用していることを確認してください（V1はサポート終了しました）

鍵に関するエラー:

秘密鍵のフォーマットが正しいか確認してください（PEM形式）
保存や転送の際に鍵が破損していないか確認してください
アプリの設定で鍵に適切な権限が付与されているか確認してください

パフォーマンスの問題:

bundleのサイズが大きいと、暗号化・復号に時間がかかる場合があります
bundleサイズを削減するために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 updatesを活用して暗号化データの転送量を最小限に抑える
画像をWebP形式に変換してbundleサイズを最適化する
bundling前にJavaScriptとCSSファイルを軽量化する
未使用の依存関係とcodeを削除する
古いデバイスや低スペックなデバイスでのパフォーマンスを監視する

次のステップ

詳細を見るカスタムストレージ独自のインフラで暗号化を使用する場合
詳しく見るチャネル環境をまたいで暗号化されたbundleを管理するために
セットアップ CI/CD 連携暗号化されたデプロイを自動化するために

暗号化の次のステップへ

以下を使用している場合： 暗号化 セキュリティとコンプライアンスの計画に使う場合は、以下と連携してください：コンプライアンス実装の詳細は「コンプライアンス」を参照： Capgo セキュリティスキャナー Capgo セキュリティスキャナーの製品ワークフローについては： Capgo セキュリティ Capgo Security の製品ワークフローについて、 Capgo トラストセンター Capgo Trust Center の製品ワークフロー、および組織のセキュリティ Organization Security の実装詳細について。