mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
wenjie
159 lines
6.0 KiB
Markdown
159 lines
6.0 KiB
Markdown
> [README](../project/README.ja.md) に戻る
|
|
|
|
# クレデンシャル暗号化
|
|
|
|
PicoClaw は `model_list` 設定エントリの `api_key` 値の暗号化をサポートしています。
|
|
暗号化されたキーは `enc://<base64>` 文字列として保存され、起動時に自動的に復号されます。
|
|
|
|
---
|
|
|
|
## クイックスタート
|
|
|
|
**1. パスフレーズを設定する**
|
|
|
|
```bash
|
|
export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
|
|
```
|
|
|
|
**2. API キーを暗号化する**
|
|
|
|
`picoclaw onboard` を実行します — パスフレーズの入力を求められ、SSH キーが生成されます。
|
|
その後、次の `SaveConfig` 呼び出し時に、設定内のすべての平文 `api_key` エントリが自動的に再暗号化されます。生成される `enc://` 値は以下のようになります：
|
|
|
|
```
|
|
enc://AAAA...base64...
|
|
```
|
|
|
|
**3. 出力を設定に貼り付ける**
|
|
|
|
```json
|
|
{
|
|
"model_list": [
|
|
{
|
|
"model_name": "gpt-4o",
|
|
"model": "openai/gpt-4o",
|
|
"api_key": "enc://AAAA...base64...",
|
|
"api_base": "https://api.openai.com/v1"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## サポートされる `api_key` 形式
|
|
|
|
| 形式 | 例 | 動作 |
|
|
|------|---|------|
|
|
| 平文 | `sk-abc123` | そのまま使用 |
|
|
| ファイル参照 | `file://openai.key` | 設定ファイルと同じディレクトリから内容を読み取り |
|
|
| 暗号化 | `enc://<base64>` | 起動時に `PICOCLAW_KEY_PASSPHRASE` を使用して復号 |
|
|
| 空 | `""` | そのまま渡される（`auth_method: oauth` で使用） |
|
|
|
|
---
|
|
|
|
## 暗号設計
|
|
|
|
### 鍵導出
|
|
|
|
暗号化には **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 )>
|
|
```
|
|
|
|
| フィールド | サイズ | 説明 |
|
|
|-----------|--------|------|
|
|
| `salt` | 16 バイト | 暗号化ごとにランダム生成；HKDF に入力 |
|
|
| `nonce` | 12 バイト | 暗号化ごとにランダム生成；AES-GCM IV |
|
|
| `ciphertext` | 可変 | AES-256-GCM 暗号文 + 16 バイト認証タグ |
|
|
|
|
GCM 認証タグは暗号文に自動的に付加されます。改ざんがあった場合、破損した平文を返すのではなく、エラーで復号が失敗します。
|
|
|
|
### パフォーマンス
|
|
|
|
| 操作 | 所要時間 (ARM Cortex-A) |
|
|
|------|------------------------|
|
|
| 鍵導出 (HKDF) | < 1 ms |
|
|
| AES-256-GCM 復号 | < 1 ms |
|
|
| **起動時の総オーバーヘッド** | **キーあたり < 2 ms** |
|
|
|
|
---
|
|
|
|
## SSH キーによる二要素セキュリティ
|
|
|
|
SSH 秘密鍵が提供されている場合、暗号を破るには**両方**が必要です：
|
|
|
|
1. **パスフレーズ** (`PICOCLAW_KEY_PASSPHRASE`)
|
|
2. **SSH 秘密鍵ファイル**
|
|
|
|
これは、設定ファイルが漏洩しただけでは、パスフレーズが弱い場合でも API キーを復元できないことを意味します。SSH キーはパスフレーズの強度に関係なく、256 ビットのエントロピー（Ed25519）を提供します。
|
|
|
|
### 脅威モデル
|
|
|
|
| 攻撃者が持っているもの | 復号可能か？ |
|
|
|----------------------|-------------|
|
|
| 設定ファイルのみ | いいえ — パスフレーズ + SSH キーが必要 |
|
|
| SSH キーのみ | いいえ — パスフレーズが必要 |
|
|
| パスフレーズのみ | いいえ — SSH キーが必要 |
|
|
| 設定ファイル + SSH キー + パスフレーズ | はい — 完全な侵害 |
|
|
|
|
---
|
|
|
|
## 環境変数
|
|
|
|
| 変数 | 必須 | 説明 |
|
|
|------|------|------|
|
|
| `PICOCLAW_KEY_PASSPHRASE` | はい（`enc://` 使用時） | 鍵導出に使用するパスフレーズ |
|
|
| `PICOCLAW_SSH_KEY_PATH` | いいえ | SSH 秘密鍵のパス。未設定の場合、`~/.ssh/picoclaw_ed25519.key` から自動検出 |
|
|
|
|
### 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`）により、既存の暗号化値を壊すことなく将来のアルゴリズムアップグレードが可能です。
|