sfinx

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

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)