cli.md (3786B)
1 # sfinx command line 2 3 `sfinx` is one binary that dispatches on its first argument. Build it with 4 `make`; the binary lands at `build/$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/sfinx`. 5 6 ## Quick start 7 8 ``` 9 $ sfinx generate -o demo.key 10 $ sfinx sign -k demo.key -m "hello sfinx" -o demo.sig 11 $ sfinx verify -k demo.key -S demo.sig -m "hello sfinx" 12 OK 13 ``` 14 15 `generate` writes one file holding the seed and its public key. `sign` picks a 16 random path of 32 bytes, so the same message signs differently every time. 17 `verify` prints `OK` or `FAIL`. 18 19 ## Commands 20 21 - `sfinx seed [length] [-o file] [--force]`: write `length` random seed bytes, default 32, to stdout or a file. 22 - `sfinx generate [length] [-L hash] [-p path-len] [--out-fmt fmt] [--single] [-o file] [-F]`: generate a seed and derive its public key. `--out-fmt hdr` writes one combined file, `raw` and `hex` write a key file and a `.pub` file beside it. Stdout carries the seed alone. 23 - `sfinx printkey -k file [-L hash] [-p path-len] [--in-fmt fmt] [--out-fmt fmt] [--single] [-o file] [--public-only] [--force]`: read a key file, derive the public key from the seed, and re-encode it. `--in-fmt` defaults to auto-detect, `--out-fmt` to `hdr`. `--public-only` drops the seed. 24 - `sfinx sign -k keyfile [-L hash] [--single | -p path-len | -P path] [-m message | -M message-file] [--key-fmt fmt] [--sig-fmt fmt] [-o file] [-F]`: sign a message and write the signature. `--key-fmt` defaults to auto-detect with a `raw` seed fallback, `--sig-fmt` to `hex` on stdout and `raw` to a file. 25 - `sfinx verify -k keyfile [-L hash] [-p path-len] [-s signature | -S signature-file] [-m message | -M message-file] [--key-fmt fmt] [--sig-fmt fmt]`: verify a signature and print `OK` or `FAIL`. `--key-fmt` defaults to auto-detect with a `rawpub` fallback, `--sig-fmt` to auto-detect with a `raw` fallback. 26 - `sfinx help` and `sfinx version`. 27 28 `-h/--help` on any command prints its options. 29 30 ## Hashing and paths 31 32 - `-L hash`: hash size, one of `224`, `256`, `384`, `512`. Default `256`. 33 - `-p path-len`: the path length. `sign` draws a random path that long, `generate` and `printkey` derive the public key for it, `verify` cross-checks it against the signature. 34 - `-P path`: use an explicit path, as hex. 35 - `--single`: single-key mode (`N = 0`), one WOTS key signing `H(message)` for a seed. 36 - `-F`, `--force`: overwrite existing output files. 37 38 `--single` is mutually exclusive with `-p` and `-P`. It is small and fast, but 39 one-time: signing two different messages with the same seed destroys 40 unforgeability, so use a fresh seed per message. `verify` takes no flag and 41 reads the mode from the signature. 42 43 ## File formats 44 45 A key file carries a seed, a public key, or both. A signature file carries a 46 signature. The encode and decode code lives in the library, so any program using 47 sfinx reads and writes the same files. 48 49 Key and signature formats (`--key-fmt`, `--sig-fmt`, `--in-fmt`, `--out-fmt`): 50 51 - `hdr`: text, self-detecting. Lines are `hash:`, `seed:`, `public-key:`, `path-len:`, and `signature:`. `path-len:` is decimal and accompanies a public key, the rest are hex. 52 - `raw`: bare bytes. A key seed is bare seed bytes, a signature is bare signature bytes. 53 - `hex`: lowercase hex, one line. 54 - `rawpub`: a bare public key, `L` bytes. Explicit only. 55 - `hexpub`: a public key as lowercase hex. Explicit only. 56 57 Auto-detect (a null or omitted format) recognises `hdr` and `hex` by looking at 58 the content. `raw`, `rawpub`, and `hexpub` are never guessed; name them 59 explicitly. 60 61 `verify` reads the path length from the signature. Only `hdr` records one, and a 62 recorded length is cross-checked, naming a mismatch instead of reporting `FAIL`. 63 64 The wire layout of the signature itself, including `E4M4(N)` and the path, is in 65 `scheme.md`.