barrel_crypto
Le chiffrement au repos de Barrel : les algorithmes, la dérivation de clés et les fournisseurs de clés derrière l’option encryption d’une base.
Ce qu’elle résout
Une base par client ou par agent doit être illisible sans sa clé, sur disque comme dans les sauvegardes. barrel_crypto dérive une clé par base à partir d’un secret maître (ou la demande à votre fournisseur de clés), et le stockage des documents, le magasin de vecteurs, les fichiers BM25 sur disque et les pièces jointes en blob sont chiffrés avec elle.
Quand l’utiliser
- Chaque client, agent ou espace a besoin de sa propre clé.
- Les processus d’un même nœud Erlang ne doivent pas lire les espaces les uns des autres : le chiffrement est cette frontière.
- Vous gardez vos clés dans un KMS : écrivez un module fournisseur de clés.
Quand ne pas l’utiliser
- Vous stockez les pièces jointes dans S3 via barrel_att_s3 : ces octets ne sont pas chiffrés.
- Vous avez besoin de rotation des clés ou de chiffrer une base existante sur place : ni l’un ni l’autre n’existe.
Sa place dans Barrel
- Repose sur
- Aucune autre bibliothèque Barrel
- Utilisée par
barrel,barrel_docdb,barrel_vectordb,barrel_spaces- Autres dépendances
- crypto d’OTP
- Seule
- Oui, elle n’a aucune dépendance en dehors de crypto d’OTP.
Installation
{barrel_crypto, "~> 1.0"} Configuration
Clés
| Clé | Défaut | Rôle |
|---|---|---|
BARREL_ENCRYPTION_KEY | aucun | Secret maître : 32 octets bruts, 64 caractères hexadécimaux, ou une phrase de passe |
{barrel_crypto, encryption_key} | aucun | Utilisé quand la variable d’environnement n’est pas définie |
BARREL_ENCRYPTION_SALT / encryption_salt | barrel_default_salt_v1 | Sel HKDF |
Option encryption
| Clé | Défaut | Rôle |
|---|---|---|
disabled | par défaut | En clair |
default | Clé par base, dérivée du secret maître | |
#{provider => Mod} | Votre module renvoie la clé de 32 octets d’un espace de clés |
Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration et la référence de l’API.
L’API par tâche
Clés
| Tâche | Appel | Renvoie |
|---|---|---|
| Clé d’une base | barrel_keyprovider:key_for_db/2 | {ok, Key}, {ok, plaintext}, ou {error, _} |
| Votre propre fournisseur | callback key_for_db(Keyspace) | {ok, <<_:256>>} |
| Dériver | barrel_crypto:derive_key/1,2 | une clé |
Algorithmes
| Tâche | Appel | Renvoie |
|---|---|---|
| Sceller, ouvrir (AES-256-GCM) | barrel_crypto:encrypt/2, decrypt/2 | enveloppe, texte en clair ou {error, decryption_failed} |
| Termes | barrel_crypto:encrypt_term/2, decrypt_term/2 | enveloppe, terme |
| Tranches de fichier (AES-256-CTR) | barrel_crypto:ctr_crypt/3,4, new_nonce/1 | octets |
| Vérifier une clé | barrel_crypto:key_check_new/1, key_check_verify/2 | jeton, booléen |
Une base chiffrée, vérifiée sur disque
D’après une exécution vérifiée : documents, un vecteur, BM25 sur disque et une pièce jointe en blob, puis une recherche du texte en clair dans les fichiers.
os:putenv("BARREL_ENCRYPTION_KEY", "a long passphrase"),
{ok, _} = application:ensure_all_started(barrel),
Opts = fun(Enc) -> #{encryption => Enc,
docdb => #{data_dir => Dir},
vectordb => #{dimension => 3, bm25_backend => disk,
db_path => Dir ++ "/secret_vec"}} end,
{ok, Db} = barrel:open(secret, Opts(default)),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"a">>,
<<"note">> => <<"TOPSECRETMARKER">>}),
ok = barrel:vector_add(Db, <<"a">>, <<"TOPSECRETVECTEXT">>,
#{}, [0.1, 0.2, 0.3]),
{ok, _} = barrel:put_attachment(Db, <<"a">>, <<"f.txt">>,
<<"TOPSECRETBLOB">>),
ok = barrel:close(Db),
io:format("files containing plaintext marker: ~s",
[os:cmd("grep -rl -a 'TOPSECRET' " ++ Dir
++ " | wc -l")]),
io:format("plaintext open: ~p~n",
[barrel:open(secret, Opts(disabled))]),
os:putenv("BARREL_ENCRYPTION_KEY", "another passphrase"),
io:format("wrong key open: ~p~n",
[barrel:open(secret, Opts(default))]). files containing plaintext marker: 0
plaintext open: {error,db_is_encrypted}
wrong key open: {error,wrong_encryption_key} Limites à connaître
- Pas de rotation des clés et pas de chiffrement sur place d’une base existante (
{error, cannot_encrypt_existing_db}). - Les clés ne sont jamais écrites sur disque, mais un fichier de vérification de clé en clair,
CRYPTO, se trouve dans le répertoire de la base. - Le mode CTR n’est pas authentifié, et les clés ne sont pas effacées de la mémoire (les deux points sont documentés).
decrypt/2laisse passer une entrée qui ne commence pas parBR; un texte en clair court qui commence parBRle fait planter.
Les pièces jointes stockées dans S3 via barrel_att_s3 ne sont pas chiffrées, même quand la base l’est (vérifié : l’objet dans le bucket contenait le texte en clair).