Sempere
Guide contents

How it works

How encryption works

Device keys, the recovery key, the vault key, what each file is encrypted to, and what your storage provider can and cannot see.

Sempere encrypts every file on your device before it is saved, with keys that only you hold. Whatever stores the vault (iCloud Drive, a NAS, a backup disk) holds files it cannot read.

How a vault is encrypted Three keys: the iPad's key and the Mac's key, each made on its device and kept in its Keychain, and the recovery key, printed in the recovery kit and kept by no device. vault.json, which anyone can read, lists the devices and holds the vault key wrapped once for each of the three keys; the home device signs the list. Each note revision file starts with one stanza that seals the file's own key to the vault identity, derived from the vault key, with ML-KEM-768 plus X25519, followed by the encrypted body: an authentication tag keyed from the vault key, then the note as gzip-compressed JSON. The storage provider sees file names, sizes, times, attachment kinds and vault.json, but not titles, ink, text, tags or recordings. iPad's key in the iPad'sKeychain Recovery on the paper kit;no device has it Mac's key in the Mac'sKeychain each opens a wrap vault.json readable by anyone The devices, signed by the home device.The vault key, wrapped once for each deviceand once for the recovery key. notes/<id>/…-a1b2c3d4-7.delta.age One stanza, whatever the number of devices the file's own key, sealed to the vault identity(ML-KEM-768 + X25519) Encrypted body: a tag keyed from the vaultkey, then your note as gzip JSON. Your storage provider sees file names (random ids), sizes, times,attachment kinds, and vault.json. Not your titles, ink, text, tags or recordings.
Each device key, and the recovery key, opens the vault key; every file is encrypted once, to the vault identity.

Three kinds of key

  • Device keys. Each device makes its own key when it creates or joins a vault. The key stays in that device’s Keychain, available only on that device; it is never exported, copied or synced through iCloud Keychain. Each device also has a signing key, in the Secure Enclave where the device has one.
  • The recovery key. One more key per vault, printed in the recovery kit when the vault is created. No device keeps it. It opens the vault read-only, and it can take over managing devices.
  • The vault key. A random key that every file depends on. vault.json holds it wrapped once for each device and once for the recovery key, so each of those keys opens it. A new vault key starts whenever a device is removed (an epoch); old files keep the key they were written under, and the new epoch’s record keeps the old key for the devices still listed.

Keys are text in the age format. A secret key starts with AGE-SECRET-KEY-PQ-1, a public key with age1pq1.

Post-quantum

The keys are hybrid: ML-KEM-768, a post-quantum algorithm, combined with X25519, the elliptic curve classic age uses. An attacker would have to break both. This guards against someone storing your files today to decrypt them with a future quantum computer. Classic age keys (AGE-SECRET-KEY-1…) are refused. Details: docs/post-quantum.md.

What each file is encrypted to

Each saved file (a note revision, an attachment, the settings) is a standard age file:

  • a fresh random file key encrypts the content (ChaCha20-Poly1305);
  • the header holds that file key once, sealed to the vault identity, an age key derived from the vault key.

So a file’s header is the same size whatever the number of devices, and adding a device rewrites no file.

Authentication

Keys derived from the vault key also authenticate:

  • every note file carries a tag, so a file that someone planted or changed is rejected instead of being trusted;
  • attachment file names are derived from it, so the names give nothing away;
  • the device list in vault.json is tagged, and signed by the home device (the one that manages devices) with two signature schemes, P-256 and ML-DSA-65. Someone with write access to your storage cannot add their own device or rename one: your devices refuse a list that does not check.

Each device remembers what it checked, and the chain of device changes goes back to the vault’s root fingerprint, which never changes and is printed on the recovery kit. A new device checks the vault against the six words the home device shows when it approves the join, or against the kit’s root when it takes over. Devices and keys explains the device model.

What your storage provider sees

Encryption keeps what you wrote, drew, recorded and attached private. It does not hide that a vault exists. Whoever holds the files can see:

  • file and folder names: random note ids, device ids and counters, never titles;
  • file sizes (attachments are padded to a size class) and each attachment’s kind (image, PDF, audio, video);
  • when files were written, which shows when you work;
  • what vault.json holds in the clear: the devices’ public keys and names, which device manages the others, the vault’s display name, id and creation date; and the requests of devices waiting to join.

Titles, notebooks, tags, text, ink, recordings and transcripts are inside the encrypted files.

The passphrase copy

If you turned on Also store the recovery key under a passphrase, the vault’s keys/ folder holds the recovery key encrypted with your passphrase (scrypt). Anyone with your files can try passphrases against it offline. That is why Sempere refuses a passphrase it estimates below about 70 bits.

Limits

Encryption does not protect an unlocked device, exports (they are plain files), or keys you lose. Removing a device protects what you write afterward, not what it already read. The security page lists every limit. To check the format yourself, read docs/format.md, or open a note with standard tools: Read your notes without Sempere.