sfinx

sphincs+ inspired signing utility
git clone git://git.finwo.net/app/sfinx
Log | Files | Refs | README | LICENSE

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`.