sfinx

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

commit b96fec1186b0f90fd3ee81ce7588175eee29da4f
parent 150a94acb0b682ee8cce68734f0b84f286b8907e
Author: finwo <finwo@pm.me>
Date:   Sun, 11 Oct 2026 16:43:55 +0200

Rewrite README

Diffstat:
MREADME.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)