Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Update docs

Leendert de Borst2a79e9b2bd23
diff --git a/docs/docs/security-whitepaper.mdx b/docs/docs/security-whitepaper.mdx
index 783291ba5..ff4e67a96 100644
--- a/docs/docs/security-whitepaper.mdx
+++ b/docs/docs/security-whitepaper.mdx
@@ -422,7 +422,7 @@ Access to a shared vault is called a *grant*: a copy of the vault's VEK encrypte
### 10.2. Access and keys
- **Group membership alone gives no access**: a group itself holds no keys. A user only gets access to a shared vault after being invited to it and accepting, which gives them their own grant.
- **Each key has one job**: the account encryption keypair only receives vault keys, and a Vault Delivery Keypair only decrypts email, so a key stored inside a vault never opens anything outside it.
-- **Grants are tied to their vault**: a grant is encrypted under a label that names the vault, so it cannot be used for another vault.
+- **Grants are tied to their vault**: a grant, and the vault name in an invitation, is encrypted under a label that names the vault, so it cannot be used for another vault.
- **Grants and keys are signed**: a grant carries an Ed25519 signature by the member who holds it, and a published account public key or delivery key one by the account that published it, each over a message that names its purpose, so a grant cannot be created by someone who merely knows a public key, and a signature made for one purpose does not verify for another. The server checks every signature on upload. A client opens a shared vault only with a grant signed by its own account, and encrypts a vault key only for a public key signed by a signing key its user certified ([10.3](#103-account-fingerprints-and-key-certifications)). A grant the server made up, signed with a key of its own, therefore never opens.
- **Own keys come from the private key**: a client uses the account public key the server serves as its own only after checking that it is the public half of the private key it holds, and derives its own signing public key from its signing private key. A server that serves another key as the user's own is refused.
- **Enforcement layers**: access to a vault's contents is enforced by cryptography (no grant, no key). Which vaults the server lists for a user, group membership and roles are enforced by the server. A few guards, such as refusing to delete the folder that represents a shared vault, are enforced only in the client.
@@ -456,7 +456,7 @@ AliasVault gives you offline access to your data: each device keeps an encrypted
- **Master password**: the unlock key is derived with Argon2id from the salt and settings cached on the device, the KEK is derived from it with HKDF-SHA256, and the KEK decrypts the Account Key (see [Key derivation and key hierarchy](#4-key-derivation-and-key-hierarchy)).
- **Biometrics (mobile)**: the Account Key is encrypted with a key held by the device's secure hardware. iOS uses a Keychain item with `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` and the `biometryCurrentSet` access control; Android uses an AndroidKeyStore AES-GCM key with `setUserAuthenticationRequired(true)`, `AUTH_BIOMETRIC_STRONG` and `setInvalidatedByBiometricEnrollment(true)`.
-- **PIN (mobile and browser extension)**: the Account Key is encrypted with AES-256-GCM under a key derived from the PIN with Argon2id (random 16-byte salt, 64 MiB, 3 iterations). The PIN encryption and the attempt policy are implemented once in the Rust core; after 4 failed attempts the encrypted Account Key is deleted and PIN unlock is disabled. A PIN has at least 6 characters: digits only on mobile, any characters in the browser extension. The browser extension stores the result in the extension's local storage; the mobile apps encrypt it once more with a key from the iOS Keychain (this-device-only) or the Android Keystore.
+- **PIN (mobile and browser extension)**: the Account Key is encrypted with AES-256-GCM under a key derived from the PIN with Argon2id (random 16-byte salt, 64 MiB, 3 iterations). The PIN encryption and the attempt policy are implemented once in the Rust core; after 4 failed attempts the encrypted Account Key is deleted and PIN unlock is disabled. A PIN has at least 6 characters: digits only on mobile, any characters in the browser extension. The browser extension appends the SHA-256 of its extension id to the random salt, so a copy of the extension storage alone does not hold the full salt; the extension stores the result in its local storage. On iOS the encrypted Account Key and salt are stored as a Keychain item (this-device-only, available only while a device passcode is set). On Android they are encrypted once more with AES-256-GCM under a key held in the Android Keystore before they are stored in the app's private preferences.
- **Passkey quick unlock (web app)**: the Account Key is encrypted with a key obtained from a passkey's PRF extension and stored in the browser.
Locking the vault removes the decrypted vault and the Account Key from memory; the encrypted vault stays on the device, so the next unlock can work offline. Logging out instead removes all data from the device, including the encrypted vault and key hierarchy, so logging back in requires a connection to the server.
@@ -464,7 +464,7 @@ Locking the vault removes the decrypted vault and the Account Key from memory; t
On Android, the app is excluded from system backups (`allowBackup="false"`), so the encrypted vault and the encrypted keys are not copied to cloud backups. On iOS the Keychain items are marked as this-device-only.
## 12. Vault exports
-The recommended export format is an encrypted `.avex` file, which can be imported into AliasVault again. It contains all vault data, including attachments and logos, encrypted with AES-256-GCM under a key derived with Argon2id (256 MiB, 3 iterations, parallelism 1, random 16-byte salt) from an export password you choose. The salt and Argon2id settings are stored in the file's header, so the password alone is enough to open it again.
+The recommended export format is an encrypted `.avex` file, which can be imported into AliasVault again. It contains all vault data, including attachments and logos, encrypted with AES-256-GCM under a key derived with Argon2id (256 MiB, 3 iterations, parallelism 1, random 32-byte salt) from an export password you choose. The salt and Argon2id settings are stored in the file's header, so the password alone is enough to open it again.
<a href={useBaseUrl('/assets/diagrams/whitepaper/12-vault-exports.html')} target="_blank" rel="noopener noreferrer" title="Open full screen">
<ThemedImage
@@ -493,7 +493,7 @@ These are the known limitations of the current design relative to the [threat mo
1. <Link id="limitation-shared-member-removal" />**Revocation from a shared vault is not cryptographic.** The server stops serving the vault and its email to a removed member, and their client deletes its local copy. The VEK and Vault Delivery Keypair stay the same, so the remaining members are not affected. Reading content added after the removal requires both the keys the former member kept and ciphertext the server no longer serves them, such as from a leaked copy of the server database. The remediation is to change the passwords in the shared vault where needed: the former member synced those items before the removal, and no change of keys can take that back. To also keep anything added later out of reach of the former member, create a new shared vault, move the items and aliases to it, invite the remaining members and delete the old vault, which deletes its data from the server, including its emails.
2. <Link id="limitation-rollback" />**Clients verify that a vault revision is authentic, not that it is the latest.** The server can serve a revision that members of the vault wrote earlier, or an empty vault, as the current one; it cannot read, change or create vault contents ([2.4](#24-what-the-server-knows-and-can-do)). A client accepts such a revision, so changes made after it are lost and older states of items return. Clients accept older revisions on purpose: a server restored from a backup serves them in the same way, and refusing them would lock users out of their vaults.
-3. <Link id="limitation-pin-unlock" />**PIN unlock in the browser extension is an opt-in convenience.** PIN unlock is off by default and the master password is the default unlock method; the PIN setting notes that a PIN can be less secure than the master password. The Account Key is encrypted under a key derived from the PIN with Argon2id, and the extension deletes it after 4 failed attempts. This limitation applies only to an attacker who already has a copy of the extension's storage from the user's browser profile, which takes forensic access to the device or a compromised device, both outside the threat model ([2.5](#25-out-of-scope)). Such an attacker is not bound by the attempt limit and can try PINs offline at the cost of one Argon2id derivation per guess, which is feasible for a 6-digit PIN; a longer PIN with letters and symbols takes more guesses. Browsers give extensions no hardware-bound key storage, so the extension cannot bind the PIN-encrypted key to the device. On mobile, the PIN-encrypted Account Key is also encrypted with a device-bound key from the iOS Keychain or the Android Keystore, so a copy of the app's storage alone is not enough to start guessing.
+3. <Link id="limitation-pin-unlock" />**PIN unlock in the browser extension is an opt-in convenience.** PIN unlock is off by default, and the PIN setting notes that a PIN can be less secure than the master password. How the PIN protects the Account Key is described in [11](#11-protecting-keys-on-the-device). An attacker with a copy of the extension's storage (forensic access or a compromised device, outside the threat model, [2.5](#25-out-of-scope)) is not bound by the attempt limit and can guess the PIN offline, which is feasible for a 6-digit PIN. Browsers give extensions no hardware-bound key storage; on mobile the Keychain or Keystore prevents this.
4. <Link id="limitation-post-quantum" />**Public-key encryption uses RSA-2048; a post-quantum algorithm is planned.** Grants, email keys and Login with Mobile use RSA-2048-OAEP. An attacker who keeps a copy of that ciphertext (from the server database or captured traffic) could decrypt it once a quantum computer able to break RSA-2048 exists, and with it the shared vault keys, emails and Account Keys it protects. RSA-2048 provides 112-bit security, which NIST SP 800-57 Part 1 approves through 2030; the NIST draft transition plan (IR 8547) sets 2035 for moving public-key encryption to post-quantum algorithms. Vault contents and the keys that protect the personal vault at rest use AES-256-GCM, which is considered safe against quantum computers. Every RSA ciphertext carries an algorithm identifier, so a post-quantum scheme can be added next to RSA without breaking existing data; it will be added once well-reviewed implementations exist on every platform AliasVault supports.
5. <Link id="limitation-argon2-parameters" />**A new device accepts Argon2id settings down to the OWASP minimum.** Accounts use 64 MiB and 5 iterations, but a device that has never logged in before does not know that, so it accepts any settings down to the OWASP minimum of 19 MiB and 2 iterations ([section 4](#4-key-derivation-and-key-hierarchy)). A malicious server could send that minimum to a new device and obtain one login proof to guess the master password against at the lower cost. A device that logged in before refuses weaker settings than it used, and a leaked database only allows guessing at the account's own settings. The minimum matches the default for accounts until version 0.31.0; once all accounts have migrated to the current defaults, it will be raised to match them.