Skip to content
Skip to content
Get started
/Security

Security

Per-folder encryption

A folder can have its own password, separate from your vault passphrase: a second lock for the things that need one. It is built entirely on the same envelope primitive, and the folder password never leaves your device.

What it is

By default, every file in your vault is protected by your vault passphrase. Per-folder encryption adds an independent password to a specific folder, so opening that folder requires something extra: useful for the handful of folders you want sealed off even from your own everyday session.

There is no new cryptography here. A protected folder reuses the exact envelope encryption scheme used everywhere else in zcrypt. The only thing that changes is which password derives the key that wraps each file's Content Encryption Key, the folder password instead of the vault passphrase.

Local password verification

When you set a folder password, your device generates a random salt and builds a small verifier: a fixed constant encrypted with the folder-password-derived key. To check a typed password later, the client re-derives the key and tries to decrypt that verifier. The right password decrypts it; a wrong one fails GCM authentication. All of this happens on-device with no server round-trip.

folder password verifier (conceptual)
pw_salt     = random(32 bytes)                       // per folder
KEK_pw      = PBKDF2-HMAC-SHA256(folder_password, pw_salt, 600000, 32)
pw_verifier = AES-256-GCM(key = KEK_pw, plaintext = "zcrypt-folder-verify-v1")

// later, to verify a typed password, entirely on-device:
AES-256-GCM-open(KEK_pw', pw_verifier) == "zcrypt-folder-verify-v1" ?

Why a verifier instead of asking the server

The verifier lets the app tell you immediately whether a password is correct without decrypting a real file and without the server ever participating in the check. The server cannot validate the password because it never has the material to.

Re-keying across the boundary

A file's already-uploaded chunks never get re-encrypted when you protect a folder. That would mean re-uploading everything. Instead, only the tiny wrapped key changes. When a file enters a protected folder, the client recovers its existing CEK under the source key, then re-wraps that same CEK under a fresh folder-password-derived key and a new salt.

  1. Recover the file's existing CEK using the source password (vault passphrase or the old folder password).
  2. Re-wrap that same CEK under the destination password's derived key with a new per-file salt.
  3. Persist the new salt and wrapped CEK via the /rekey endpoint: it updates only those two fields and touches no chunk data.

Moving a file out of a protected folder runs the same dance in reverse, re-wrapping the CEK back under your vault passphrase. The underlying ciphertext on your storage backend is never rewritten.

What the server stores

For a protected folder, the server holds exactly two opaque, client-computed base64 blobs, and nothing else about the password:

  • •pw_salt: the random per-folder salt used to derive the folder-password key on your device.
  • •pw_verifier: the small ciphertext used for local verification. It reveals nothing about the password.

The folder password is never sent

The server never derives, sees, or logs the folder password or any key derived from it. A folder counts as “protected” purely because pw_salt is present. Audit events for setting or clearing a folder password record only the folder ID, never the salt, the verifier, or any key material.

Caveats

  • •A forgotten folder password is unrecoverable. Just like the vault passphrase, there is no reset: the key exists nowhere we can reach. Store it in a password manager.
  • •It protects file contents, not the folder name in transit. Folder names are already encrypted client-side under your vault key; the folder password governs the files' content keys.
  • •You must re-key before unprotecting. Removing a folder password requires the client to first re-key its files back to the vault passphrase, so nothing is left wrapped under a key you're about to discard.

Where to go next