Quay lại README

Mã hóa Thông tin Xác thực

PicoClaw hỗ trợ mã hóa các giá trị api_key trong các mục cấu hình model_list. Các khóa đã mã hóa được lưu trữ dưới dạng chuỗi enc://<base64> và được giải mã tự động khi khởi động.

Bắt đầu Nhanh

1. Đặt cụm mật khẩu

export PICOCLAW_KEY_PASSPHRASE="your-passphrase"

2. Mã hóa khóa API

Chạy picoclaw onboard — nó yêu cầu nhập cụm mật khẩu và tạo khóa SSH, sau đó tự động mã hóa lại tất cả các mục api_key dạng văn bản thuần trong cấu hình ở lần gọi SaveConfig tiếp theo. Giá trị enc:// kết quả sẽ có dạng:

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

3. Dán kết quả vào cấu hình

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

Các Định dạng api_key được Hỗ trợ

Thiết kế Mật mã

Dẫn xuất Khóa

Mã hóa sử dụng HKDF-SHA256 với khóa riêng SSH làm yếu tố thứ hai.

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)

Mã hóa

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

Định dạng Truyền tải

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

Thẻ xác thực GCM được tự động nối vào bản mã. Bất kỳ sự giả mạo nào đều khiến giải mã thất bại với lỗi thay vì trả về văn bản thuần bị hỏng.

Hiệu suất

Bảo mật Hai Yếu tố với Khóa SSH

Khi khóa riêng SSH được cung cấp, việc phá vỡ mã hóa yêu cầu cả hai:

1. Cụm mật khẩu (PICOCLAW_KEY_PASSPHRASE)
2. Tệp khóa riêng SSH

Điều này có nghĩa là chỉ rò rỉ tệp cấu hình không đủ để khôi phục khóa API, ngay cả khi cụm mật khẩu yếu. Khóa SSH đóng góp 256 bit entropy (Ed25519) bất kể độ mạnh của cụm mật khẩu.

Mô hình Mối đe dọa

Biến Môi trường

Tự động Phát hiện Khóa SSH

Nếu PICOCLAW_SSH_KEY_PATH không được đặt, PicoClaw tìm khóa chuyên dụng:

~/.ssh/picoclaw_ed25519.key

Tệp chuyên dụng này tránh xung đột với các khóa SSH hiện có của người dùng. Chạy picoclaw onboard để tạo tự động.

os.UserHomeDir() được sử dụng để phân giải thư mục home đa nền tảng (đọc USERPROFILE trên Windows, HOME trên Unix/macOS).

Lưu ý: Tệp khóa SSH là bắt buộc cho mã hóa thông tin xác thực. Nếu không tìm thấy khóa và PICOCLAW_SSH_KEY_PATH không được đặt, mã hóa/giải mã sẽ thất bại. Chạy picoclaw onboard để tạo khóa tự động.

Di chuyển

Vì tài liệu bí mật duy nhất là PICOCLAW_KEY_PASSPHRASE và tệp khóa riêng SSH, việc di chuyển rất đơn giản:

1. Sao chép tệp cấu hình sang máy mới.
2. Đặt PICOCLAW_KEY_PASSPHRASE với cùng giá trị.
3. Sao chép tệp khóa riêng SSH đến cùng đường dẫn (hoặc đặt PICOCLAW_SSH_KEY_PATH đến vị trí mới).

Không cần mã hóa lại.

Lưu ý về Bảo mật

• Cả cụm mật khẩu và khóa SSH đều bắt buộc. Khóa SSH đóng vai trò yếu tố thứ hai — không có nó, mã hóa/giải mã sẽ thất bại. Chạy picoclaw onboard để tạo khóa nếu chưa tồn tại.
• Khóa SSH chỉ đọc khi chạy. PicoClaw không bao giờ ghi hoặc sửa đổi tệp khóa SSH.
• Khóa văn bản thuần vẫn được hỗ trợ. Các cấu hình hiện có không dùng enc:// không bị ảnh hưởng.
• Định dạng enc:// được quản lý phiên bản thông qua trường info của HKDF (picoclaw-credential-v1), cho phép nâng cấp thuật toán trong tương lai mà không làm hỏng các giá trị đã mã hóa hiện có.