Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-013 title: マスターキーの取得には、構成済みの1つのキーソース権限を使用する date: 2026-07-25 status: 提案 relates-to:

  • https://github.com/zeroclaw-labs/zeroclaw/issues/9127
  • https://github.com/zeroclaw-labs/zeroclaw/pull/9194
  • docs/book/src/security/model.md
  • docs/book/src/architecture/config-lifecycle.md
  • crates/zeroclaw-config/src/secrets.rs

ADR-013: マスターキーの取得では、構成済みの単一のキーソース権限を使用する

コンテキスト

シークレットの暗号化が有効な場合、ZeroClaw は通常、空でない #[secret] の値を enc2: 形式で、設定ルートごとに 1 つのマスターキーを使って永続化します。現在の実装では、そのキーを .secret_key から取得します。これはファイルシステムの権限で保護された平文の 16 進数ファイルです。このデフォルトは、ローカル開発や保護されたキー素材をマウントするデプロイでは実用的ですが、オペレーティングシステムのキーチェーン、パスフレーズから導出されたキー、外部のシークレットシステムには対応できません。

キーの場所は、契約の一部にすぎません。すべての本番コンシューマーは、どのソースがキーを管理するのか、初回使用時のプロビジョニングと一時的な利用不能をどのように区別するのか、また設定されたソースが想定されるキーを提供できない場合に何が起きるのかについて合意していなければなりません。正規のシークレット境界の外で直接 .secret_key を読み取ること、別のソースへの暗黙的なフォールバック、または安全でないバックエンド切り替えによって、既存の暗号文が読み取れなくなったり、デプロイメントで意図された保護が弱まったりする可能性があります。

RFC #9127 は、段階的なキーソースアーキテクチャを定義します。初期実装 #9194 では、ファイルソースを分離し、構成と暗号文のセマンティクスを維持しながら、アトミックかつ置換なし、追従なしのキー・ファイル公開を堅牢化します。この堅牢化にはターゲット固有の低レベル依存関係が必要になる場合があります。#9460 は、Windows における作成時 ACL の境界に関する残りの課題を追跡しています。この記録は、設定された非ファイルソースや移行サポートが提供済みであると主張することなく、永続的な目標を記録するものです。

決定

1 つの正規キーソース境界を使用する

マスターキーの取得は、設定およびシークレットサブシステム内の KeySource 境界が担います。SecretStore と、デプロイメントキー素材を使用するその他すべての本番環境コンシューマーは、.secret_key を直接読み取ったり、プラットフォームストアを呼び出したり、独自に取得したキーを直接キャッシュしたりするのではなく、その境界を使用する必要があります。

1回のデプロイメントで、設定されたソースのうち権威となるのは1つだけです。ファイルソースは、引き続き後方互換性のあるデフォルトです。別のソースを追加しても、enc2: の暗号文形式や ChaCha20-Poly1305 の暗号化契約を変更してはなりません。

ソース選択は、正規の型付き Config から解決され、Config::install_root_dir() を基準とします。バイナリおよびランタイム構築層は、プロセス世代ごとに共有される単一のソース基準を構築し、それを SecretStore とその他すべてのキー利用側に注入します。利用側はその基準をクローンできますが、ルートを選択したり、保持されたシークレット設定のスナップショットから基準を再構築したり、バックエンドのマテリアルを直接読み取ったりしてはなりません。独立したプロセスは、同じ設定済みの基準を決定論的に解決します。バックエンドキャッシュはプロセスローカルにとどまります。

非暗号化コンシューマーがソースへのスコープ付きアクセスを受けるか、用途固有のサブキーを導出するかは、別個のセキュリティ上の決定事項です。このADRは正規の取得を要求しますが、TUI ID署名や別のプロトコルに対する導出方法や互換性契約を選択するものではありません。その決定が記録されるまで、非暗号化コンシューマーは生の暗号化マスターキーを暗黙的に再利用してはなりません。

境界では、同期操作の実行中に限り鍵バイト列を公開できます。これは正確性とライフタイムに関する制約であり、サンドボックスではありません。その操作内で実行されるコードは、バイト列をコピーすることもできます。実装では、プラットフォームと依存関係モデルで許容される場合、コピーを最小限に抑え、一時的なデータを消去する必要があります。

この生キー境界は、エクスポート可能な32バイトのキーマテリアルを返せるソースにのみ適用されます。エクスポート不可能なセキュアエレメントは、キーのバイト列ではなく暗号操作を公開するため、別個の操作ベースの境界とアーキテクチャ上の判断が必要です。

