README.md (4280B)
1 sfinx 2 ===== 3 4 > Stateless hash-based signatures 5 6 A SPHINCS+-inspired signature scheme. Its only assumption is SHA3, so there is 7 no curve or factoring problem for a quantum computer to solve. 8 9 | at the defaults | | 10 | --------------- | ------------ | 11 | Secret | a seed | 12 | Public key | 32 bytes | 13 | Signature | 43,042 bytes | 14 15 Dependencies and exports are managed with [dep](https://git.finwo.net/app/dep). 16 17 Features 18 -------- 19 20 - The seed is any byte string up to 64 MiB, random bytes recommended 21 - Hash size and tree depth are chosen per call 22 - Hashing comes from [keccak-fast](https://git.finwo.net/lib/keccak-fast.c), 23 dispatched per CPU and batched 24 - C99 with POSIX calls, needing only libc and the hash core 25 26 Summary 27 ------- 28 29 ``` 30 usage: sfinx <command> [options] 31 32 commands: 33 version Show the version 34 verify Verify a message signature 35 sign Sign a message 36 seed Generate a random seed 37 printkey Print or convert a key file 38 help Show this help 39 generate Generate a seed and its public key 40 ``` 41 42 Run `sfinx help` or `sfinx <command> --help` for the options of a single 43 command. The full reference, including the key and signature file formats, is 44 in [docs/cli.md](docs/cli.md). 45 46 Building 47 -------- 48 49 ```sh 50 make 51 ``` 52 53 The binary lands in a target-specific directory, so on linux-x86_64 it ends up 54 at `build/linux-x86_64/sfinx`. 55 56 Usage 57 ----- 58 59 ### Signing and verifying 60 61 ```sh 62 sfinx generate -o demo.key 63 sfinx sign -k demo.key -m "hello sfinx" -o demo.sig 64 sfinx verify -k demo.key -S demo.sig -m "hello sfinx" 65 ``` 66 67 `generate` writes one file holding the seed and its public key. `sign` draws a 68 random 32-byte path, so the same message signs differently every time, and 69 `verify` prints `OK` or `FAIL`. At these defaults a signature is 43,042 bytes. 70 71 The path is the randomizer and must not repeat across messages. Drawn at random 72 it collides after roughly `2^128` signatures. 73 74 ### Single-key mode 75 76 ```sh 77 sfinx generate --single -o single.key 78 sfinx sign -k single.key --single -m "one shot" -o single.sig 79 ``` 80 81 `--single` collapses the tree to a single Winternitz key signing `H(message)`. 82 Signatures drop to 1,090 bytes, but the mode really is one-time: signing two 83 different messages under one seed destroys unforgeability, so use a fresh seed 84 per message. It has its own public key, and `verify` reads the mode from the 85 signature rather than a flag. 86 87 Embedding 88 --------- 89 90 ```sh 91 dep add finwo/sfinx https://git.finwo.net/app/sfinx/archives/heads/main.tar.gz 92 dep install 93 ``` 94 95 After that, simply add `include lib/.dep/config.mk` in your makefile and include 96 the header file by adding `#include <finwo/sfinx.h>`. Installing pulls in the 97 hash core as well. 98 99 The export covers `src/sfinx.c`, `src/keypair.c` and `src/fmt/*.c`. No CLI, 100 argparse or util code is reachable from the library, and `test/test_embed.sh` 101 builds exactly that set. 102 103 pthread is optional. The bundled CLI links it and spreads the subtree build over 104 a worker pool, while the library export leaves it to the consumer. The output is 105 identical either way. 106 107 Benchmark 108 --------- 109 110 ```sh 111 make bench 112 make bench BENCH_ARGS='-L 512 -p 8 -n 5' 113 make --directory test bench-chain 114 ``` 115 116 This builds `test/bench.c` both threaded and sequential, then times key 117 derivation, signing and verification for both the tree and the single key. `-L` 118 sets the hash size (default 256), `-p` the path length in bytes (default 32) and 119 `-n` the repetitions, of which the best is reported (default 3). `bench-chain` 120 times the WOTS chains alone, per backend. 121 122 Measured numbers across a few machines are in 123 [docs/bench.md](docs/bench.md). 124 125 Testing 126 ------- 127 128 If you want to run the project's tests, simply run `make test` to build and run 129 the test binaries along with the shell suites. 130 131 Docs 132 ---- 133 134 - [docs/idea.md](docs/idea.md): the rough idea, the glossary, and how it fits 135 - [docs/scheme.md](docs/scheme.md): the precise scheme, formulas and pseudocode 136 - [docs/cli.md](docs/cli.md): the command reference and the file formats 137 - [docs/api.md](docs/api.md): the C API, generated from `src/sfinx.h` 138 - [docs/bench.md](docs/bench.md): measured throughput per machine and backend 139 140 License 141 ------- 142 143 sfinx source code is available under the [FGPL License](LICENSE.md)