8439d6bfad
The tool will cover more key types than SSH, so the directory, module and binary become bip85keys and the commands are grouped by type: "bip85keys ssh pub|priv|install|ssh" now, "bip85keys age pub|priv" planned. The README states the age derivation (agehd's path in sneak/secret) and that adding a type is one package plus one subcommand. The SSH application id and everything else stay as before. Model: fable-5-1
141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
# bip85keys
|
|
|
|
`bip85keys` turns a BIP-39 mnemonic (or a BIP-32 `xprv`) into key pairs that can
|
|
be recreated from that secret at any time. The same secret, 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 secret is turned into a key like this:
|
|
|
|
1. mnemonic -> BIP-39 seed (empty passphrase), or the `xprv` is parsed directly;
|
|
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 secret
|
|
|
|
The secret is never taken as a command-line argument. It is looked for in this
|
|
order; the first one found wins:
|
|
|
|
1. `--mnemonic-file <path>` or `--xprv-file <path>`: the file holds the secret
|
|
on one line.
|
|
2. Environment variable `BIP85KEYS_MNEMONIC` or `BIP85KEYS_XPRV`.
|
|
3. A prompt on the terminal with echo turned off. The prompt accepts either a
|
|
mnemonic or an `xprv`; a value starting with `xprv` is treated as an `xprv`.
|
|
|
|
If none of these is available and standard input is not a terminal, the tool
|
|
refuses and exits with status 1.
|
|
|
|
Every command takes `--index` / `-n` and the secret flags above, 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
|
|
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
|
|
```
|