プロビジョニング状態と可用性を分離する

ソースでは、次の状態を区別する必要があります:

  • ローカルの鍵マテリアルが存在し、検証できる;
  • ローカルキーマテリアルの初期化が必要、または
  • 鍵マテリアルは外部からプロビジョニングされるため、ローカルで意味のある存在確認はできません。

ローカルプロビジョニングプローブは、予期せずヘルパーを実行したり、ネットワークサービスに接続したり、ユーザーにプロンプトを表示したり、キーチェーンのロックを解除したりしてはなりません。実際のキーへのアクセスは別の操作であり、設定されたソースを利用できない、ロックされている、設定が誤っている、または誤ったキーを返すことが原因で失敗する場合があります。

初期化によって新しい鍵マテリアルが作成されるのは、ソースがそれを明示的にサポートしている場合に限られます。ファイルの初期化では、既存のマテリアルを置き換えたり、シンボリックリンクによるリダイレクトを受け入れたりすることなく、完全でアクセス制限のあるファイルを公開する必要があります。ローテーションは初期化ではなく、独自のガード付き操作が必要です。

権限を変更せずにフェイルクローズする

有効化された機能で設定済みのキーが必要であり、ソースからそのキーを提供できない場合、その機能の起動または認証情報操作は、安全なソース固有の診断情報を伴って失敗しなければなりません。ZeroClaw は .secret_key に暗黙的にフォールバックしたり、代替キー素材を生成したり、別のバックエンドを試したりしてはなりません。生のキーのバイト列や、それらを含む可能性のあるヘルパーの出力を、ログまたは返されるエラーに含めてはなりません。

構成されたソースの取得に失敗した場合、署名なしの TUI 識別情報を暗黙的に選択してはならない。署名なしの TUI 識別情報のサポートを継続する場合、それは独自の脅威モデル、診断、およびテストを備えた、オペレーターが明示的に選択するポリシーでなければならない。署名付きの識別情報が構成されている場合、その鍵の取得に失敗すると、該当する起動または接続を失敗させる。TUI の署名がスコープ付きのソースアクセスを受けるか、用途固有の鍵を導出するかは、別個のセキュリティ上の判断である。

ソース実装は、脅威モデルと運用上の依存関係を明記しなければなりません。オペレーティングシステムのキーチェーンは、侵害されたZeroClawプロセスを保護しません。パスフレーズソースは、ユーザー操作とパスワードの強度に依存します。外部ヘルパーは、その実行可能ファイル、環境、トランスポート、上流のシークレットシステムに依存します。バックエンド名だけでは、セキュリティを保証できません。

外部ヘルパーを実装する場合は、シェルを介さず、明示的に設定された絶対パスの実行可能ファイルを実行します。初期契約では引数を受け付けません。後から引数をサポートするには別途レビューが必要であり、シェルコマンドを解析するのではなく、値を個別に表現しなければなりません。実行にはタイムアウトを設け、タイムアウト時または終了時に実装が子プロセスを保持して回収します。ヘルパーは、64文字の小文字の16進数として表される32バイトのキーをちょうど1つ返します。生の stdout と stderr がログや返されるエラーに含まれることはありません。初期契約ではプロセス環境を継承するため、その露出について文書化しなければなりません。再試行とキャッシュには上限を設け、期限切れの鍵マテリアルを消去し、更新に失敗した場合もフェイルクローズを維持します。

マイグレーションとローテーションを分離する

同じマスターキーを別のソースに移動するのは移行です。新しいキーを生成して保護されたすべての値を再暗号化するのはローテーションです。これらは失敗時およびロールバック時のルールが異なるため、1つの汎用的なバックエンド変更として扱ってはなりません。

暗号化された値が存在する状態で設定済みのソースを変更するには、検証済みの移行パスが必要です。移行ツールが提供されるまで、ZeroClaw は、既存の enc2: 値を復号するキーにアクセスできることを証明できないソース変更を拒否しなければなりません。移行では、新しいソースへの書き込みと読み戻しが正常に完了するまで、古いソースを保持する必要があります。ローテーションでは、すべての値の再暗号化が完了し、新しい設定がアトミックにコミットされるまで、古いキーと元の設定を保持する必要があります。

zeroclaw secrets migrate は、最初のファイル以外のソースを選択可能にする変更と同時、またはそれ以前にリリースされなければならない。後続の各ソースについては、運用担当者が選択できるようになる前に、サポートされた移行パスを用意しなければならない。純粋にパスフレーズから導出されるソースなど、既存のマスターキーをインポートできないソースには、同一キーでの移行が可能であるかのように扱うのではなく、別途レビューされたローテーションパスが必要となる。

