One key per database. A credential on every request.
Barrel can encrypt a whole database at rest under its own key: documents, attachments, vectors and index files. In front of it, barrel_server checks a bearer, a capability token, a signed request or a client certificate before any route runs.
Both are off until you turn them on. This page says what each one covers, what it does not, and where tokens are enforced.
Encryption at rest
You pass an encryption spec when you open a database. A key provider turns the database keyspace into a 32-byte key; the stores encrypt every file they write with it. A branch shares its parent’s keyspace, so it opens with the same key.
- Master secret BARREL_ENCRYPTION_KEYYour key provider KMS, vault, per tenant
HKDF-SHA256 with the database keyspace
- One key per database 32 bytes, never written to disk
AES-256-CTR, per file and per sector
- Encrypted documents, WAL, blob attachments, vector store, disk BM25 and DiskANN filesNot encrypted attachments on the S3 backend
| Data | At rest |
|---|---|
| Document store (RocksDB files, WAL) | Encrypted |
| Attachments in the default blob store | Encrypted |
Attachments on the S3 backend (barrel_att_s3) | Not encrypted: stored in clear in the bucket |
| Vector store, HNSW and FAISS state | Encrypted |
| Disk BM25 and DiskANN index files | Encrypted, per 4096-byte sector |
| Timeline branches | Encrypted under the parent’s key |
| Key-check file in the database directory | In clear by design: it lets a wrong key fail at open |
Who may call the server
Set an auth key and every route except /health needs a credential. A request is judged by the credential it presents: a signature first, else the token in Authorization, else the client certificate.
| Model | Turn it on with | What it proves | Applies to |
|---|---|---|---|
| Open | no auth key | Nothing. Every route answers. | REST, sync, MCP |
| Bearer | #{tokens => [...]} | A shared secret, compared in constant time. A list lets you rotate. | REST, sync, MCP |
| Capability token | issued per space (bsp_...) | One space, with read, write or admin. Lifecycle, timeline and unmapped routes refuse it. | REST, sync, MCP |
| Signed request (v3) | accept => [signed], signers | An Ed25519 key per client. Covers method, path, query, body hash and the headers that change a write; replays are refused. | REST, sync |
| mTLS | accept => [mtls], verify_peer | That the client holds a certificate from your CA, not which client it is. | REST, sync over HTTP/1.1 or HTTP/2 with TLS |
In your node, and over the server
The agent layer is a library. Tokens mean something only where someone checks them.
| Control | In process (Erlang API) | Over barrel_server (REST, sync, MCP) |
|---|---|---|
| Capability tokens | Advisory: checked only where your code calls barrel_caps:verify/3. open_space/1 and session calls take no token. | Checked on every request and every MCP tool call. |
| Admin right (grant, revoke, handoffs) | Not checked: the Erlang calls take no token. | Required by the routes. |
| Per-database encryption | The isolation boundary: no key, no data. | Applied to every database through open_opts; keys never travel over HTTP. |
What holds, and what tests it
Each property names the test or recorded run that checks it.
Nothing readable on disk
With encryption on, a search of every file for a marker written into a document, a vector text and an attachment finds nothing; the same write without encryption finds it.
Checked by a recorded end-to-end run (below), barrel_encryption_SUITE, barrel_encryption_facade_SUITE and barrel_vectordb_crypto_tests.
A wrong key fails at open
A wrong key answers wrong_encryption_key, a plaintext open of an encrypted database db_is_encrypted, never corrupted reads.
Checked by the recorded run and barrel_encryption_SUITE.
A failing signature is never rescued
A request that presents a signature is judged by it alone, even if a bearer or a client certificate would let it in.
Checked by t_bearer_with_bad_signature_rejected in barrel_server_signed_SUITE, t_bad_signature_rejected in barrel_server_mtls_SUITE.
Signed bodies and headers cannot be swapped
The body hash is checked before the handler runs, on every route; changing a signed header answers 401.
Checked by barrel_server_signed_SUITE: t_tampered_body_rejected, t_rest_doc_body_swap_rejected, t_att_put_digest_tamper_rejected, t_replay_rejected.
Capability tokens fail closed
A route not mapped to a right refuses a capability token with 403; a dead token gets 401.
Checked by t_capability_fail_closed and t_capability_dead_tokens in barrel_server_auth_SUITE.
mTLS refuses a client with no certificate
At the TLS handshake, before any route runs.
Checked by t_certless_refused in barrel_server_mtls_SUITE.
Use it
Encrypt a database
Encryption is runtime configuration: pass the same spec on every open.
%% 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} Encrypt every database a server opens
{barrel_server, [
{open_opts, #{encryption => default}}
]} Lock the server with bearer tokens
{barrel_server, [
{auth, #{tokens => [<<"new-token">>, <<"old-token">>]}}
]} Sign requests between nodes
Generate the key pair with crypto:generate_key(eddsa, ed25519). Clients from barrel_docdb 2.1.0 send signature v3 only, so upgrade servers to barrel_server 1.13.0 first.
%% 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}}). Gate the transport with 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}). Limits
- Attachments stored on the S3 backend are not encrypted, even when the database is.
- There is no key rotation and no in-place encryption of an existing database. Replicate into a new database under the new key. A lost key means lost data.
- The threat model is data at rest. CTR mode is not authenticated, so an attacker who can write the files is out of scope, and keys in memory are not zeroized.
- A server with no
authkey is open to anyone who can reach it. An emptyacceptlist locks it completely. - Bearer tokens can be replayed without TLS. Signing authenticates the client and each request; it does not hide traffic or authenticate the server’s responses. Use verified HTTPS for that.
- mTLS identifies your CA, not the peer: on its own every client with a certificate is one trusted peer. Add signed requests for identity. HTTP/3 listeners do not check client certificates yet.
/mcpand barrel-lite accept bearer tokens only (server or capability).