データベース暗号化
Libre WebUI には、機密値をストレージへ書き込む前に保護するアプリケーション層の暗号化サービスがあります。
暗号化方式
バックエンドは Node.js crypto を通じて AES-256-GCM を使用します。暗号鍵は 32 バイトで、64 文字の 16 進文字列として表す必要があります。
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
鍵を生成するには次を実行します。
openssl rand -hex 32
鍵の保存
Libre WebUI は次の順序で鍵を読み込みます。
- 環境の
ENCRYPTION_KEY。 - 選択した
DATA_DIR内に保存された.encryption_keyファイル。 - 新規ストアの場合に限り、新しく生成され、データベースの起動前に
DATA_DIR/.encryption_keyへ永続的に書き込まれた鍵。
環境と永続ファイルの両方に鍵がある場合、両者が一致しなければ起動に失敗します。元の鍵がない既存の暗号化状態もフェイルクローズとなります。Libre が既存ストアに対して代替鍵を生成することはありません。
鍵に関する重要な規則
- データベースと一緒に
ENCRYPTION_KEYをバックアップしてください。 - 暗号化済みの値を移行する計画がない限り、鍵をローテーションしないでください。
- 鍵を失うと、暗号化された値は復旧できません。
- データを再暗号化せずに鍵を変更すると、既存の暗号化値を読み取れなくなります。
保護されるもの
暗号化は、暗号化サービスまたは暗号化ストレージヘルパーを使用するコード経路に適用されます。これらのヘルパーが扱う認証情報や非公開の利用者データなど、機密性の高いアプリケーション値を保護するためのものです。
これはディスク全体の暗号化、SQLite ページ暗号化、または利用者とブラウザ間のエンドツーエンド暗号化ではありません。これらの層にはディスク暗号化と HTTPS を使用してください。
Work データ
アプリケーション層の暗号化によって Work タスク全体が暗号化されるわけではありません。Work のソースファイルとプロジェクト依存関係は、タスク単位の Docker 名前付きボリュームにある通常のファイルです。Work の会話、ツール結果、コマンド出力、タスクメタデータは SQLite に保存されます。一部の認証情報保存経路が暗号化サービスを使用しているだけで、自動的に暗号化されることはありません。
必要に応じて、Docker データルートと DATA_DIR をアクセス制御とディスク暗号化で保護してください。データベース、ENCRYPTION_KEY、管理対象の Work ボリュームを一緒にバックアップしてください。Work タスクをリモートモデルへ送信すると、会話コンテキストや要求されたファイルまたはコマンド出力がそのプロバイダーに開示される場合もあります。ストレージ暗号化によって、このネットワーク境界が変わることはありません。
Docker と Kubernetes
本番環境では安定した鍵を明示的に設定します。
ENCRYPTION_KEY=replace-with-64-hex-characters
DATA_DIR=/data
DATA_DIR を永続ストレージにマウントしてください。Kubernetes では、鍵を Secret に保存し、データを PersistentVolume にマウントします。
トラブルシューティング
鍵の長さが無効
鍵は正確に 64 文字の 16 進数でなければなりません。次のコマンドで新しい鍵を生成します。
openssl rand -hex 32
再デプロイ後にデータを復号できない
同じ ENCRYPTION_KEY を使用し、同じ DATA_DIR ボリュームをマウントしていることを確認してください。
開発環境で新しい鍵が生成された
DATA_DIR/.encryption_key をデータベースと一緒に保持してください。代わりに同じ値を ENCRYPTION_KEY で設定することもできます。両方が存在する場合は一致していなければなりません。