Local data and backups

Ledgers, settings and the grants you receive are all kept encrypted on your machine. How much comes back after a computer is replaced or lost depends on which backups were made beforehand.

Local data is always encrypted

All local data is encrypted under one master key, and the master key is opened by the passcode. Ledger entries, settings, the pending queue, the identity registry, the record index, and received grants and terms files are all encrypted with a local data key derived from the master key (XChaCha20-Poly1305). While the app is locked all of it stays sealed, and someone who copies this machine’s files needs the passcode to read them.

Three kinds of file sit outside the master key’s encryption, because they are meant for others to read or must be read before unlocking:

• Read before unlocking: the key store itself (encrypted separately), the machine settings machine.json, and the data folder pointer.
• Exports meant for others: record kits and the record kit index, grant files, credentials, ledger mirrors, key files and whole-machine backups (a whole-machine backup is encrypted with its backup password).
• Files other people send you.

Where the files live

Machine folder

Holds the key store, the identity registry, the machine settings and the record kit index. Its default location is ~/.zikaron-desk.d/; the pointer file ~/.zikaron-desk (one line holding an absolute path) can point it elsewhere.

Data folders

One for each role of each identity, holding the ledger, settings, pending queue, received grants and so on.

Whole-machine backup

One backup file restores everything: every identity and key on this machine, all local data and all settings. The master key, the passcode and the wrong-try count stay on the machine and stay out of the backup.

1. “Export backup…” in Settings › Local data: enter this machine’s passcode, choose a backup password (at least 8 characters) and repeat it, choose where to save it, and press “Export”.
2. The file is named zikaron-backup-YYYY-MM-DD.zikaron; a second export on the same day gets a number, and earlier files stay as they are.
3. The app reads the file back and opens it once to check it, and then says “Backup exported: …”.

A backup derives its key from the backup password with scrypt (N=262144, r=8, p=1) and is encrypted with XChaCha20-Poly1305. The backup password is the one key to the backup; keep it safe in another place.

Restoring from a backup. “Restore from backup…”: choose the backup file, enter the backup password and this machine’s passcode, and press “Recover”. The machine’s identities, keys and data are replaced whole by the backup’s, and the passcode stays the same; whatever this machine held beyond the backup is replaced with it. The restore happens completely or leaves everything as it was. Old files that still fail to open afterwards are moved unchanged into the set-aside folder in the machine folder.

When ledger entries or received grants have been added since the last backup, the Alerts page shows “N not backed up”; export again.

With the recovery phrase alone

A recovery phrase brings back keys. Entry files live on the machine, and the chain holds their fingerprints; so with the recovery phrase alone, what comes back is the data readable on chain; the entries themselves rest on a whole-machine backup, and the original files on what you keep yourself.

Fetching the ledger

When an identity is imported again from its recovery phrase, private key or key file, a red box appears at the top of the Local data page: “This identity was restored: its ledger has not been fetched”. Until the ledger is fetched, the identity can read and writing is paused. To fetch it, choose a whole-machine backup, enter the backup password and press “Fetch ledger”. The app takes this identity’s ledger from the backup and compares it with this key’s anchors on chain:

Everything matches

Every anchor on chain is in the ledger, and writing opens again.

The chain has newer entries

Some anchors on chain are missing from the fetched ledger, and the identity stays read-only. Find the newer backup and fetch again.

Conflict with entries on this machine

A conflict card appears; after “Fetch and replace”, the machine’s previous data is kept as “Old data” and can be viewed read-only.

This way, the ledger that continues is always the newest one.

Ledger mirror

A Recorder’s Local data page has “Export ledger mirror…”: it exports the ledger to a folder you choose, laid out as ZIKARON-backup/<address>/<role>; when the folder already holds an older mirror, only the new entries are added. A mirror is an export for other tools to read, and entries for the zikaron command line come from here; see Command line. To restore a machine, use a whole-machine backup.

Data folder

Change data folder…

Lasts for this session; the next launch returns to this identity’s own data folder.

Move to an empty folder

Moves the data folder there and makes it this identity’s data folder; the files at the old location stay as they are, to clear when you choose.

Import grants folder…

For the User: imports the grant entry files in a folder in one go.

Reconcile

“Reconcile now” under “Advanced options” checks the local ledger offline and, once it passes, allows writing again.

One window at a time writes to a data folder; a window opened later can only read, and shows the read-only bar at the top.

When the ledger turns read-only

Ledger handed over

The ledger now belongs to a new key, and this machine can read it.

Ledger chain broken

The ledger check found a broken chain. Press “Go to Restore” and restore from a whole-machine backup, or reconcile under “Advanced options”.

Another window is writing

Close the other window, then reopen this data folder (lock and unlock, or restart the app) to write; or carry on reading here.

Restored identity

Read-only until its ledger is fetched; see above.

Backup essentials

1. Write the recovery phrase on paper and keep it apart from the computer.
2. Keep whole-machine backups on another disk, and the backup password in another place.
3. Keep the original files yourself. The ledger records fingerprints; to prove something later, you show the original, byte for byte.