このページは英語のページを機械翻訳したものです。内容は英語のページが正です。 英語のページを読む
鍵暗号化鍵 (KEK) の管理
サーバーは、データベースに保持するシークレットを、データベースには決して保存しない鍵暗号化鍵(KEK)で暗号化します。 このページでは、KEK の生成、保管、バックアップ、ローテーションの仕方、代わりに KMS で保持する方法、そして KEK を失ったときや漏れたときにすることを説明します。 すべての設定は 設定のリファレンス にあります。
- アクターの秘密鍵など、データベースに保存するシークレットは、シークレットごとに生成するデータ暗号化鍵(DEK)を使って AES-256-GCM で暗号化します。 DEK は 鍵暗号化鍵(KEK) でラップし、暗号文の隣に保存します(エンベロープ暗号化)。
- KEK はデータベースに保存しないため、データベースのダンプが漏れただけではシークレットは漏れません。
- 各暗号文は、その DEK をラップした KEK の 鍵 ID を持ちます。
key_manager = localでは、鍵 ID はlocal:に KEK から導いた 16 桁の 16 進数を続けたもので、 同じ KEK からは常に同じ ID になります。ID を自分で割り当てることはありません。 - 暗号文は、保存した行の ID と列の名前に結び付いています。別の行や列にコピーすると復号できなくなります。
- 封印された列は、
my kek statusが表示する名前で、local_account_private_keys.private_key_enc(アクターの秘密鍵)、totp_enrollments.secret_enc(二要素認証のシークレット)、login_provider_secrets.sealed_secret(ログインのプロバイダーのクライアントシークレット)、webhook_secrets.sealed_secret(Webhook の署名のシークレット)、instance_secrets.sealed_secret(メディアプロキシの署名の鍵と、冪等性フィンガープリントの鍵)、tls_acme_accounts.sealed_private_key(サーバーが自分で証明書を取得するときの ACME アカウントの鍵)、tls_certificates.sealed_private_key(それらの証明書の鍵)です。 - パスキーでのログインや外部のプロバイダーを通したログインの状態も同じように封印しますが、保存はしません。ブラウザーが最長 30 分保持します。
- メディアプロキシの URL の署名の鍵(HMAC-SHA256)は、サーバーが最初の起動時に生成してデータベースに保存するランダムな鍵で、ほかのシークレットと同じように暗号化します。
KEK をローテーションしても変わらないため、メディアプロキシの URL はローテーションをまたいでも使え続け、
my kek rewrapはほかのシークレットと一緒にこの鍵もラップし直します。 key_managerはlocal(既定値で、設定kekを使います)、gcpkms(KEK は Google Cloud KMS にとどまります。Google Cloud KMS を参照)、awskms(KEK は AWS KMS にとどまります。AWS KMS を参照)、またはplugin(KEK は自分のプログラムにとどまります。プラグイン を参照)です。
KEK を失ったときに起きること
Section titled “KEK を失ったときに起きること”KEK がなければ、データベースを復元してもアクターの秘密鍵を復号できません。秘密鍵を失うと、ほかのサーバーはそのアクターの署名をもう検証できず、 フェディバースでのアクターの同一性が壊れます(フォロワーとの関係を引き継げません)。KEK はデータベースと同じように大切に扱ってください。
封印されていないものは読めるままです。投稿、アカウント、フォロー、そのほかのデータベースの内容と、ストレージのメディアファイルです。
封印された値はすべて unknown key-encryption key のエラーで失敗します。アクターの秘密鍵、二要素認証のシークレット、
ログインのプロバイダーのクライアントシークレット、Webhook の署名のシークレット、メディアプロキシの署名の鍵、サーバーが自分で取得した証明書の鍵です。
シークレットをラップした KEK の代わりに別の KEK を設定したときや、シークレットをラップした KMS の鍵やプラグインの鍵を無効にしたり破棄したりしたときも同じことが起きます。
KEK を生成する
Section titled “KEK を生成する”32 バイトのランダムな値を標準の base64 でエンコードします。
openssl rand -base64 32openssl がない環境では、head -c 32 /dev/urandom | base64 でもかまいません。生成した値をターミナルの履歴やチケットに残さないでください。
保管して渡す
Section titled “保管して渡す”KEK はシークレットの設定なので、渡せるのは環境変数 MY_KEK か、値を持つファイルのパスである MY_KEK_FILE だけです。設定ファイル(TOML)に書くと起動できません。
| 環境 | 渡し方の例 |
|---|---|
| 自前のホスト(バイナリ / systemd) | 所有者だけが読めるファイル(chmod 600)に置き、MY_KEK_FILE でそれを指します |
| Docker / Compose | Docker のシークレットを /run/secrets/my_kek にマウントし、MY_KEK_FILE=/run/secrets/my_kek を設定します。deploy/docker のファイルは secrets/kek からこれを行います(Docker Compose のファイル)。ローテーションするときは、そのファイルを置き換え、.env に MY_KEK_PREVIOUS を設定します |
| Kubernetes / microk8s | Secret をファイルとしてマウントし、MY_KEK_FILE でそれを指します |
| Cloud Run | Secret Manager のシークレットをファイルまたは環境変数として公開します |
| AWS ECS | Secrets Manager または SSM Parameter Store(SecureString)から渡します |
- web や worker など、すべてのプロセスに同じ KEK を与えてください。
- KEK がログやエラーメッセージに出ることはありません(出るのは鍵 ID だけです)。
my config checkは KEK の形式(32 バイトの base64)を検証し、値を(redacted)と表示します。productionのプロファイルでは、すべてゼロや同じバイトの繰り返しのようにランダムでない KEK でも失敗し、my serveはそのような KEK について警告をログに書きます(本番環境のチェックリスト を参照してください)。
バックアップする
Section titled “バックアップする”データベースと KEK は、別々にバックアップしてください。
- KEK は、データベースのバックアップとは別の場所(パスワードマネージャー、オフラインの媒体、別のアカウントのシークレットストアなど)に保管します。 両方が 1 か所にあると、その場所が漏れたときにデータベースの暗号化が意味をなさなくなります。
- ローテーションの間は、
kek_previousの鍵でラップされた暗号文がデータベースに残っている限り、それらの鍵もバックアップに含めます。 - 復元の手順に KEK を含め、定期的に復元を試してください(バックアップと復元)。データベースを復元したら、バックアップの時点で使っていた KEK(と
kek_previous)を同じ値に設定します。 別の KEK では、シークレットを読むものはすべて、鍵 ID を示すunknown key-encryption keyのエラーで失敗します。
KEK をローテーションする
Section titled “KEK をローテーションする”kek_previous の KEK は復号にだけ使い、新しいシークレットは常に kek で暗号化します。
古いプロセスと新しいプロセスが並んで動くローリングデプロイで、どこかのプロセスが読めない暗号文を作らないよう、2 段階で切り替えます。
- 新しい KEK を生成し、バックアップします。
MY_KEK=<old KEK>とMY_KEK_PREVIOUS=<new KEK>で、すべてのプロセスを再起動します。これで、すべてのプロセスが新しい KEK で復号できます。MY_KEK=<new KEK>とMY_KEK_PREVIOUS=<old KEK>で、すべてのプロセスを再起動します。これ以降、シークレットは新しい KEK でラップされ、古い KEK の暗号文も引き続き読めます。- 保存済みのシークレットを新しい KEK でラップし直します。手順 3 と同じ設定で
my kek rewrapを 1 回実行します(保存済みのシークレットをラップし直す を参照)。 0 で終了すれば、データベースのシークレットで古い KEK を必要とするものはもうありません。 - 古い KEK で発行した短命のログインのトークンが期限切れになるよう、手順 3 から 30 分以上待ってから、
MY_KEK=<new KEK>でkek_previousなしに、すべてのプロセスを再起動します。 手順 4 より前に取ったデータベースのバックアップを保持する間は、古い KEK のバックアップも保持してください。それらを復元するときにまた必要になります。
kek_previous には、カンマ区切りで複数の鍵を指定できます。同じ鍵を 2 回並べたり、kek と同じ鍵を並べたりすると起動できません。
保存済みのシークレットをラップし直す
Section titled “保存済みのシークレットをラップし直す”my kek rewrap は、各シークレットのラップされたデータ暗号化鍵だけを置き換え、暗号文はそのまま保ちます。シークレットを書き出したり表示したりすることはありません。
my kek status # count the stored secrets by the key ID of the KEK that wraps them; decrypts nothingmy kek rewrap # re-wrap every secret that a key of kek_previous wraps with kekmy kek statusは列と鍵 ID ごとに 1 行を表示し、kekの鍵 ID に(current)を付け、最後にkek_previousの鍵をまだ必要とするシークレットがあるかを伝えます。kekでもkek_previousのものでもない鍵 ID は、設定に KEK が欠けていることを意味します。my kek rewrapはシークレットを 100 件ずつ読み、各まとまりを 1 つの短いトランザクションで書きます。列ごとに、ラップし直した数と、すでにkekでラップされていた数を表示します。 サーバーが動いている間にも実行でき、いつ止めても、もう一度実行しても安全です。すでにkekでラップされたシークレットは飛ばし、その間にサーバーが書き換えたシークレットはサーバーが書いたままにします。- ラップし直せないシークレットは変えずに残し、その行の ID とともに報告し、コマンドは 1 で終了します。その KEK が設定されていない
(メッセージが鍵 ID を示します。その KEK を
kek_previousに加えてもう一度実行してください)か、保存された値が壊れているか別の行からコピーされたかのどちらかです。my kek statusがまだその鍵のシークレットを数えている間は、kek_previousから KEK を外さないでください。
Google Cloud KMS
Section titled “Google Cloud KMS”key_manager = gcpkms では、Cloud KMS の対称鍵(目的が ENCRYPT_DECRYPT の CryptoKey)がデータ暗号化鍵をラップし、KEK は Cloud KMS から出ることがありません。
データベースのダンプと設定の両方が漏れても、シークレットは漏れません。復号するには鍵を使う権限が必要だからです。
kms_keyに、バージョンを含まない鍵のリソース名を設定します:projects/{project}/locations/{location}/keyRings/{ring}/cryptoKeys/{key}。248 バイトを超える名前は起動時に拒否されます。 保存したシークレットの鍵 ID は、gcpkms:にこの名前を続けたものです。- サーバーは Application Default Credentials で認証します。Cloud Run ではサービスのサービスアカウント、それ以外では
GOOGLE_APPLICATION_CREDENTIALSです。 - そのサービスアカウントに、(プロジェクトではなく)鍵に対する
roles/cloudkms.cryptoKeyEncrypterDecrypterを、web や worker などすべてのプロセスと、コマンドmy kek statusとmy kek rewrapのために与えます。 これがないと、シークレットの読み取りはロールを示すエラーで失敗します。鍵のバージョンがない、または無効なときも同様に失敗し、これらのエラーは設定を直すまで再試行しません。 クォータのエラーや Cloud KMS を利用できない状態は一時的なもので、シークレットを必要とした処理は再試行します。 - サーバーは Cloud KMS が復号したデータ暗号化鍵を
kms_dek_cache_ttl(既定値10m)の間保持するため、シークレットの読み取りのほとんどは Cloud KMS を呼び出しません。
Cloud KMS で鍵をローテーションする
Section titled “Cloud KMS で鍵をローテーションする”Cloud KMS でのローテーション(手作業、または鍵のローテーション期間による)は、新しいプライマリーのバージョンを加え、古いバージョンを有効なまま残します。
新しいシークレットは新しいバージョンでラップされ、サーバーは各シークレットをラップしたバージョンで復号し、鍵 ID は変わらないため、ローテーションに my kek rewrap は不要です。
シークレットがまだ必要としている古いバージョンを、無効にしたり破棄したりしないでください。無効にした、または破棄したバージョンでラップされたシークレットは、もう復号できません。 Cloud KMS は、あるバージョンがどのシークレットをラップしたかを教えてくれないため、鍵の素材を引退させるには、まずシークレットを新しい鍵に移します。
- 新しい鍵を作成し(同じキーリングでもかまいません)、サービスアカウントにその鍵のロールを与えます。
kms_keyに新しい鍵を、kms_key_previousに古い鍵を設定して、すべてのプロセスを再起動します。これで古い鍵は復号にだけ使われます。- 同じ設定で
my kek rewrapを実行します。my kek statusが古い鍵の ID のシークレットを数えなくなったら、kms_key_previousを外して再起動します。 - そのあとで初めて古い鍵のバージョンを無効にし、手順 3 より前に取ったデータベースのバックアップを保持する間は、それらを復元できる状態にしておきます。それらのバックアップを復元するときにまた必要になります。
AWS KMS
Section titled “AWS KMS”key_manager = awskms では、AWS KMS の対称鍵(鍵仕様 SYMMETRIC_DEFAULT、鍵の用途 ENCRYPT_DECRYPT、カスタマー管理)がデータ暗号化鍵をラップし、KEK は AWS KMS から出ることがありません。
データベースのダンプと設定の両方が漏れても、シークレットは漏れません。復号するには鍵を使う権限が必要だからです。
-
kms_keyに、鍵の ARN(arn:aws:kms:{region}:{account}:key/{key-id})、エイリアス(alias/{name}またはその ARN)、または鍵 ID を設定します。 サーバーは起動時に名前を鍵の ARN に解決し、保存したシークレットの鍵 ID はawskms:にその ARN を続けたものになります。 そのため、エイリアスを別の鍵に向けても次の起動までは何も変わらず、起動後も変わるのは新しいシークレットだけです。すでに保存したシークレットは古い鍵を示し続けるため、古い鍵をkms_key_previousに設定してください(AWS KMS の鍵を引退させる を参照)。 AWS マネージドキー(alias/aws/...)は拒否されます。それを使えるのは、その鍵を所有する AWS のサービスだけです。 -
サーバーは AWS SDK の既定の認証情報チェーンで認証します。ECS ではタスクのロール、EC2 ではインスタンスプロファイル、それ以外では環境(
AWS_ACCESS_KEY_IDなど)または共有の設定ファイルです。 リージョンは鍵の ARN のリージョンです。エイリアスや鍵 ID のときはAWS_REGIONを設定します。 -
web や worker などすべてのプロセスと、コマンド
my kek statusとmy kek rewrapのために、鍵に対するkms:Encrypt、kms:Decrypt、kms:DescribeKeyを許可します。IAM ロールのポリシーの例です。{"Effect": "Allow","Action": ["kms:Encrypt", "kms:Decrypt", "kms:DescribeKey"],"Resource": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"}kms_keyがエイリアスでも、リソースは鍵の ARN です。鍵ポリシーでも、アカウントの IAM のポリシーがアクセスを付与できるようにしておく必要があります(既定の鍵ポリシーはそうなっています)。 -
鍵が存在しない、無効または削除待ちである、または対称暗号化の鍵でないときは、サーバーは起動に失敗します。起動後に権限がなくなったり鍵が無効になったりしたときは、シークレットの読み取りが原因を示すエラーで失敗し、 これらのエラーは設定を直すまで再試行しません。スロットリング(
ThrottlingException)や AWS KMS を利用できない状態は一時的なもので、シークレットを必要とした処理は再試行します。 -
各呼び出しの暗号化コンテキストは、シークレットの行の ID と列の名前を持ちます(
{"my-aad": ...}、base64url で)。CloudTrail はこれを平文で記録しますが、シークレットは含みません。 -
費用: AWS はカスタマー管理の鍵ごとに月額料金(執筆時点で USD 1。さらに、鍵の素材の最初の 2 回のローテーションごとに同額)と、月ごとの無料枠を超えたリクエストごとの料金を請求します (AWS KMS の料金 を参照)。サーバーは AWS KMS が復号したデータ暗号化鍵を
kms_dek_cache_ttl(既定値10m)の間保持するため、 常に配送している 10 のアクターを持つサーバーで、プロセスごとに月に約 43,000 回のリクエストとなり、無料枠を数セント超える程度です。
AWS KMS の鍵を引退させる
Section titled “AWS KMS の鍵を引退させる”AWS KMS の自動の鍵のローテーションは、鍵の ARN とそれまでの鍵の素材を保つため、鍵 ID は変わらず、ローテーションに my kek rewrap は不要です。
鍵の使用をやめるとき、またはエイリアスを別の鍵に向けるときは、まずシークレットを新しい鍵に移します。シークレットがまだ必要としている古い鍵を、無効にしたり削除を予定したりしないでください。その鍵でラップされたシークレットは、もう復号できなくなります。
- 新しい鍵を作成し、ロールがそれを使えるようにします。
kms_keyに新しい鍵を、kms_key_previousに古い鍵(エイリアスではなくその ARN)を設定して、すべてのプロセスを再起動します。これで古い鍵は復号にだけ使われます。- 同じ設定で
my kek rewrapを実行します。my kek statusが古い鍵の ID のシークレットを数えなくなったら、kms_key_previousを外して再起動します。 - そのあとで初めて古い鍵を無効にし、手順 3 より前に取ったデータベースのバックアップを保持する間は、その鍵を保持します。それらのバックアップを復元するときにまた必要になります。
key_manager = plugin では、自分の プラグイン が KEK を Vault や HSM など自ら選んだ場所に保持し、サーバーのためにデータ暗号化鍵をラップします。
プラグインは KEK と同じ信頼境界の中にあります。 プラグインはすべてのデータ暗号化鍵を平文で見るため、プラグインやその動作するホストを掌握した人は、アクターの秘密鍵を含め、サーバーのすべてのシークレットを読めます。 プラグインには KEK と同じ保護を与えてください。その接続先を設定ファイルと環境以外のどの設定からも変えられないのも、そのためです。
MY_KEY_MANAGER=pluginMY_PLUGIN_KEY_MANAGER_ADDRESS=unix:///run/my/key_manager.sock- 接続先は
unix://かhttps://です。鍵が平文で行き来することになるため、サーバーはループバックでもhttp://を拒否します。接続先のそのほかの設定は プラグイン にあります。 - サーバーをプラグインに向ける前に、
my plugin test --kind key_manager <address>を実行してください(プラグインをテストする)。このコマンドがラップするのは、自分で作って捨てる鍵だけです。 - 保存したシークレットの鍵 ID は、
plugin:に、プラグインが自分の KEK に付けた ID を続けたものです。その ID は 1 から 248 バイトの、表示可能な ASCII です。 - 保存したシークレットがまだ示している KEK は、すべて保持してください。 プラグインでのローテーションは、次のラップで新しい ID として表れます。それより前にラップされたシークレットは古い ID を示し続け、プラグインはそれらを引き続き開けなければなりません。
my kek rewrapはそれらを現在の ID に移し、my kek statusは残っているものを数えます。 - プラグインと KMS は一緒には使えません。プラグインでは
kms_keyとkms_key_previousが拒否され、key_manager = gcpkmsまたはawskmsではplugin_key_manager_addressが拒否されます。
サーバーの起動時
Section titled “サーバーの起動時”すべてのプロセスと、my kek status のようにデータベースを開くすべての my のコマンドは、何よりも先に次のことを行います。失敗すると起動が止まるのは、この種類のプラグインだけです。
- プラグインに、現在の KEK の ID を問い合わせます。
- 捨てるためのランダムな鍵で自己テストを行います。ラップとアンラップで鍵が戻ること、異なる認証データでのアンラップが
OUTCOME_DECRYPTを返すこと、同じ鍵を 2 回ラップした結果が異なること、ラップした値が鍵を含まないことを確かめます。
応答しない、または 503 を返すプラグインは、サーバーのあとに起動するサイドカーのために、最長 30 秒再試行します。そのあとはプロセスがエラーで終了します。誤った応答や、トークンを拒否されたなどそのほかの失敗では、すぐに止まります。自己テストは、認証データを無視したり鍵をそのまま通したりするプラグインを止めるためのもので、待っても直らないからです。
プラグインに到達できないとき
Section titled “プラグインに到達できないとき”サーバーはフェイルクローズで動きます。拒否された呼び出しやタイムアウトした呼び出し、空・不明・不正な形式の応答など、何がうまくいかなくても、鍵を必要とした操作はエラーで失敗します。シークレットを平文で保存することも、ローカルの KEK や別の鍵に切り替えることも、失敗を結果として扱うこともありません。このように失敗したジョブはあとで再試行し、リクエストはそれを行った人に対して失敗します。失敗した呼び出しはそれぞれ、種類と Connect のコードごとに my.plugin.failures に数えられ、ログには鍵、認証データ、ラップした値も、プラグインが返した内容も残りません。
ラップは決してキャッシュせず、少し前に封印した値もキャッシュには何もないため、次のことはすぐに止まります。
- アクターの鍵を生成する、アカウントの作成。
- 二要素認証の設定と、手続きの状態を封印して保持する、パスキーの登録とパスキーでのログイン。
- 外部のプロバイダーを通したログインと、プロバイダーのクライアントシークレットの保存。
- Webhook の登録と
my kek rewrap。
保存したシークレットの読み取りが動くのは、プロセスが以前の読み取りで得たデータ暗号化鍵を保持している間だけで、最長 kms_dek_cache_ttl(既定値 10m)です。そのあと、またはまだ読んでいないシークレットについては、次のことも止まります。
- アクターの秘密鍵を必要とする、連合の配送と署名付きの取得。配送は、プラグインが戻ればジョブの再試行で追いつきます。
- ログイン時の二要素認証のコードの確認。
- Webhook の配送。
再起動は上で説明したとおり止まるため、プラグインの障害を直すためにサーバーを再起動しないでください。動いているサーバーはキャッシュでまかなえるものを提供し続けますが、再起動したサーバーはプラグインが応答するまで何も提供しません。タイムラインを読むことや投稿など、シークレットを必要としないものは続きます。メディアプロキシの署名の鍵は起動時に読み、メモリーにとどまります。更新したクライアント証明書や CA のファイルにも再起動は不要です。ファイルが変わると、サーバーはそれらを読み直します(プラグイン)。
RPC は my.plugin.key_manager.v1.KeyManagerService のもので、既定の期限は 5 秒、メッセージは行きも帰りもそれぞれ最大 128 KiB です。
POST /my.plugin.key_manager.v1.KeyManagerService/Describe{}{"outcome":"OUTCOME_OK","keyId":"transit/my-kek-3"}
POST /my.plugin.key_manager.v1.KeyManagerService/WrapKey{"dek":"<base64>","aad":"<base64>"}{"outcome":"OUTCOME_OK","keyId":"transit/my-kek-3","wrapped":"<base64>"}
POST /my.plugin.key_manager.v1.KeyManagerService/UnwrapKey{"keyId":"transit/my-kek-3","wrapped":"<base64>","aad":"<base64>"}{"outcome":"OUTCOME_OK","dek":"<base64>"}keyIdはプラグイン自身の ID で、plugin:を含みません。UnwrapKeyは現在のものより古い ID を示すことがあります。wrappedは 1 から 65,535 バイトで、鍵を含んではいけません。同じ鍵を 2 回ラップした結果は異なります。aadは行の ID と列の名前を持つ認証データで、UnwrapKeyは、それがWrapKeyの受け取ったものでなければ失敗しなければなりません。これが、シークレットを別の行にコピーできないようにしているものです。dek、aad、wrappedは決してログに書かないでください。
outcome |
意味 |
|---|---|
OUTCOME_OK |
呼び出しが成功した |
OUTCOME_UNKNOWN_KEY |
UnwrapKey: プラグインが keyId の KEK を持っていない |
OUTCOME_DECRYPT |
UnwrapKey: wrapped または aad の認証に失敗した |
鍵の保管先に届かないときなど、答えられないときは HTTP または Connect のエラーを返してください。そのときに OUTCOME_DECRYPT や OUTCOME_UNKNOWN_KEY を返さないでください。サーバーにとって、これらは値そのものが不正であることを意味します。サーバー自身は呼び出しを再試行しないため、プラグインはジョブから同じ呼び出しをもう一度受けることがあります。
ローカルの KEK と KMS の間で移行する
Section titled “ローカルの KEK と KMS の間で移行する”鍵 ID は、それをラップした鍵の管理方式の種類(local:、gcpkms:、awskms:、plugin:)で始まります。サーバーは新しいシークレットを現在の key_manager でラップし、
保存した各シークレットをその鍵 ID が示す鍵の管理方式でアンラップするため、ローカルの KEK と KMS の間の移行は、種類をまたいだローテーションです。
- KMS では、
kekとkek_previousは復号にだけ使います。まだローカルの KEK でラップされているシークレットを開き、新しいシークレットはすべてkms_keyでラップします。kms_key_previousは同じ KMS のそれまでの鍵を並べたもので、これも復号にだけ使います。 key_manager = localでは、kms_keyとkms_key_previousを設定していれば、それらは復号にだけ使います。まだ KMS でラップされているシークレットを開きます。- ローカルの KEK から KMS へ:
- Google Cloud KMS または AWS KMS のとおりに、鍵を作成して権限を与えます。
key_manager = gcpkmsまたはawskmsとし、kms_keyにその鍵を設定し、現在の KEK をkekからkek_previousに移して、すべてのプロセスを再起動します。 これでシークレットは KMS でラップされ、ローカルの KEK でラップされたものも引き続き開けます。- 同じ設定で
my kek rewrapを実行します。 my kek statusがlocal:の鍵 ID のシークレットを数えなくなったら、kek_previousを外して再起動します。手順 3 より前に取ったデータベースのバックアップを保持する間は、KEK のバックアップも保持してください。
- KMS からローカルの KEK に戻すときは、同じことを逆向きに行います。
key_manager = localと新しいkekを設定し、kms_keyは設定したまま(これで復号にだけ使われます)にして、my kek rewrapがすべてのシークレットを移し、my kek statusがgcpkms:またはawskms:の鍵 ID のシークレットを数えなくなるまで待ちます。 このとき、kms_keyとkms_key_previousの鍵はすべて同じ KMS のものでなければなりません。 - あるクラウドの KMS から別のクラウドの KMS に移るには、まずローカルの KEK に移ってから、もう一方の KMS に移ります。直接の移行はありません。
- プラグインも、ローカルの KEK だけを経由して同じように移行します。
- プラグインへは、
key_manager = pluginとplugin_key_manager_addressを設定し、現在の KEK をkekからkek_previousに移して、すべてのプロセスを再起動してから、my kek rewrapを実行します。my kek statusがlocal:の鍵 ID のシークレットを数えなくなったら、kek_previousを外して再起動します。 - プラグインからは、
key_manager = localと新しいkekを設定し、plugin_key_manager_addressは残したまま(これで復号にだけ使われます)すべてのプロセスを再起動してから、my kek rewrapを実行します。my kek statusがplugin:の鍵 ID のシークレットを数えなくなったら、接続先を外して再起動します。それまでは、プラグインはラップを含む 起動時の確認 に引き続き通らなければなりません。
- プラグインへは、
- サーバーは KMS またはプラグインが復号したデータ暗号化鍵を
kms_dek_cache_ttl(既定値10m、最大kms_dek_cache_entries件、既定値1024)の間保持するため、 使用中のシークレットが KMS やプラグインに届くのは、期間とプロセスごとに約 1 回です。どちらかの設定を0にするとキャッシュを無効にします。
KEK が漏れたとき
Section titled “KEK が漏れたとき”漏れたのが KEK だけなら、上のとおりにローテーションします。KEK とデータベースの両方が漏れたおそれがあるときは、ローテーションでは守れません。 データベースにあるアクターの秘密鍵はすでに読める状態なので、アクターの鍵そのものを作り直す必要があります。
Web Push の VAPID の鍵
Section titled “Web Push の VAPID の鍵”Web Push は、サーバーの VAPID の鍵(P-256、RFC 8292)で署名します。これは KEK とは別のシークレットで、データベースには保存しません。
my config vapid-keyで鍵ペアを作成し、すべてのプロセスに秘密鍵(vapid_private_key = ...の値)をMY_VAPID_PRIVATE_KEYまたはMY_VAPID_PRIVATE_KEY_FILEで与えます。 サーバーは秘密鍵から公開鍵を導いてクライアントに渡すため、公開鍵を設定する必要はありません。- 設定しないと Web Push は無効になり、クライアントはそれを提示しません。
productionのプロファイルでは、my config checkとmy serveの起動がそのことを警告します。 - ブラウザーは購読を公開鍵に結び付けるため、鍵を変えると既存の購読への配信が止まります。利用者が設定でプッシュ通知をもう一度オンにすると、クライアントは新しい鍵でもう一度購読します。 漏れたのでない限り、鍵を変えないでください。漏れたときは新しい鍵に切り替え、利用者に通知をもう一度オンにするよう頼んでください。
LLM とコーディングエージェント向け:llms.txt,llms-full.txt, llms-small.txt