Identities and keys

An identity is a set of signing keys, generated on your machine or imported by you, kept in this machine’s key store and opened by the passcode. The app uses its own key store alone and leaves the system keychain as it is.

Two kinds of identity

Recovery-phrase identity

Derived from 12 recovery words, with two keys at once, one for each role: the Recorder at m/44'/60'/0'/0/0, the User at m/44'/60'/0'/0/1. The two addresses differ, and each needs a little gas.

Local-key identity

An existing private key or key file you import. It fills the one role chosen at import, and the other role stays empty.

A machine can hold several identities, switched with the identity chip at the top of the sidebar. Each role of each identity has its own key, address and data folder.

The passcode

The passcode is 8 letters or digits, case-sensitive. A machine with a passcode opens with the passcode gate every time; the eighth character submits it.

• After 5 wrong tries in a row the gate becomes “Locked”, and recovery is the way on. The count is kept on disk and survives restarting the app.
• A passcode that is too simple is refused on the spot: eight identical characters, or digits that run in sequence or read as a date. When the current passcode is digits only, Settings suggests adding letters.
• The try limit stops someone sitting at the machine from guessing. Against someone who copies the key store file away, the protection is the passcode itself and the encryption work every try has to repeat; so mix letters and digits.

Locking

“Lock” in the sidebar, or ⌘L, locks at once: the master key is wiped from memory, the data folder is closed, and background work stops: ledger checks, grant re-verification, revocation watch and sending the pending queue. After unlocking, the data folder reopens, anything due runs, and the pending queue goes back to waiting for its receipts.

“Auto-lock” in Settings › Identity key is on out of the box: after the “Idle time” (1, 5, 15, 30 or 60 minutes; 15 by default) passes idle, the app locks itself, and any key press or mouse movement restarts the clock. Transactions already sent complete as usual.

The primary identity

The first identity on a machine is its primary identity by default; another can be made primary later in Settings › Identity key. When the passcode is forgotten, the primary identity’s credentials alone can reset it:

• A recovery-phrase primary: its 12 recovery words.
• A local-key primary: the key file exported from it, with the file password.

“Set as primary…” asks for this machine’s passcode. The old primary becomes a secondary identity, and every key and all local data are re-encrypted under a new master key; the passcode stays the same. The change happens completely or leaves everything as it was. A local-key identity imported from a raw private key exports its key file first, and can then become primary.

A forgotten passcode

On the passcode gate, press “Forgot passcode” to reach “Recover”: fill in the primary identity’s 12 recovery words, or choose the primary’s key file and enter the file password, then set a new passcode. On success the wrong-try count is cleared and the old passcode stops working. A secondary identity’s credentials are refused; use the primary’s, or restore from a backup.

At the bottom of the recovery card is “Restore from backup…”: choose a whole-machine backup file, enter the backup password, confirm “Replace this machine with the backup?” and set a new passcode. The machine’s identities, keys and data are replaced whole by the backup’s, re-encrypted under the new passcode.

Backing up keys

Recovery phrase

Written on paper. After entering the passcode in Settings › Identity key, “Show recovery phrase…” shows it once more.

Key file

“Export key file…” writes a standard keystore file that other wallets can read too. The file password is at least 8 characters, and the file can be read by you alone; the app reads it back to check it, and the backup counts once it passes. For a local-key primary, it is also how the passcode is recovered.

Whole-machine backup

Backs up every identity, ledger and setting together; see Whole-machine backup.

“Backup status” on the Identity key page says how far this identity is backed up: “Recovery phrase confirmed, key file exported”, “Recovery phrase confirmed”, “Key file exported” or “Not backed up”.

Changing identity

Switch identity…

Lists every identity; click a row to see both roles’ full addresses, and press “Switch” to change to it.

New identity…

Generate, write down and check 12 words, as in wizard step 2.

Import key…

Three tabs: “Recovery phrase”, “Private key” (64 hexadecimal digits, with or without 0x) and “Key file”. For a private key or key file, choose “Import as which identity”: “Recorder” or “User”.

Rename…

Changes an identity’s label, which serves to tell identities apart.

New and imported identities are secondary; the first identity created on a machine becomes its primary. When an identity is imported from its recovery phrase, private key or key file, its ledger stays on the original machine and in its backups; to bring it over, see Fetching the ledger.

Rules for the identity key

Every word an identity key signs may one day be checked. It is used in Zikaron alone: it signs ledger entries and claim co-signatures, and it sends anchoring transactions.

Gas only

Keep assets at another address. The identity key’s address is public, and it needs just enough for gas.

Signed by Zikaron alone

Answer signing requests from other apps and web pages with another key. A ledger entry’s signature is a few dozen bytes; an ordinary-looking text handed to you for signing may be an entry someone else drafted in your name.

A plain address

The identity key’s address stays a plain address; code and delegation belong to other addresses. Once an address carries code or a delegation, every anchor it sends in that time is void.

One key, one ledger

A key serves this one ledger alone.

Deleting an identity

“Delete identity…” at the bottom of the Identity key page: after this machine’s passcode, it removes the keys from the key store and the identity’s registration, and keeps the data folders.

• A primary identity first passes the primary role to another identity, and can then be deleted.
• An identity first backs up its key or confirms its recovery phrase, and can then be deleted.
• A Recorder records a handover before deleting, so a new key can continue the ledger; see Handing over a ledger.