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 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é.
- Secret maître BARREL_ENCRYPTION_KEYVotre fournisseur de clés KMS, coffre, par client
HKDF-SHA256 avec le keyspace de la base
- Une clé par base 32 octets, jamais écrits sur disque
AES-256-CTR, par fichier et par secteur
- Chiffré documents, WAL, pièces jointes blob, magasin de vecteurs, fichiers BM25 sur disque et DiskANNNon chiffré pièces jointes sur le backend S3
| Données | Au repos |
|---|---|
| Magasin de documents (fichiers RocksDB, WAL) | Chiffré |
| Pièces jointes dans le magasin blob par défaut | Chiffré |
Pièces jointes sur le backend S3 (barrel_att_s3) | Non chiffré : stocké en clair dans le bucket |
| Magasin de vecteurs, état HNSW et FAISS | Chiffré |
| Fichiers d’index BM25 sur disque et DiskANN | Chiffré, par secteur de 4096 octets |
| Branches de la timeline | Chiffré sous la clé du parent |
| Fichier de vérification de clé dans le répertoire de la base | En 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èle | S’active avec | Ce qu’il prouve | S’applique à |
|---|---|---|---|
| Ouvert | pas de clé auth | Rien. 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], signers | Une 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 |
| mTLS | accept => [mtls], verify_peer | Que 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.
| Contrôle | Dans 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 base | La 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}}). 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
{barrel_server, [
{open_opts, #{encryption => default}}
]} Verrouiller le serveur avec des jetons bearer
{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é
authest ouvert à quiconque peut l’atteindre. Une listeacceptvide 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.
/mcpet barrel-lite n’acceptent que des jetons bearer (serveur ou de capacité).