DiaryVault supports opt-in, per-note, end-to-end encryption. Notes you mark as encrypted are protected with a passphrase only you know — nobody else, including us and your cloud provider, can read them. This page describes the architecture in depth.

Source: lib/features/encryption/

1. Design goals
2. Threat model
3. Key hierarchy
4. The keychain
5. Cryptographic primitives
6. Storage layout
7. Encrypted note payload format
8. Sync hash design
9. Session lifecycle
10. Multi-device semantics
11. Passphrase change and recovery rotation
12. User-facing flows
13. What encrypted notes are excluded from
14. Limitations and caveats

1. Opt-in per note. Encryption is not all-or-nothing. A note is either plain or encrypted, chosen in the editor with a lock toggle.
2. Cloud-provider-blind. The cloud store (Dropbox / Google Drive / Nextcloud) only ever sees ciphertext for encrypted notes.
3. Recoverable. Forgetting the passphrase must not mean instant data loss — a recovery code provides a second key slot.
4. Sync-friendly. Encrypted notes must sync across devices like normal notes, including conflict resolution, without any server-side changes.
5. Zero plaintext at rest. Title, body, and plain-text preview of an encrypted note are never written to disk or cloud in plaintext.

Protected against:

• Anyone with read access to your cloud app folder (cloud provider, someone who steals your Dropbox credentials) — they see only base64 ciphertext for encrypted note content.
• Anyone with read access to the local SQLite database — same.

NOT protected against / out of scope:

• An attacker who knows your passphrase. The passphrase is the root of all key material.
• A device compromise while the session is unlocked. Master keys live in process memory while the encrypted notes view is open.
• Asset files. Images/videos/audio attached to an encrypted note are uploaded to the cloud unencrypted (see Limitations). Only their paths inside the note body are encrypted.
• Metadata. Note creation/modification timestamps, the number of encrypted notes, ciphertext lengths, and tags remain visible.
• Guessing attacks on weak passphrases. Argon2id makes them expensive, not impossible. Choose a long passphrase.

The scheme is classic envelope encryption with three layers:

passphrase ──Argon2id──► KEK-pass ──┐
                                     ├──► unwrap ──► MASTER KEY (random 256-bit)
recovery code ──Argon2id──► KEK-rec ─┘                      │
                                                            │ unwrap
                                                            ▼
                                              per-note DEK (random 256-bit)
                                                            │
                                                            ▼
                                       AES-256-GCM encrypts {title, body, plain_text}

Why a master key at all (instead of deriving note keys directly from the passphrase)?

1. Cheap passphrase changes. Changing the passphrase re-wraps one master key instead of re-wrapping every note's DEK. (In practice we still re-stamp every note row so sync propagates — but the DEKs themselves don't change, and the master key is never re-generated.)
2. A single recovery code. The recovery code wraps the same master key, so one code recovers all notes, forever, regardless of when they were created.
3. Passphrase verification with zero notes. The locally cached wrapped master key lets the app distinguish "wrong passphrase" from "no notes yet".

The salt must be shared between devices, which is why it travels with the notes (see The keychain) — two devices that set up encryption independently generate different random salts and master keys, even with the same passphrase. The multi-device machinery below reconciles that.

The keychain is everything needed to unlock the master key, while containing no secrets itself:

class EncryptionKeychain {
  final KdfParams kdfParams;           // Argon2id params + 16-byte random salt
  final WrappedKey wrappedMkPass;      // MK encrypted with KEK-pass
  final WrappedKey wrappedMkRecovery;  // MK encrypted with KEK-rec
}

A keychain is stored in two places:

1. Locally (shared preferences, key encryption_keychain_cache) so unlock doesn't need a database hit.
2. Stamped on every encrypted note row (enc_salt, enc_wrapped_mk_pass, enc_wrapped_mk_recovery columns). Because the keychain rides along with the notes, it travels with cloud sync for free — there is no separate metadata file to keep consistent. A fresh device hydrates its keychain from any synced encrypted note row.

Because the GCM authentication tag fails on the wrong KEK, unwrapping doubles as passphrase verification — there is no separate password hash to leak.

All primitives live in lib/features/encryption/core/crypto_service.dart (stateless, no I/O).

encryption_version (currently 1) is stamped on every note row. KDF cost parameters are versioned constants, so a future version bump can strengthen them without a migration — only the salt is stored per note.

Notes table (SQLite schema v4), encryption columns:

The same columns appear in the cloud copy of the note (<noteId>.json), so the cloud artifact is self-contained: any device that knows the passphrase can derive everything it needs from a synced note row.

The three sensitive fields are packed into one JSON document and encrypted under the note's DEK with a single random IV:

plaintext:  {"title": ..., "body": <quill delta JSON string>, "plain_text": ...}
ciphertext: base64( nonce ‖ AES-256-GCM_DEK(plaintext) ‖ tag )  → stored in `body`

The body embeds asset references (image/video paths) — those are inside the ciphertext and therefore hidden. Note that the editor's dirty-check and asset trimming always operate on the plaintext body before encryption; the shared write paths never see ciphertext.

