README に戻る

クレデンシャル暗号化

PicoClaw は model_list 設定エントリの api_key 値の暗号化をサポートしています。 暗号化されたキーは enc://<base64> 文字列として保存され、起動時に自動的に復号されます。

クイックスタート

1. パスフレーズを設定する

export PICOCLAW_KEY_PASSPHRASE="your-passphrase"

2. API キーを暗号化する

picoclaw onboard を実行します — パスフレーズの入力を求められ、SSH キーが生成されます。 その後、次の SaveConfig 呼び出し時に、設定内のすべての平文 api_key エントリが自動的に再暗号化されます。生成される enc:// 値は以下のようになります：

enc://AAAA...base64...

3. 出力を設定に貼り付ける

{
  "model_list": [
    {
      "model_name": "gpt-4o",
      "model": "openai/gpt-4o",
      "api_key": "enc://AAAA...base64...",
      "api_base": "https://api.openai.com/v1"
    }
  ]
}

サポートされる api_key 形式

暗号設計

鍵導出

暗号化には HKDF-SHA256 を使用し、SSH 秘密鍵を第二要素とします。

sshHash = SHA256(ssh_private_key_file_bytes)
ikm     = HMAC-SHA256(key=sshHash, message=passphrase)
aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)

暗号化

AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)

ワイヤーフォーマット

enc://<base64( salt[16] + nonce[12] + ciphertext )>

GCM 認証タグは暗号文に自動的に付加されます。改ざんがあった場合、破損した平文を返すのではなく、エラーで復号が失敗します。

パフォーマンス

SSH キーによる二要素セキュリティ

SSH 秘密鍵が提供されている場合、暗号を破るには両方が必要です：

1. パスフレーズ (PICOCLAW_KEY_PASSPHRASE)
2. SSH 秘密鍵ファイル

これは、設定ファイルが漏洩しただけでは、パスフレーズが弱い場合でも API キーを復元できないことを意味します。SSH キーはパスフレーズの強度に関係なく、256 ビットのエントロピー（Ed25519）を提供します。

脅威モデル

環境変数

SSH キーの自動検出

PICOCLAW_SSH_KEY_PATH が設定されていない場合、PicoClaw は専用キーを探します：

~/.ssh/picoclaw_ed25519.key

この専用ファイルにより、ユーザーの既存の SSH キーとの競合を回避します。 picoclaw onboard を実行すると自動的に生成されます。

os.UserHomeDir() はクロスプラットフォームのホームディレクトリ解決に使用されます（Windows では USERPROFILE、Unix/macOS では HOME を読み取ります）。

注意： SSH キーファイルはクレデンシャル暗号化に必須です。キーが見つからず PICOCLAW_SSH_KEY_PATH も設定されていない場合、暗号化/復号は失敗します。picoclaw onboard を実行してキーを自動生成してください。

移行

唯一の秘密情報は PICOCLAW_KEY_PASSPHRASE と SSH 秘密鍵ファイルであるため、移行は簡単です：

1. 設定ファイルを新しいマシンにコピーします。
2. PICOCLAW_KEY_PASSPHRASE を同じ値に設定します。
3. SSH 秘密鍵ファイルを同じパスにコピーします（または PICOCLAW_SSH_KEY_PATH を新しい場所に設定します）。

再暗号化は不要です。

セキュリティに関する考慮事項

• パスフレーズと SSH キーの両方が必須です。 SSH キーは第二要素として機能します — これがなければ暗号化/復号は失敗します。キーが存在しない場合は picoclaw onboard を実行して生成してください。
• SSH キーは実行時に読み取り専用です。 PicoClaw は SSH キーファイルへの書き込みや変更を行いません。
• 平文キーは引き続きサポートされます。 enc:// を使用しない既存の設定は影響を受けません。
• enc:// 形式はバージョン管理されています。 HKDF info フィールド（picoclaw-credential-v1）により、既存の暗号化値を壊すことなく将来のアルゴリズムアップグレードが可能です。