Coffre-fort des secrets

v1.2.x · mis à jour 2026-06-26

AiHummer stocke chaque identifiant — jetons de canal, mots de passe SMTP/IMAP, jetons OAuth, clés LLM par locataire (BYOK) — dans un coffre-fort de secrets cryptés. La voûte utilise le chiffrement par enveloppe afin que la valeur au repos ne soit jamais lisible à partir de la seule base de données, et elle est conçue de manière à ce qu’un secret soit jamais placé dans le contexte du modèle ni dans les journaux.

Chiffrement par enveloppe

Le coffre-fort utilise une hiérarchie de clé à deux niveaux :

A clé maîtresse (KEK) — fourni en tant que AIHUMMER_MASTER_KEY, encodé en base64 Valeur de 32 octets — enveloppe et désempile les clés de données. Elle ne quitte jamais l’hôte et n’est jamais écrit dans la base de données.
A clé de chiffrement de données par locataire (DEK) chiffre les valeurs secrètes réelles avec AES-256-GCM (chiffrement authentifié). Chaque locataire possède sa propre DEK, ainsi les clés d’un locataire ne peuvent pas déchiffrer les secrets d’un autre locataire.

Les valeurs secrètes sont stockées sous forme de texte chiffré ; la DEK est stockée enveloppée par la KEK. Le déchiffrement se produit en mémoire au moment où un secret est nécessaire (par exemple, lorsqu’un connecteur s’authentifie), et le texte en clair est ensuite supprimé.

AIHUMMER_MASTER_KEY (KEK)  ──wraps──▶  per-tenant DEK  ──AES-256-GCM──▶  secret value

[!NOTE] Le coffre-fort repose sur PostgreSQL pgcrypto extension. Assurez-vous qu’il l’est disponible dans votre base de données — cela fait partie des exigences standard du système.

La clé maîtresse

La clé maîtresse est une valeur de démarrage : elle est lue depuis l’environnement au démarrage et est pas configurable depuis l’interface d’administration. L’installateur (et la passerelle au premier démarrage) crée toujours AIHUMMER_MASTER_KEY — ce n’est pas optionnel, car les secrets au repos, le coffre-fort d’identifiants et BYOK par locataire en dépendent tous. Une installation standard en possède donc toujours un.

# /home/.aihummer/etc/gateway.env
# 32 random bytes, base64-encoded
AIHUMMER_MASTER_KEY=Base64Of32RandomBytes==

Vous pouvez en générer un avec :

openssl rand -base64 32

[!WARNING] La clé maîtresse est nécessaire pour déchiffrer tout ce qui se trouve dans le coffre-fort. Traitez-la comme la racine de vos secrets et sauvegarde-le séparément à partir de la base de données — si si vous le perdez, les valeurs chiffrées ne peuvent pas être récupérées. Voir Opérations pour des conseils de secours.

Si la clé maîtresse est manquante

Parce que la clé est toujours provisionnée, une installation standard dispose toujours d’un coffre-fort fonctionnel. Le comportement ici est un mécanisme de fermeture en cas d’échec pour le cas inhabituel où AIHUMMER_MASTER_KEY est d’une certaine manière non défini (par exemple, un fichier env modifié à la main) : le coffre-fort et tout ce qui en dépend sont désactivée — le stockage des secrets au repos, le coffre-fort d’identifiants et les clés BYOK par locataire sont tous désactivés. C’est délibéré — le produit ne revient pas silencieusement à stocker les secrets en clair.

Les secrets n’atteignent jamais le modèle

C’est la propriété la plus importante du coffre, et elle est structurelle plutôt que rappel de politique.

[!DANGER] Les secrets sont jamais injecté dans le prompt du système, la conversation histoire, ou tout texte visible par le modèle, et ils sont jamais écrit dans les journaux. Les outils qui nécessitent des identifiants les récupèrent depuis le coffre au moment de l’appel, à l’intérieur la passerelle, et l’utiliser pour authentifier la demande sortante — seulement le modèle voit toujours le résultat de l’appel de l’outil, pas le secret.

Parce que l’interactivité est alimentée par l’appel d’outils (voir Garde-fous et défense contre l’injection d’instructions), il n’existe aucun moyen par lequel une invite pourrait demander au modèle de « lire » un secret stocké : le modèle n’en possède aucune copie à lire.

Identifiants partagés et par utilisateur

Le coffre distingue entre partagé identifiants (au niveau de l’espace de travail) et personnel Identifiants (par utilisateur). Les jetons OAuth2 par utilisateur obtenus via le flux Connexions sont stockés dans le coffre et résolus par l’utilisateur actif, avec un recours à l’espace de travail lorsque cela est approprié. Cela permet au même outil d’agir au nom de différents utilisateurs avec leur propre autorisation, sans jamais exposer le jeton d’un utilisateur à un autre.

Où aller ensuite

RBAC et clés API à portée — qui peut lire ou modifier configuration sécurisée par coffre
Sécurité au niveau des lignes — isolation par locataire dans le base de données qui soutient le coffre-fort.
Garde-fous et défense contre l’injection d’instructions — pourquoi le modèle ne peut jamais être trompé pour divulguer un secret.