Barrel
EN GitHub

Une clé par base. Un identifiant à chaque requête.

Barrel peut chiffrer au repos une base entière sous sa propre clé : documents, pièces jointes, vecteurs et fichiers d’index. Devant elle, barrel_server vérifie un bearer, un jeton de capacité, une requête signée ou un certificat client avant l’exécution de toute route.

Les deux sont désactivés tant que vous ne les activez pas. Cette page dit ce que chacun couvre, ce qu’il ne couvre pas, et où les jetons sont appliqués.

Chiffrement au reposAuthentification

Chiffrement au repos

Vous passez une spécification encryption à l’ouverture d’une base. Un fournisseur de clés transforme le keyspace de la base en une clé de 32 octets ; les magasins chiffrent avec elle chaque fichier qu’ils écrivent. Une branche partage le keyspace de son parent, elle s’ouvre donc avec la même clé.

  1. Secret maître BARREL_ENCRYPTION_KEY
    Votre fournisseur de clés KMS, coffre, par client

    HKDF-SHA256 avec le keyspace de la base

  2. Une clé par base 32 octets, jamais écrits sur disque

    AES-256-CTR, par fichier et par secteur

  3. Chiffré documents, WAL, pièces jointes blob, magasin de vecteurs, fichiers BM25 sur disque et DiskANN
    Non chiffré pièces jointes sur le backend S3
Ce que couvre le chiffrement au repos
DonnéesAu repos
Magasin de documents (fichiers RocksDB, WAL)Chiffré
Pièces jointes dans le magasin blob par défautChiffré
Pièces jointes sur le backend S3 (barrel_att_s3)Non chiffré : stocké en clair dans le bucket
Magasin de vecteurs, état HNSW et FAISSChiffré
Fichiers d’index BM25 sur disque et DiskANNChiffré, par secteur de 4096 octets
Branches de la timelineChiffré sous la clé du parent
Fichier de vérification de clé dans le répertoire de la baseEn clair, à dessein : il fait échouer une mauvaise clé à l’ouverture

Qui peut appeler le serveur

Fixez une clé auth et toutes les routes sauf /health demandent un identifiant. Une requête est jugée sur l’identifiant qu’elle présente : d’abord une signature, sinon le jeton dans Authorization, sinon le certificat client.

Modèles d’authentification de barrel_server
ModèleS’active avecCe qu’il prouveS’applique à
Ouvertpas de clé authRien. Toutes les routes répondent.REST, sync, MCP
Bearer#{tokens => [...]}Un secret partagé, comparé en temps constant. Une liste permet la rotation.REST, sync, MCP
Jeton de capacitéémis par espace (bsp_...)Un espace, en lecture, écriture ou admin. Les routes de cycle de vie, de timeline et non associées le refusent.REST, sync, MCP
Requête signée (v3)accept => [signed], signersUne clé Ed25519 par client. Couvre la méthode, le chemin, la query, le hachage du corps et les en-têtes qui modifient une écriture ; les rejeux sont refusés.REST, sync
mTLSaccept => [mtls], verify_peerQue le client détient un certificat de votre CA, pas de quel client il s’agit.REST, sync sur HTTP/1.1 ou HTTP/2 avec TLS

Dans votre nœud, et via le serveur

La couche agents est une bibliothèque. Les jetons n’ont de sens que là où quelqu’un les vérifie.

Où les jetons sont appliqués
ContrôleDans le processus (API Erlang)Via barrel_server (REST, sync, MCP)
Jetons de capacitéIndicatifs : vérifiés seulement là où votre code appelle barrel_caps:verify/3. open_space/1 et les appels de session ne prennent pas de jeton.Vérifiés à chaque requête et à chaque appel d’outil MCP.
Droit admin (octroi, révocation, passations)Non vérifié : les appels Erlang ne prennent pas de jeton.Exigé par les routes.
Chiffrement par baseLa frontière d’isolation : pas de clé, pas de données.Appliqué à chaque base par open_opts ; les clés ne transitent jamais sur HTTP.

Ce qui tient, et ce qui le vérifie

Chaque propriété nomme le test ou l’exécution enregistrée qui la vérifie.

Rien de lisible sur le disque

Avec le chiffrement actif, chercher dans chaque fichier un marqueur écrit dans un document, un texte de vecteur et une pièce jointe ne trouve rien ; la même écriture sans chiffrement le trouve.

Vérifié par une exécution de bout en bout enregistrée (plus bas), barrel_encryption_SUITE, barrel_encryption_facade_SUITE et barrel_vectordb_crypto_tests.

Une mauvaise clé échoue à l’ouverture

Une mauvaise clé répond wrong_encryption_key, une ouverture en clair d’une base chiffrée db_is_encrypted, jamais des lectures corrompues.

Vérifié par l’exécution enregistrée et barrel_encryption_SUITE.

Une signature invalide n’est jamais rattrapée

