How Hush works

The pieces

The apps on your devices do all the encryption. The server only stores and returns what they send.

From master password to keys

Hush uses three keys, and each has one job. Only one of them, the auth key, is ever sent to the server, and it can't decrypt anything.

The optional recovery key

A recovery key is a second way to the same vault key, for a forgotten master password. It is 32 random bytes, shown once as 56 letters and digits in groups of 4 (the last few are a checksum, so a typo is caught before anything is sent). From it the device derives two subkeys: a recovery auth key, which the server hashes like the auth key, and a recovery wrap key, which never leaves the device and wraps a second copy of the vault key. There is no Argon2id here: 256 random bits can't be guessed. Using it sets a new master password and a new recovery key. Keep it on paper or offline, never inside Hush: it is as powerful as the master password.

What an encrypted item is

The item (name, username, password, notes, sections, icon…) becomes JSON, is padded up to a multiple of 64 bytes so its exact length doesn't show, and is encrypted. The result is a small envelope:

{ "v": 1,                                   // format version
  "n": "Hq0mN8xZ…24 random bytes…",          // nonce
  "c": "9fKe1Lw3…ciphertext + 16-byte tag…" } // the locked item

The encryption also binds in the item's id (pm:item:v1:<id>). If anyone changes even one byte, or moves the ciphertext to a different item, decrypting fails. Every failure gives the same error, so it reveals nothing about why.

What happens when you…

Locking a device wipes the vault key from memory. Unlocking again needs the master password (or, if you turned it on, the fingerprint, see section 06), because no device stores the vault key.

What the server database holds

MongoDB has two collections. Here is what an account and an item look like in the database (shortened values):

users: one document per account

{ "_id": ObjectId("6714…"),
  "email": "you@example.com",
  "kdf": { "alg": "argon2id13", "opsLimit": 3, "memLimit": 67108864,
           "salt": "q3VtR9…==" },                       // public by design: devices need it
  "authHash": "$argon2id$v=19$m=19456,t=2,p=1$…$…",  // hash of the auth key, not the key
  "wrappedVaultKey": { "v": 1, "n": "…", "c": "…48 bytes…" },  // locked by the wrap key
  "recovery": { "authHash": "$argon2id$…",                 // only with a recovery key
                "wrappedVaultKey": { … } },              // locked by the recovery wrap key
  "twoFactor": { "secret": { "n": "…", "c": "…" },   // only with 2FA: sealed with a server key
                 "lastStep": 59321…, "recoveryCodes": [ "…keyed hashes…" ] },
  "createdAt": …, "updatedAt": … }

items: one document per item

{ "userId": ObjectId("6714…"),
  "itemId": "3f1c9a2e-…-4…",                          // random, made by the device
  "envelope": { "v": 1, "n": "…", "c": "…" },           // the whole item, encrypted
  "revision": 3,                                     // +1 per save
  "deletedAt": null,                                 // a date while in the trash (30 days)
  "createdAt": …, "updatedAt": … }

Redis holds only short-lived things: sessions, stored as a hash of the token pointing to your user id (ending after 2 h unused, 24 h at most), two-step challenges (5 min), "remembered device" tokens (hashed, 30 days) and rate-limit counters (15 min). If Redis leaked, the stored hashes couldn't be used as tokens.

If the database leaked

Assume the worst: someone copies the entire database, or a backup file. What can they do?

How long trying every possibility would take, assuming a well-equipped attacker managing 1,000 guesses a second against these settings (a rough figure; Argon2id's memory cost is what keeps GPUs slow):

Two-step sign-in doesn't change this table: it guards the server, and a copied database is attacked without asking the server anything. The recovery key's copy of the vault key can't be guessed (256 random bits).

What a malicious server could still do

• Withhold or delete items. Backups cover this.
• Serve an older copy of an item. Revisions aren't bound into the ciphertext yet (a known limit).
• Offer weaker key settings to a device that has never signed in before. Devices that have signed in remember the strongest settings they've seen and refuse anything weaker.

It can't read items, change them unnoticed, swap one item's ciphertext into another, or get your master password.

The Android app

Hush for Android runs the same crypto code as the web app on native libsodium. It produces byte-for-byte the same output, so the phone and the laptop open the same vault, and a test checks that they still match.

What lives where on the phone

How it guards the screen and the clipboard

Autofill

Opt-in. When a sign-in form appears, Android offers "Hush · fill for <site>". Tapping it opens a protected Hush screen: unlock with fingerprint or master password, pick a login, filled. If the screen unlocked just for this, the key is wiped again on close. Every Hush field, on the phone and on the web, is kept away from other password managers, so nothing typed into Hush is offered for saving or filled by them.

Permissions

Storage, media, microphone and overlay permissions are removed from the app. Android's automatic cloud backup is off for Hush, so its files are not copied to Google. Every release is signed with Hush's own release key, and Android refuses an update signed with any other key.

The web app

Imports (Chrome, Bitwarden, 1Password CSV/JSON) are read in the browser and encrypted before upload; the plain file never reaches the server. Encrypted exports use their own passphrase with heavier Argon2id (256 MiB), because a file can be attacked offline forever.

The server

Today the server runs on a private network that only its developer's devices can reach. It moves to dedicated hosting before anyone else can sign up.

Backups and break-glass

The database is dumped every night, and each archive is encrypted with age to a backup key whose private half never touches the server. Copies are pulled to a separate machine and kept for 90 days.

Backups contain exactly what the database contains: ciphertext, the wrapped vault key and the auth hash. Nothing in them is readable without your master password, and without the backup key a stolen archive can't even be guessed at offline.

If the server is ever gone, hush recover opens a backup with the backup key and the master password: no server, no Docker, no network. It can show items or write an encrypted export to import into a new Hush.

Honest limits