Security and account
How your data is protected
A plain-language explanation of GrailVault's encryption, what the server can and cannot see, and where the limits are.
GrailVault is designed so that the server cannot read your vault. This page explains how, without assuming any cryptography background.
#The short version
- You pick a master password. It never leaves your browser.
- Your browser turns it into keys using Argon2id, a deliberately slow, memory-hungry function that makes password guessing very expensive.
- A random vault key encrypts every item with XChaCha20-Poly1305. The vault key itself is stored only in encrypted form.
- The server stores the encrypted items. Without your master password (or your recovery key) they are unreadable noise.
#The keys, step by step
| Step | What happens |
|---|---|
| Master password | You type it. It is used only inside your browser and is never stored. |
| Key derivation | Argon2id (128 MiB of memory, 3 passes by default, with a random salt) turns it into one secret value. |
| Two separate keys | From that value your browser derives two independent keys: an encryption key and a login key. Knowing one tells you nothing about the other. |
| Vault key | A random key made once when you sign up. It encrypts every item. It is stored on the server only wrapped (encrypted) by your encryption key. |
| Items | Each credential is encrypted separately with the vault key and a fresh random value, and is tied to your account, its own id and its type, so items cannot be swapped between accounts or records without detection. |
| Signing in | Your browser proves it knows your password by sending the login key, never the password itself. The server stores only a slow hash of the login key. |
Because items are protected by the random vault key, changing your master password only re-protects that one key. Your data is never exposed or re-encrypted in the process.
#What the server stores, and what it never has
| The server stores | The server never has |
|---|---|
| Encrypted items (ciphertext) | Your master password |
| Your email address | Your vault key, or the keys derived from your password |
| A slow hash of your login key | Item names, usernames, websites, tags or notes |
| The size, kind and timestamps of each item | Passwords, API keys or tokens in readable form |
| Session and activity information: browser, IP address, last activity | Any way to decrypt your vault, even for us |
There is no administrator role in GrailVault. Nobody, including us, can read, reset or recover another person's vault.
#The ingredients
GrailVault uses libsodium, a widely reviewed cryptography library, and does not invent its own algorithms.
| Purpose | Used |
|---|---|
| Password to keys | Argon2id |
| Encrypting items and keys | XChaCha20-Poly1305 (authenticated encryption) |
| Separating keys | libsodium key derivation with distinct contexts |
| Hash of the login key | Argon2id |
| Two-factor codes | TOTP, RFC 6238 |
| Windows Hello, phone and Touch ID unlock | WebAuthn with the PRF extension |
#Protections around the vault
- Brute-force slowdown: repeated wrong passwords lock the account for 15 minutes after 5 failures, and requests are rate-limited.
- Two-factor sign-in: see Two-factor authentication.
- Strict browser protections: a tight content security policy with no inline scripts, same-site secure cookies and request-forgery tokens.
- Locking: keys are wiped from memory on lock; see Copy, reveal and locking.
- The browser extension: it uses the same encryption and keeps its keys in memory only; see Safety and privacy.
- Activity log: sign-ins and security changes are listed so you can spot anything unfamiliar; see Recent activity.
- Breach check: optional and private; see Security check.
- Encrypted backups only: there is deliberately no plain-text export. See Encrypted backup and restore.
#What this does not protect against
Warning
No password manager can promise perfect safety. These are the real limits.
- A compromised device. Malware or a keylogger on the computer where you type your master password can see what you see.
- A hacked or malicious server that serves altered code. In any web app the browser runs the code the server sends. If an attacker took over the service, they could send code that captures your password on your next sign-in. We protect the service, but this is a limit of every web-based vault, and the reason the extension and an independent audit matter.
- A weak master password. Argon2id makes guessing slow, not impossible.
- An unlocked screen. Anyone at your unlocked vault can see it until you lock it, so lock it (or close the tab) when you step away from a shared computer.
- Metadata. The server can see your email address, how many items you have, their sizes and when they changed.
- Rolled-back data. A server could return an older copy of an item. This is not detected today.
- No independent audit. The design is documented here so that you or your own reviewer can check it, but no third party has audited GrailVault.
See also Limits and roadmap.