hacks/bip85keys/README.md

bip85keys

bip85keys turns a BIP-39 mnemonic into key pairs that can be recreated from that mnemonic at any time. The same mnemonic, key type and index always give the same key.

It uses the BIP-85 entropy deriver from git.eeqj.de/sneak/secret/pkg/bip85 and takes the same steps as that repository's agehd package.

Commands are grouped by key type: bip85keys ssh ... for ed25519 SSH keys (in this PR) and bip85keys age ... for age identities (planned, see below).

Derivation

The mnemonic is turned into a key like this:

1. mnemonic -> BIP-39 seed (empty passphrase);
2. seed -> BIP-32 master key;
3. master key -> 64 bytes of BIP-85 entropy at the path below;
4. entropy -> BIP-85 DRNG (SHAKE256); read 32 bytes;
5. those 32 bytes become the key in the way the key type needs.

The path is:

m/83696968'/592366788'/<app>'/<n>'

• 83696968 is the fixed BIP-85 purpose.
• 592366788 is the vendor id, sha256("berlin.sneak") & 0x7fffffff, the same one agehd uses.
• app is the application id of the key type; each type has its own.
• n is the key index: flag --index / -n, default 0.

Giving it the mnemonic

The mnemonic itself is never a command-line argument. It is looked for in this order; the first one found wins:

1. --mnemonic-command <command>: a shell command, run with sh -c, whose standard output is the mnemonic. Example: --mnemonic-command 'secret get foo'. Whitespace around the output is dropped. If the command exits with a non-zero status, the tool prints its standard error and exits with status 1.
2. Environment variable BIP85KEYS_MNEMONIC_COMMAND: the same, as a shell command held in the environment.
3. Environment variable BIP85KEYS_MNEMONIC: the mnemonic itself.
4. A prompt on the terminal with echo turned off.

If none of these is available and standard input is not a terminal, the tool refuses and exits with status 1. A mnemonic that fails the BIP-39 checksum is refused with a message saying so.

Every command takes --index / -n and --mnemonic-command, and has --help. bip85keys --version prints the version set at build time.

SSH keys: bip85keys ssh

Only ed25519 keys are produced. The application id is 1822331379, sha256("bip85ssh") & 0x7fffffff, so the path is m/83696968'/592366788'/1822331379'/<n>'. The 32 bytes from step 4 are the ed25519 seed.

Test vector, mnemonic abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about:

index 0: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIA1esgfi4OeaywgKh0o5r/8lMOUlUD/N+YoAiC8SNEML
index 1: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB26T7hdDuUF6wfTQ7NpIpyeTgGha4NlhQjaAhap5dqs

bip85keys ssh pub

Prints one authorized_keys line to standard output:

ssh-ed25519 <key> <comment>

The comment defaults to bip85keys/ssh/<n>; change it with --comment.

bip85keys ssh priv

Prints the unencrypted private key in OpenSSH format (the -----BEGIN OPENSSH PRIVATE KEY----- block that ssh reads) to standard output and nothing else, so it can be redirected into a file. The key's comment is the same as for pub.

bip85keys ssh install <[user@]host> [-- ssh options...]

Runs the system ssh to the host and, on the host:

• creates ~/.ssh with mode 0700 if it is missing;
• creates ~/.ssh/authorized_keys with mode 0600 if it is missing;
• appends the pub line only if an identical line is not already there.

It then prints added or already present. How this ssh connection authenticates is up to the user's normal ssh setup (existing keys, agent, password). Anything after -- is passed to ssh unchanged.

bip85keys ssh ssh <host> [ssh arguments...]

Derives the key, serves it from an SSH agent that runs inside the tool on a unix socket in a new private 0700 temporary directory, then runs the system ssh with -o IdentityAgent=<that socket> followed by the host and all remaining arguments unchanged. The tool exits with ssh's exit status and removes the socket and directory on the way out. The private key is never written to disk.

age identities: bip85keys age (planned)

Not in this PR, which delivers the SSH type first; it is the next type to add. bip85keys age pub and bip85keys age priv will derive exactly what sneak/secret derives with its agehd package: application id 733482323 (sha256("secret") & 0x7fffffff), so the path is m/83696968'/592366788'/733482323'/<n>'; the 32 bytes from step 4 are clamped as X25519 requires and encoded as an AGE-SECRET-KEY-1... identity. An age key from this tool for a given mnemonic and index will equal the one secret derives.

Adding a key type

Adding a key type is one package under internal/ that turns the 32 derived bytes into that type's key, plus one cobra subcommand under internal/cli/ that groups its commands.

Errors

Errors go to standard error and the exit status is 1, except for ssh ssh, which passes through ssh's own exit status.

Building and running

make build    # produces ./bip85keys
make check    # fmt-check, lint (golangci-lint) and tests

Examples:

bip85keys ssh pub -n 3 --mnemonic-command 'secret get foo'
bip85keys ssh priv -n 3 > ~/.ssh/id_bip85_3
bip85keys ssh install -n 3 user@example.com
bip85keys ssh ssh -n 3 user@example.com uptime