Skip to main content

Module keys

Module keys 

Source
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_generated and rekey_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 --help and the CHANGELOG say so.
recovery
12.3: the recovery code, version 1 (the keys note, section 3).

Structs§

FileKeyInfo
What a brain’s page 0 says about its key, read without the key.
Resolved
What resolve found.
StoredRekeyError
A rekey through rekey_stored failed. entries says what became of the key-store entries.

Enums§

Resolution
The chain’s answer.
Secret
A secret that opens a brain.
SecretKind
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.
StoredSecret
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_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.

Traits§

KeyStore
Where brains’ secrets are kept, each found by its brain’s salt: the OS keychain (the keychain feature), or the test store.

Functions§

create_generated
Create a brain at path under a freshly generated key (the keys note, section 1). In this order, so there’s never a brain at path whose key is only in memory:
default_store
The key store this build uses, if it has one: in a dev-hooks build, the directory MNEMO_DEV_KEYSTORE names when it’s set; otherwise the OS keychain when the keychain feature is on (macOS, Windows, Linux). None otherwise. Making one asks nothing of the store: whether it can be used shows at the first lookup, or through KeyStore::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.
kdf_grade_note
The text mnemo info shows 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. what names 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 ssh asks of a private key (the keys note, section 6).
rekey_stored
Rekey db to new, keeping it in store under 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-cmd is, 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 after timeout.
store_and_check
Store secret under salt, 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’s persist: keep the key, given the brain’s salt.