commit b96fec1186b0f90fd3ee81ce7588175eee29da4f
parent 150a94acb0b682ee8cce68734f0b84f286b8907e
Author: finwo <finwo@pm.me>
Date: Sun, 11 Oct 2026 16:43:55 +0200
Rewrite README
Diffstat:
| M | README.md | | | 174 | ++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------- |
1 file changed, 111 insertions(+), 63 deletions(-)
diff --git a/README.md b/README.md
@@ -1,91 +1,139 @@
-# sfinx
+sfinx
+=====
-<small>a small, stateless, hash-based signing library and CLI in C</small>
+> Stateless hash-based signatures
-sfinx signs data with a SPHINCS+-inspired scheme built from hash chains and a
-tree you never build. The secret is one seed. The public key is a single hash.
-Nothing is stored between signatures, and one keypair verifies any tree depth.
+Signing uses a SPHINCS+-inspired scheme built on hash chains over a merkle tree
+that is never stored. Every key is derived from the seed and the path that
+reaches it, so there is no counter and no state file to keep in sync. The secret
+is a seed, and the public key is a single hash.
-- No state, no counters, no state file.
-- The seed is any byte string, up to 64 MiB. Random bytes are recommended, a passphrase is allowed.
-- `L` and the tree depth are runtime values, so the same seed works with any hash size.
-- Hashing is SHA3/SHAKE from `finwo/keccak-fast`, runtime-dispatched and batched.
-- The library is C99 with POSIX calls and depends only on libc plus the hash core.
+The hash size and the path length are arguments rather than build options, and
+the top of the tree is fixed, so one keypair covers every path length at a given
+hash size.
-## Quick start
+This project makes use of [dep](https://git.finwo.net/app/dep) to manage its
+dependencies and exports.
- make
- BIN=build/$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/sfinx
+Features
+--------
+
+- The seed is any byte string up to 64 MiB, random bytes recommended
+- Hash size and path length are chosen per call
+- Hashing comes from [keccak-fast](https://git.finwo.net/lib/keccak-fast.c),
+ dispatched per CPU and batched
+- C99 with POSIX calls, needing only libc and the hash core
- $BIN generate -o demo.key
- $BIN sign -k demo.key -p 32 -m "hello sfinx" -o demo.sig
- $BIN verify -k demo.key -S demo.sig -m "hello sfinx"
+Summary
+-------
-`generate` writes one file with the seed and its public key. `sign` picks a
-random path of 32 bytes, so the same message signs differently every time.
-`verify` prints `OK`. Run `$BIN help` or `$BIN <command> --help` for every
-option.
+```
+usage: sfinx <command> [options]
-## How it works
+commands:
+ version Show the version
+ verify Verify a message signature
+ sign Sign a message
+ seed Generate a random seed
+ printkey Print or convert a key file
+ help Show this help
+ generate Generate a seed and its public key
+```
-Think of sfinx as a tree you never build. The public key is a hash, and below it
-sit subtrees whose leaves are one-time signature keys. Nothing is stored: every
-key is derived from the seed plus the path that reaches it.
+Run `sfinx help` or `sfinx <command> --help` for the options of a single
+command. The full reference, including the key and signature file formats, is
+in [docs/cli.md](docs/cli.md).
-- The signer picks a random path. It is the randomizer, so signing the same message twice lands on different one-time keys.
-- The bottom key signs `H(path | message)`. Each key above it signs the root of the subtree below, and the top subtree root is the public key.
-- Each one-time key is a Winternitz chain set with a checksum, so no chain can be run backward.
-- Each subtree parent is hashed together with its position, so a node cannot be replayed at another depth or in another subtree.
+Building
+--------
-A signature is a proof that you can produce the path to a given root, with no
-secret kept between signatures. The idea is in `docs/idea.md`, and the formulas
-are in `docs/scheme.md`.
+```sh
+make
+```
-## Single-key mode
+The binary lands in a target-specific directory, so on linux-x86_64 it ends up
+at `build/linux-x86_64/sfinx`.
-`--single` collapses the tree to one one-time key (`N = 0`). It is small and
-fast, but one-time: signing two different messages with the same seed destroys
-unforgeability, so use a fresh seed per message. `verify` reads the mode from
-the signature and needs no flag.
+Usage
+-----
-## Embedding
+### Signing and verifying
-sfinx is a [`dep`](https://git.finwo.net/app/dep/file/README.md.html) package.
-`dep` is a dependency manager for embedded C libraries: list a dependency in
-`.dep`, run `dep install`, and it unpacks the sources into `lib/` and merges
-each package's `export.mk` into `lib/.dep/config.mk`.
+```sh
+sfinx generate -o demo.key
+sfinx sign -k demo.key -p 32 -m "hello sfinx" -o demo.sig
+sfinx verify -k demo.key -S demo.sig -m "hello sfinx"
+```
-Add sfinx to `.dep`:
+`generate` writes one file holding the seed and its public key. `sign` draws a
+random 32-byte path, so the same message signs differently every time, and
+`verify` prints `OK` or `FAIL`. At these defaults a signature is 43,042 bytes.
- finwo/sfinx https://git.finwo.net/app/sfinx/archives/heads/main.tar.gz
+The path is the randomizer and must not repeat across messages. Drawn at random
+it collides after roughly `2^128` signatures, which is what makes a one-time
+construction usable many times.
-Then install:
+### Single-key mode
- $ dep install
+```sh
+sfinx generate --single -o single.key
+sfinx sign -k single.key --single -m "one shot" -o single.sig
+```
-Install pulls the `finwo/keccak-fast` hash core in as well, and puts the header
-at `<finwo/sfinx.h>`. Include it and build against the exported sources.
+`--single` collapses the tree to a single Winternitz key signing `H(message)`.
+Signatures drop to 1,090 bytes, but the mode really is one-time: signing two
+different messages under one seed destroys unforgeability, so use a fresh seed
+per message. It has its own public key, and `verify` reads the mode from the
+signature rather than a flag.
-The library exports `src/sfinx.c`, `src/keypair.c`, and `src/fmt/*.c` through
-`export.mk`. No CLI, argparse, or util code is reachable from the library;
-`test/test_embed.sh` builds exactly that set.
+Embedding
+---------
-pthread is optional. The bundled CLI links it and runs the subtree build on a
-worker pool. The library export does not add `-pthread`, so a consumer opts in.
+```sh
+dep add finwo/sfinx https://git.finwo.net/app/sfinx/archives/heads/main.tar.gz
+dep install
+```
-## Benchmark
+After that, simply add `include lib/.dep/config.mk` in your makefile and include
+the header file by adding `#include <finwo/sfinx.h>`. Installing pulls in the
+hash core as well.
-`make bench` builds `test/bench.c` twice, threaded and sequential, and times
-tree key derivation, tree signing, verification, and single-key signing.
+The export covers `src/sfinx.c`, `src/keypair.c` and `src/fmt/*.c`. No CLI,
+argparse or util code is reachable from the library, and `test/test_embed.sh`
+builds exactly that set.
- $ make bench
- $ make bench BENCH_ARGS='-L 512 -p 8 -n 5'
+pthread is optional. The bundled CLI links it and spreads the subtree build over
+a worker pool, while the library export leaves it to the consumer. The output is
+identical either way.
-`-L` sets the hash size (default 256), `-p` the path length in bytes (default
-32), and `-n` the repetitions, best reported (default 3).
+Benchmark
+---------
-## Docs
+```sh
+make bench
+make bench BENCH_ARGS='-L 512 -p 8 -n 5'
+```
-- `docs/idea.md`: the rough idea, the glossary, and how the pieces fit.
-- `docs/scheme.md`: the precise scheme, the formulas, and pseudocode.
-- `docs/cli.md`: the command reference and the key and signature file formats.
+This builds `test/bench.c` both threaded and sequential, then times key
+derivation, signing and verification for both the tree and the single key. `-L`
+sets the hash size (default 256), `-p` the path length in bytes (default 32) and
+`-n` the repetitions, of which the best is reported (default 3).
+
+Testing
+-------
+
+If you want to run the project's tests, simply run `make test` to build and run
+the test binaries along with the shell suites.
+
+Docs
+----
+
+- [docs/idea.md](docs/idea.md): the rough idea, the glossary, and how it fits
+- [docs/scheme.md](docs/scheme.md): the precise scheme, formulas and pseudocode
+- [docs/cli.md](docs/cli.md): the command reference and the file formats
+- [docs/api.md](docs/api.md): the C API, generated from `src/sfinx.h`
+
+License
+-------
+
+sfinx source code is available under the [FGPL License](LICENSE.md)