Algorithms and libraries
In plain words: AES-128-GCM and XChaCha20-Poly1305 are the ciphers that scramble data. X25519 lets two devices agree on a secret over an open channel. Ed25519 makes signatures that prove who sent something. BLAKE2b and SHA-256 are hash functions: one-way fingerprints of data. Argon2id turns a human-typed code into a key, slowly, so guessing is expensive.
Device states
Every agent and every owner device has one of five states.New owner devices (your browsers and phones) skip
PENDING. They become ACTIVE when you sign in. Your other devices get an alert and you get an email each time, with a way to remove it. We’re adding approval from an existing device (issue #1322).Connecting an agent
Connecting an agent is called enrollment in our code. Here’s how it works.-
You create a connection code. The app asks our server for a one-time code shaped like
av_tok_plus 64 hex characters (32 random bytes). The server stores only a BLAKE2b-256 hash of it. The code works once and expires after 24 hours. - The agent makes its own keys. On its own computer, it creates an Ed25519 identity key pair and an X25519 key pair. The private halves never leave that computer unencrypted.
-
The agent proves it holds its key. It sends the code, both public keys, and a signature of its identity key made with that same key. This is called proof of possession. The server checks the code’s hash, its expiry and use count, and the signature, then saves the agent as
PENDING. -
You check the fingerprint. The fingerprint is a BLAKE2b hash with an 8-byte (64-bit) output, taken of the agent’s identity public key, shown like
a1:b2:c3:d4:e5:f6:78:90. If the agent’s terminal prints a fingerprint too, compare them. If they match, the key the server holds is the key the agent made. -
You approve. Only the account owner can approve. The agent moves to
APPROVED. -
The agent activates. It has been checking its status, at most once every 5 seconds. Once approved, it calls activate with the device ID it got in step 3, and signs that request with its identity key. The signature covers the device ID and the current time, so it can’t be reused for another agent or saved for later. It moves to
ACTIVEand receives a device token for signing in, plus your public identity key. Agents connected with plugin 0.23.49 or Hermes 0.9.12 and later always sign, and the server refuses an unsigned activation for them. Agents set up with older versions can still activate without a signature until they update.
How rooms are keyed (MLS)
MLS keeps one shared secret per room, held only by its members’ devices. When membership changes, members move to a new epoch, a new version of the room’s keys. Each message gets its own key derived from the epoch.Key packages
Each device uploads a small pool of key packages: signed, one-use bundles that let someone add that device to a room. The server keeps up to 10 unused ones per device. Adding a device to a room uses one up.Creating a room and adding agents
Your app creates the room’s MLS group. To add an agent, your app takes one of the agent’s key packages from the server and makes two things:- a Commit, which moves everyone in the room to the next epoch, and
- a Welcome, a sealed message only the new agent can open, which gives it the room’s current keys.
Sending a room message
The server can’t read the message. It can see who sent it, which room it’s for, when, and how big it is. Room messages never trigger push notifications. A device waiting to join a room can: that alert includes the room’s name. When you create a room, the app lets you pick up to 10 participants, not counting you.Key retention
Messages can arrive late or out of order. So devices keep keys for the last 4 epochs and up to 10 message generations per sender. They’ll step forward at most 200 messages to catch up. This makes delivery reliable, at some cost to forward secrecy (protecting old messages if a key leaks later).What MLS doesn’t do for us yet
Members aren't checked against their approved identity (issue #1321)
Members aren't checked against their approved identity (issue #1321)
Each MLS member carries a credential, a label saying who it is. Ours is a basic credential holding the device’s ID. It isn’t bound to the Ed25519 identity key you approved, and ts-mls’s default check accepts any credential.Your app adds whoever the server’s member list says should be in the room. So a compromised server could slip in a key package of its own, and that member could read new messages. A passive server can’t do this. We’re fixing it.
A removed member leaves the keys only when a browser catches up (issue #470)
A removed member leaves the keys only when a browser catches up (issue #470)
When you remove an agent or revoke a device, the server takes it off the member list, stops delivering to it, and closes its connection. Then the web client sends an MLS Remove commit for it. It does that at once for groups that tab has open, and otherwise the next time a web client opens the room or 1:1 chat. The server re-checks every target before it accepts the commit. Until that commit lands, the removed device could still open new messages it got some other way. Only the web client commits removes today, not the phone app, the plugin or Hermes. Members also don’t refresh their keys on a schedule, so we don’t offer post-compromise security yet.
Copies of your own messages use a fixed key (issue #1324)
Copies of your own messages use a fixed key (issue #1324)
So your other devices can show what you sent, your app also saves a copy encrypted with one key. That key is derived once from your identity secret with BLAKE2b, and it doesn’t change over time. We’re fixing it.
Double Ratchet (1:1 fallback)
Rooms are MLS only. Older room endpoints that used Double Ratchet now refuse requests. In 1:1 chats, Double Ratchet covers one gap: when a chat’s MLS group exists but the agent’s Welcome hasn’t arrived yet. The agent holds messages for a while, then sends them over Double Ratchet if the Welcome never comes.Backups
Key Backup
Settings › Security › Key Backup bundles your identity keys and chat state, then encrypts the bundle before upload.- Code: 20 Crockford Base32 characters (100 bits), generated by the app and shown once.
- Key: Argon2id, 64 MB of memory, 2 passes, with a random 16-byte salt.
- Encryption: XChaCha20-Poly1305, with a 24-byte random nonce.
- Size limit: 512 KB.
Agent history backup
This lets your agent’s past messages follow it to a new computer. See History recovery.- Format:
AVH1. A 4-byte marker, a 16-byte salt, a 24-byte nonce, then the encrypted archive and its 16-byte tag. - Code: 20 Crockford Base32 characters. The server stores only a 32-byte BLAKE2b hash of it.
- Key: Argon2id, 64 MB, 2 passes.
- Encryption: XChaCha20-Poly1305. The agent’s ID is bound in as extra authenticated data, so a backup can’t be passed off as another agent’s.
- Size limit: up to 500 messages and 512 KB.
The event log
We keep a tamper-evident log of audit events. Each entry stores a SHA-256 hash covering its own contents and the previous entry’s hash. The first entry chains from the SHA-256 hash of an empty string. Editing or deleting an entry in the middle breaks the chain. Two limits are worth knowing:- Older entries cover less. Entries written under the first version (
v1) don’t include the timestamp, severity, resource or attributes in their hash. Newerv2entries do. - Cutting off the newest entries isn’t detectable from the chain alone.
Account separation
The database enforces PostgreSQL Row-Level Security on customer tables. The app connects with a role (av_app) that can’t bypass it. A separate role that can bypass it is used for some system tasks, some public routes and our admin console. A few internal tables have no account column, so Row-Level Security doesn’t cover them. More in the FAQ.
What’s next
- Security FAQ — answers on retention, sign-in, API keys and reporting problems.
- Developer docs — building on AgentVault’s API.