Expand description
12.3: keys (docs/design/12.3-keys.md).
The parts mnemo init, recovery-code, rekey and, later, onboard,
unlock and the MCP server are made of:
recovery: the recovery code’s encoder and parser;KeyStore: where a brain’s secret is kept, found by its salt;resolve: the chain of key sources, picked by the file’s kind;create_generatedandrekey_stored: the orders that keep a secret that opens the file at every step;display: the rule for showing a recovery code.
The OS keychain store arrives in step 2. Until then
default_store is None in a release build.
Modules§
- display
- 12.3: the display rule (the keys note, section 7). A recovery code is
shown only to a person at a terminal: stdout and stdin are terminals, no
known agent-harness marker is set, and the controlling terminal opens.
It’s shown through the controlling terminal, after a key press, on the
alternate screen, so nothing reaches stdout or stays in scrollback. On
Windows there’s no alternate screen (the escapes are Unix-only), so the
code stays in the console’s scrollback;
init --helpand the CHANGELOG say so. - recovery
- 12.3: the recovery code, version 1 (the keys note, section 3).
Structs§
- File
KeyInfo - What a brain’s page 0 says about its key, read without the key.
- Resolved
- What
resolvefound. - Slow
Store Note - A note on stderr when the key store hasn’t answered within
after: a keychain asking whether this program may read the key blocks until someone answers it (KEYCHAIN-REPROMPT). Dropping the guard cancels it. - Stored
Rekey Error - A rekey through
rekey_storedfailed.entriessays what became of the key-store entries.
Enums§
- Resolution
- The chain’s answer.
- Secret
- A secret that opens a brain.
- Secret
Kind - 12.3: what kind of secret a caller handed the engine. A passphrase is a person’s; a key is a uniformly random 256-bit value a machine made.
- Source
- Where a secret came from.
- Stored
Secret - A secret as a key store keeps it, typed so an entry is never guessed.
Constants§
- CLI_
COMMAND_ TIMEOUT - The key command’s timeout in the CLI.
- KEYCHAIN_
ALLOW_ HINT - What to do when the keychain held the key back (KEYCHAIN-REPROMPT): macOS ties a keychain item to the program that reads it, so the first read by a new mnemo (after each upgrade) asks, and a hook or server can’t answer.
- KEYCHAIN_
SERVICE - The keychain’s service name for every brain’s entry; the account is the brain’s salt in lower-case hex (the keys note, section 4).
- SERVER_
COMMAND_ TIMEOUT - The key command’s timeout in the MCP server, which has no terminal.
- SLOW_
STORE_ NOTE_ AFTER - How long a hook or server waits for the key store before saying so.
Traits§
- KeyStore
- Where brains’ secrets are kept, each found by its brain’s salt: the OS
keychain (the
keychainfeature), or the test store.
Functions§
- create_
generated - Create a brain at
pathunder a freshly generated key (the keys note, section 1). In this order, so there’s never a brain atpathwhose key is only in memory: - default_
store - The key store this build uses, if it has one: in a
dev-hooksbuild, the directoryMNEMO_DEV_KEYSTOREnames when it’s set; otherwise the OS keychain when thekeychainfeature is on (macOS, Windows, Linux).Noneotherwise. Making one asks nothing of the store: whether it can be used shows at the first lookup, or throughKeyStore::check_available. - file_
info - Read the salt and KDF parameters from
path’s page 0, with no key and no lock. A torn page 0 is an error here (step 2 adds the salts from the WAL’s header frames). - hex
- The lower-case hex of
bytes. - is_
store_ error - Whether an error from
resolvecame from the key store itself (a refusal or a failure, never a missing entry, which isResolution::NoSource). - kdf_
grade_ note - The text
mnemo infoshows for a file’s KDF parameters, when they need a word: raw-key parameters with a passphrase, or test-grade ones. - parse_
key_ text - A key written as text: 64 hex digits, or a recovery code.
whatnames where it came from, for the error. - read_
key_ file - Read a key file: 32 raw bytes, 64 hex digits, or a recovery code. On
Unix it must be a regular file this user owns, with no access for group
or others, as
sshasks of a private key (the keys note, section 6). - rekey_
stored - Rekey
dbtonew, keeping it instoreunder the new salt (the keys note, section 4). The order: - resolve
- Find the secret for the brain at
path(the keys note, section 6). - run_
key_ command - Run
cmd(split as--embed-cmdis, no shell) and read a key from the first line of its output (the keys note, section 6): stdin closed, stderr passed through, stdout capped at 4 KiB, its exit status checked, and killed aftertimeout. - store_
and_ check - Store
secretundersalt, then read it back. A store that doesn’t give back what it was given has its entry removed, and the call fails. - write_
new_ key_ file - Write a new key file: created new (never over an existing name, a symlink included) with mode 0600, holding the key’s 64 hex digits.
Type Aliases§
- Persist
create_generated’spersist: keep the key, given the brain’s salt.