Normal notes sync by comparing a SHA-1 hash of title + created_at + body + tags. For encrypted notes this has two problems:

1. Ciphertext hashing is useless — random IVs mean re-encrypting identical content yields different ciphertext.
2. Plaintext hashing leaks — an unsalted hash of the plaintext lets the cloud provider run confirmation attacks ("is this note about X?").

So encrypted notes use a keyed, deterministic hash:

hash = HMAC-SHA256(key = master key,
       title + created_at + body(with asset paths reduced to file names) + tags
       + "|enc|" + enc_salt + enc_wrapped_mk_pass + enc_wrapped_mk_recovery + wrapped_dek)

• Deterministic over the plaintext, so change detection survives re-encryption.
• Keyed, so the cloud provider can't precompute or confirm anything.
• Includes the keychain material, so a passphrase change or recovery-code rotation changes the hash of every encrypted note and therefore syncs to other devices as if it were a normal note edit — no special sync protocol needed.

The editor's close-dialog dirty check recomputes exactly this composition (via IEncryptedNotesRepository.computeEditorHash), using the keychain stamped on the note's row — which matters when the note was created on another device.

EncryptionSessionService owns the session:

• The master key exists only in memory (SecretKey), never persisted.
• States: EncryptionDisabled → (setup) → EncryptionLocked ⇄ EncryptionUnlocked.
• The encrypted notes view is session-scoped: entering it requires an unlock; leaving it calls lock(), which drops all in-memory keys and clears the repository's decrypted-note cache.
• On app start, initialize() loads the cached keychain, or — on a fresh device after sync — hydrates it from an encrypted note row.

This is where the design earns its keep. Keychains are identified by their enc_wrapped_mk_pass blob.

Two devices that each run setup generate different keychains (different random salt + master key), even with the same passphrase. After sync, both keychains' notes exist on both devices. unlock() therefore tries every distinct keychain found locally (the cached one plus all keychains stamped on note rows) and caches each master key the passphrase opens:

• Decryption always uses the note's own keychain — device A's notes decrypt on device B transparently.
• The primary keychain (used to encrypt new notes) stays the device's own.

A note stays bound to the keychain it was created with. When you edit a synced note, the stored row is the source of truth: its DEK is unwrapped with its own keychain's master key, content is re-encrypted, and its keychain columns are left untouched. The passphrase it answers to never changes just because you edited it on another device — this avoids key material ping-ponging between devices on every save.

They remain locked: the encrypted notes list shows a "🔒 Locked note" placeholder ("Protected by a different passphrase"). Tapping it prompts for that note's passphrase and calls unlockNote(noteId, passphrase), which rebuilds the keychain from the note row and opens it via unlockAdditionalKeychain — an in-memory-only unlock that never replaces the primary keychain. After that, the note decrypts and can be edited like any other.

changePassphrase converges every note the session can currently decrypt onto the new keychain (foreign notes get their DEK re-wrapped under the primary master key). Hashes change, so sync propagates the re-stamped rows. On the next unlock elsewhere, if the device's cached keychain no longer opens but a synced one does, the synced keychain is adopted as the new primary (and persisted). Net effect: one passphrase change + one sync → all devices follow.

Both operations re-wrap key material and rely on hash-driven sync propagation:

• changePassphrase(old, new): verifies old, generates fresh KDF params (new salt), re-wraps the same master key with the new KEK, then re-stamps every openable encrypted note (recomputing hashes). The master key itself never changes, so DEKs don't need re-encryption — except foreign-keychain notes, which converge (above).
• regenerateRecoveryCode(passphrase): generates a new code, re-wraps the master key's recovery slot, propagates the same way. The old code dies everywhere after sync.

If you forget the passphrase and lose the recovery code, the notes are unrecoverable — by design. The setup flow makes you acknowledge this explicitly.

• The home list and search (all normal-note queries filter is_encrypted = 0).
• Export (JSON / text / PDF all go through fetchNotes, which applies the same filter).

1. Asset files are not encrypted. Images/videos/audio attached to an encrypted note are uploaded to the cloud as plain files. Only the note's text content (and the asset paths inside it) are protected. If a photo itself is sensitive, treat it as visible to your cloud provider. (This is the top candidate for a future encryption_version 2.)
2. Tags are stored and synced in plaintext, including on encrypted notes.
3. Metadata leakage: timestamps, note count, ciphertext sizes, and the mere existence of encrypted notes are visible.
4. Cross-platform asset paths: asset paths embedded in an encrypted note's ciphertext can't be rewritten during sync (the sync layer can't read ciphertext). Android↔Android works because the app-private directory path is identical; Android↔iOS asset references in encrypted notes may not resolve.
5. Session is per-launch and per-view: there is no "keep unlocked for X minutes" option — leaving the encrypted notes view locks everything.
6. The passphrase is the single root of trust. There is no escrow, no server-side reset. Passphrase + recovery code both lost = data gone.