Une requête qui présente une signature est jugée sur elle seule, même si un bearer ou un certificat client la laisserait passer.

Vérifié par t_bearer_with_bad_signature_rejected dans barrel_server_signed_SUITE, t_bad_signature_rejected dans barrel_server_mtls_SUITE.

Corps et en-têtes signés ne peuvent pas être échangés

Le hachage du corps est vérifié avant l’exécution du handler, sur chaque route ; modifier un en-tête signé répond 401.

Vérifié par barrel_server_signed_SUITE : t_tampered_body_rejected, t_rest_doc_body_swap_rejected, t_att_put_digest_tamper_rejected, t_replay_rejected.

Les jetons de capacité échouent fermés

Une route non associée à un droit refuse un jeton de capacité avec 403 ; un jeton mort reçoit 401.

Vérifié par t_capability_fail_closed et t_capability_dead_tokens dans barrel_server_auth_SUITE.

mTLS refuse un client sans certificat

À la poignée de main TLS, avant l’exécution de toute route.

Vérifié par t_certless_refused dans barrel_server_mtls_SUITE.

L’utiliser

Chiffrer une base

Le chiffrement est une configuration d’exécution : passez la même spécification à chaque ouverture.

%% export BARREL_ENCRYPTION_KEY="a long passphrase"
{ok, Db} = barrel:open(secret, #{encryption => default,
    vectordb => #{dimension => 3, bm25_backend => disk,
                  db_path => "data/secret_vec"}}),

%% or your own provider: key_for_db(Keyspace) -> {ok, <<_:256>>}
{ok, Db2} = barrel:open(tenant_a,
    #{encryption => #{provider => my_kms_provider}}).
Lignes affichées par une exécution enregistrée qui a écrit un marqueur dans un document, un texte de vecteur et une pièce jointe, fermé la base et fouillé les fichiers
read back: <<"TOPSECRETMARKER">>
bm25 hits: 1
files containing plaintext marker:        0
plaintext open: {error,db_is_encrypted}
wrong key open: {error,wrong_encryption_key}
reopened with right key: <<"TOPSECRETMARKER">>
encrypt existing plaintext db: {error,cannot_encrypt_existing_db}

Chiffrer chaque base qu’un serveur ouvre

sys.config
{barrel_server, [
    {open_opts, #{encryption => default}}
]}

Verrouiller le serveur avec des jetons bearer

sys.config
{barrel_server, [
    {auth, #{tokens => [<<"new-token">>, <<"old-token">>]}}
]}

Signer les requêtes entre nœuds

Générez la paire de clés avec crypto:generate_key(eddsa, ed25519). Les clients à partir de barrel_docdb 2.1.0 n’envoient que la signature v3 : mettez d’abord les serveurs à jour vers barrel_server 1.13.0.

%% server: know each peer's public key
application:set_env(barrel_server, auth,
    #{accept  => [bearer, signed],
      signers => #{<<"node1">> => PubKey32},
      skew_ms => 300000}),

%% client: sign with the private key, kept out of task configs
application:set_env(barrel_docdb, sync_signing,
    #{<<"https://edge-1.example.com:8443">> =>
          #{key_id => <<"node1">>, priv_key => Priv32}}).

Filtrer le transport avec mTLS

application:set_env(barrel_server, listeners,
    #{http => #{port => 8443, tls => true}}),
application:set_env(barrel_server, tls,
    #{certfile => "server.pem", keyfile => "server.key",
      cacertfile => "ca.pem", verify => verify_peer}),
application:set_env(barrel_server, auth,
    #{accept => [mtls, signed], signers => Signers}).

Limites

  • Les pièces jointes stockées sur le backend S3 ne sont pas chiffrées, même quand la base l’est.
  • Il n’y a ni rotation de clé ni chiffrement sur place d’une base existante. Répliquez vers une nouvelle base sous la nouvelle clé. Une clé perdue, ce sont des données perdues.
  • Le modèle de menace porte sur les données au repos. Le mode CTR n’est pas authentifié, donc un attaquant qui peut écrire les fichiers est hors périmètre, et les clés en mémoire ne sont pas mises à zéro.
  • Un serveur sans clé auth est ouvert à quiconque peut l’atteindre. Une liste accept vide le verrouille complètement.
  • Sans TLS, les jetons bearer peuvent être rejoués. La signature authentifie le client et chaque requête ; elle ne masque pas le trafic et n’authentifie pas les réponses du serveur. Utilisez pour cela du HTTPS vérifié.
  • mTLS identifie votre CA, pas le pair : seul, il fait de chaque client muni d’un certificat un même pair de confiance. Ajoutez des requêtes signées pour l’identité. Les écoutes HTTP/3 ne vérifient pas encore les certificats clients.
  • /mcp et barrel-lite n’acceptent que des jetons bearer (serveur ou de capacité).

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