Barrel
EN GitHub

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
Autres dépendances
crypto d’OTP
Seule
Oui, elle n’a aucune dépendance en dehors de crypto d’OTP.

Installation

dépendances rebar.config
{barrel_crypto, "~> 1.0"}

Configuration

Clés

CléDéfautRô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éfautRô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âcheAppelRenvoie
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âcheAppelRenvoie
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.

Erlang
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))]).
Sortie d’une exécution sur barrel_crypto 1.0.0 (la même écriture sans chiffrement laissait le marqueur dans 1 fichier)
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/2 laisse passer une entrée qui ne commence pas par BR ; un texte en clair court qui commence par BR le fait planter.
Lacune connue

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).

Haut et bas pour se déplacerEntrée pour ouvrir