Retour au README

Chiffrement des identifiants

PicoClaw prend en charge le chiffrement des valeurs api_key dans les entrées de configuration model_list. Les clés chiffrées sont stockées sous forme de chaînes enc://<base64> et déchiffrées automatiquement au démarrage.

Démarrage rapide

1. Définir votre phrase secrète

export PICOCLAW_KEY_PASSPHRASE="your-passphrase"

2. Chiffrer une clé API

Exécutez picoclaw onboard — il vous demande votre phrase secrète et génère la clé SSH, puis re-chiffre automatiquement toutes les entrées api_key en clair dans votre configuration lors du prochain appel à SaveConfig. La valeur enc:// résultante ressemblera à :

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

3. Coller la sortie dans votre configuration

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

Formats api_key pris en charge

Conception cryptographique

Dérivation de clé

Le chiffrement utilise HKDF-SHA256 avec une clé privée SSH comme second facteur.

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)

Chiffrement

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

Format de transmission

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

Le tag d'authentification GCM est automatiquement ajouté au texte chiffré. Toute altération provoque l'échec du déchiffrement avec une erreur plutôt que de retourner un texte clair corrompu.

Performance

Sécurité à deux facteurs avec clé SSH

Lorsqu'une clé privée SSH est fournie, casser le chiffrement nécessite les deux :

1. La phrase secrète (PICOCLAW_KEY_PASSPHRASE)
2. Le fichier de clé privée SSH

Cela signifie qu'un fichier de configuration divulgué seul ne suffit pas pour récupérer la clé API, même si la phrase secrète est faible. La clé SSH apporte 256 bits d'entropie (Ed25519) indépendamment de la force de la phrase secrète.

Modèle de menace

Variables d'environnement

Détection automatique de la clé SSH

Si PICOCLAW_SSH_KEY_PATH n'est pas défini, PicoClaw recherche la clé dédiée :

~/.ssh/picoclaw_ed25519.key

Ce fichier dédié évite les conflits avec les clés SSH existantes de l'utilisateur. Exécutez picoclaw onboard pour le générer automatiquement.

os.UserHomeDir() est utilisé pour la résolution multiplateforme du répertoire personnel (lit USERPROFILE sous Windows, HOME sous Unix/macOS).

Remarque : Un fichier de clé SSH est requis pour le chiffrement des identifiants. Si aucune clé n'est trouvée et que PICOCLAW_SSH_KEY_PATH n'est pas défini, le chiffrement/déchiffrement échouera. Exécutez picoclaw onboard pour générer la clé automatiquement.

Migration

Étant donné que les seuls éléments secrets sont PICOCLAW_KEY_PASSPHRASE et le fichier de clé privée SSH, la migration est simple :

1. Copiez le fichier de configuration sur la nouvelle machine.
2. Définissez PICOCLAW_KEY_PASSPHRASE avec la même valeur.
3. Copiez le fichier de clé privée SSH au même chemin (ou définissez PICOCLAW_SSH_KEY_PATH vers son nouvel emplacement).

Aucun re-chiffrement n'est nécessaire.

Considérations de sécurité

• La phrase secrète et la clé SSH sont toutes deux requises. La clé SSH agit comme un second facteur — sans elle, le chiffrement/déchiffrement échouera. Exécutez picoclaw onboard pour générer la clé si elle n'existe pas.
• La clé SSH est en lecture seule à l'exécution. PicoClaw n'écrit ni ne modifie jamais le fichier de clé SSH.
• Les clés en texte clair restent prises en charge. Les configurations existantes sans enc:// ne sont pas affectées.
• Le format enc:// est versionné via le champ info de HKDF (picoclaw-credential-v1), permettant de futures mises à niveau d'algorithme sans casser les valeurs chiffrées existantes.