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

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

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

キーを指定して暗号化

デフォルトの .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: 復号化ファイルのファイル名

使用例

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

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

# キーを生成
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

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

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

本番環境で復号化:

# 環境変数またはシークレット管理システムからキーを取得
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

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

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

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

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

本番環境でのキーの管理: 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の環境変数暗号化機能にインスパイアされています:

kozo / cryptenv

Maintainers

Details