How Nookvault protects your files
A plain-English overview of the design, including its limits.
Keys
passcode ──Argon2id (64 MiB, 3 passes, random salt)──► passcode key ─┐ recovery key (24 characters, 120 bits) ───────HKDF──► recovery key ──┼─ wraps ─► master key (256-bit, random) Face ID: master key in the Keychain, bound to your current Face ID ──┘ master key ─► metadata key (seals file names, folders and dates) master key ─► per-file keys (a new random key for every file and thumbnail) master key ─► share key pair (lets the share extension add files without unlocking)
- Your vault is encrypted with a random master key. It's never stored in the clear: only wrapped (encrypted) by your passcode and by your recovery key.
- Your passcode goes through Argon2id, which is deliberately slow and memory-hungry, so each guess is expensive even on powerful hardware. The app also adds increasing delays after wrong attempts, and can erase the vault after ten.
- Changing your passcode re-wraps the master key. Nothing needs re-encrypting.
- Face ID keeps a copy of the master key in the iOS Keychain, readable only after a successful Face ID check on this device. It's discarded automatically if someone adds a new face.
Files
Each file is split into 1 MiB chunks, each sealed with AES-256-GCM under that file's own key. Every chunk is bound to the file's ID, its position and whether it's the last chunk, so chunks can't be swapped, reordered or cut off without detection. Videos stream straight from the encrypted file and are never written to disk unencrypted. Thumbnails are encrypted the same way, separately.
The database of names, folders and dates stores each record sealed with the metadata key. Only what's needed to sort and filter (which folder an item is in, its type, whether it's in the Trash) is kept unencrypted, and only on your device.
The share extension
Saving from another app's share sheet never unlocks your vault. The extension encrypts incoming files to the vault's public key (X25519). Only the unlocked app holds the matching private key, so it adds them the next time you open Nookvault.
iCloud Backup
Backup sends only what's already encrypted: the sealed records, the encrypted files (in 64 MiB pieces) and your wrapped keys. On a new iPhone you need your passcode or recovery key to unwrap the master key. Downloaded files are checked against their recorded fingerprint (SHA-256) before use.
Who can see what
| File contents | Names, folders, dates | Number and size of files | |
|---|---|---|---|
| Someone with your unlocked iPhone and vault | Yes | Yes | Yes |
| Someone with your iPhone but not your passcode | No | No | Roughly |
| Apple (iCloud Backup on) | No | No | Yes, plus when they change |
| Us | No | No | No: we have no servers or analytics |
Limits, honestly
- A short passcode is easier to guess if someone copies your encrypted vault. Longer, or letters and numbers, is stronger.
- Nookvault can't protect against malware on a compromised or jailbroken device, or against someone watching you type your passcode.
- While a file is open, or shared to another app, it's decrypted in memory or into a temporary folder that's wiped when the vault locks.
- If you lose both your passcode and recovery key, your vault can't be recovered. That's the trade-off of real end-to-end encryption.
Building blocks
Apple CryptoKit (AES-GCM, HKDF, X25519, SHA-256), libsodium (Argon2id) and SQLite via GRDB. No custom cryptographic algorithms.