README

CakePHP用の環境変数ファイル暗号化・復号化プラグインです。

特徴

• XChaCha20-Poly1305 (libsodium) を使用した安全な暗号化
• Base64エンコードされたキーのサポート
• 複数の環境ファイル (.env.production, .env.staging など) のサポート
• CakePHPのコマンドラインインターフェースとの統合

要件

• CakePHP 5.x
• PHP 8.1以上
• libsodium 拡張 (通常はPHP 7.2以降でデフォルトで有効)

インストール

Composerを使用してプラグインをインストールします:

composer require kozo/cryptenv

プラグインを有効化するには、src/Application.php の bootstrap() メソッドに以下を追加してください:

$this->addPlugin('Cryptenv');

または、CakePHPのプラグインコマンドを使用して有効化できます:

bin/cake plugin load Cryptenv

使用方法

暗号化キーの生成

まず、暗号化に使用する32バイトのランダムキーを生成します:

php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;"

このコマンドは base64: プレフィックス付きのキーを出力します。このキーを安全に保管してください。

環境ファイルの暗号化

対話モード（キーなしで実行）

キーを指定せずに実行すると、対話モードで新しいキーを生成できます:

bin/cake env encrypt --env production

対話モードでは以下の選択肢が表示されます:

1. 新しい暗号化キーを生成するか確認
2. 生成されたキーをすぐに使用して暗号化するか確認

キーを指定して暗号化

デフォルトの .env ファイルを暗号化:

bin/cake env encrypt --key base64:YOUR_BASE64_ENCODED_KEY

特定の環境ファイルを暗号化:

bin/cake env encrypt --key base64:YOUR_BASE64_ENCODED_KEY --env production

オプション:

• --key, -k: 暗号化キー（省略時は対話モード）
• --env, -e: 環境名 (例: production, staging)
• --force, -f: 既存の暗号化ファイルを上書き
• --prune, -p: 暗号化後に元のファイルを削除

環境ファイルの復号化

暗号化されたファイルを復号化:

bin/cake env decrypt --key base64:YOUR_BASE64_ENCODED_KEY

特定の環境ファイルを復号化:

bin/cake env decrypt --key base64:YOUR_BASE64_ENCODED_KEY --env production

カスタムパスとファイル名で復号化:

bin/cake env decrypt --key base64:YOUR_BASE64_ENCODED_KEY --path /path/to/output --filename .env.local

オプション:

• --key, -k: 復号化キー (必須)
• --env, -e: 環境名 (例: production, staging)
• --force, -f: 既存のファイルを上書き
• --path: 復号化ファイルの出力先パス
• --filename: 復号化ファイルのファイル名

使用例

本番環境への展開ワークフロー

1. 開発環境で環境ファイルを暗号化:

   # キーを生成
   php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;" > encryption_key.txt
   
   # 本番用の .env.production を暗号化
   bin/cake env encrypt --key $(cat encryption_key.txt) --env production

2. 暗号化されたファイルをバージョン管理にコミット:

   git add config/.env.production.encrypted
   git commit -m "Add encrypted production environment file"

3. 本番環境で復号化:

   # 環境変数またはシークレット管理システムからキーを取得
   bin/cake env decrypt --key $ENCRYPTION_KEY --env production

複数環境の管理

# ステージング環境を暗号化
bin/cake env encrypt --key base64:STAGING_KEY --env staging

# 本番環境を暗号化
bin/cake env encrypt --key base64:PRODUCTION_KEY --env production

# それぞれを復号化
bin/cake env decrypt --key base64:STAGING_KEY --env staging
bin/cake env decrypt --key base64:PRODUCTION_KEY --env production

セキュリティに関する注意事項

1. 暗号化キーを安全に保管: 暗号化キーは絶対にバージョン管理システムにコミットしないでください。環境変数やシークレット管理システム (AWS Secrets Manager, HashiCorp Vault など) を使用してください。

2. 暗号化されていないファイルを .gitignore に追加:

   config/.env
   config/.env.*
   !config/.env.*.encrypted
   !config/.env.example
   

3. 本番環境でのキーの管理: CI/CDパイプラインやデプロイメントスクリプトで暗号化キーを環境変数として設定してください。

技術詳細

暗号化アルゴリズム

このプラグインは XChaCha20-Poly1305 (AEAD) を使用しています:

• XChaCha20: ストリーム暗号 (ChaCha20の拡張版で、より大きなnonceをサポート)
• Poly1305: メッセージ認証コード (MAC)
• AEAD: 認証付き暗号化により、データの機密性と完全性を保証

ファイル形式

暗号化されたファイルは以下の形式で保存されます:

base64_encode(nonce + ciphertext)

• nonce: 24バイトのランダムな値 (SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES)
• ciphertext: 暗号化されたデータ + 認証タグ

トラブルシューティング

"The encryption key must be 32 bytes" エラー

暗号化キーは正確に32バイトである必要があります。base64: プレフィックスを使用する場合、プレフィックスの後の部分をbase64デコードした結果が32バイトである必要があります。

"Decryption failed" エラー

• 正しい暗号化キーを使用しているか確認してください
• 暗号化されたファイルが破損していないか確認してください
• 暗号化と復号化で同じキーを使用しているか確認してください

ライセンス

このプラグインはMITライセンスの下で公開されています。

参考

このプラグインはLaravelの環境変数暗号化機能にインスパイアされています:

• Laravel EnvironmentEncryptCommand
• Laravel EnvironmentDecryptCommand