移行とローテーションでは、SecretStore の暗号文を永続的に保持するすべての保管先をインベントリに登録する必要があります。初期インベントリには、構成 TOML と生成または移行された構成出力、<install>/auth-profiles.json、<install>/auth-<provider>-pending.json、<install>/otp-secret、<data>/webauthn_credentials.json が含まれます。enc2: 値を書き込む将来の永続ストアも、同じインベントリに追加されます。永続的な暗号文形式を追加せずにストアを構築しても、別の移行対象となる保管先は生じません。

この決定では、キーソースの選択は稼働中の状態に即時適用されません。保存されたソースの変更が有効になるのは、移行の検証後にデーモンの完全なリロードまたはプロセスの再起動を行った場合のみです。今後のライブハンドオフでは、世代フェンシングを別の実装決定で定義する必要があります。

安全順序の境界を採用する

ファイルソースの抽出を、設定や暗号文のセマンティクスを変更せずに最初に導入する。対象固有の低レベル依存関係を伴うキー ファイルの作成と公開の強化は可能だが、互換性のベースラインとしてファイルバックエンドは維持する。次に、本番コンシューマーとフェイルクローズなソース選択を、その境界の背後に移す。移行ツールは、遅くとも最初に選択可能となる非ファイルソースまでに導入しなければならない。その後、非ファイルソースを、ソース固有の脅威モデル、移行サポート、テストとともに、一度に1つずつ導入する。一般的なキー ローテーションは、引き続き別途レビューするフローとする。

この ADR は、以下の条件をすべて満たすまで提案中のままです：

  • ファイルソースは、リテラルな抽出前キーおよび暗号文フィクスチャに対して既存の .secret_key と enc2: データとの互換性を維持し、置換やシンボリックリンクの追従を行わずに新しいキーファイルを公開します。
  • 正規の型付き設定がソースとインストール ルートを選択し、バイナリまたはランタイムのアセンブリ層が、プロセス世代ごとに 1 つの共有権限をすべての本番コンシューマーに注入する;
  • 設定ではソースを厳密に1つだけ選択し、ファイルソースを互換性のあるデフォルトとし、フォールバックや置換キーの生成を行わずにフェイルクローズします;
  • 設定済みソースの障害によって、署名なしの TUI アイデンティティを暗黙的に有効化してはならない。維持される署名なしモードは、固有の脅威モデル、診断、テストを伴う、オペレーターによる明示的なポリシーである。
  • プロビジョニングプローブは、マテリアルが存在しない場合と検査の失敗を区別し、成功した with_key アクセスはコールバックを正確に 1 回呼び出す。境界テストでは、コールバックが 0 回または複数回呼び出されるケース、ならびに権限エラーや一時的な検査失敗を網羅する。
  • zeroclaw secrets migrate は、最初のファイル以外のソースが選択可能になる前に利用でき、後続の各ソースには有効化前に検証済みの移行またはローテーション手順が用意されていること。
  • 少なくとも 1 つのサポート対象の非ファイルソースによって、ファイル実装以外でも境界が機能することが実証されること；かつ
  • 永続化された暗号文の完全なインベントリを復号できるか、文書化されたアトミックでロールバック可能な移行が正常に完了しない限り、ソースの切り替えは拒否されます。

結果

肯定的な結果:

  • デスクトップ、サーバー、コンテナーへのデプロイでは、動作環境に適したエクスポート可能な鍵認証機関を選択できます。
  • すべての認証情報コンシューマーは、唯一の信頼できる情報源と、フェイルクローズドなライフサイクルを共有します。
  • 既存のファイルベースのデプロイは、引き続き互換性の基準となります。
  • マイグレーション、ローテーション、通常の起動を暗黙に混同することはできません。

否定的な結果:

  • 起動時に、各ソースについてプロビジョニングと可用性のセマンティクスを明示的に指定する必要があります。
  • ファイル以外のソースは、ファイルソースにはないプラットフォーム依存関係、プロンプト、外部プロセスの動作、またはサービスの可用性を追加します。
  • 暗号化された値がすでに存在する場合、バックエンドの切り替えは単純な設定変更では行えません。
  • 移行では、境界を完成させる前に、本番コンシューマー全体にあるキー ファイルの直接読み取りを見つけて削除する必要があります。

参照