sfinx

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

commit 09ac7fe49c114a50906a4dd41e014d86d0e615bb
parent fab691a3e1de754fbefdc22a4ce0794ed30a51c3
Author: finwo <finwo@pm.me>
Date:   Sat, 10 Oct 2026 00:49:32 +0200

Single mode

Diffstat:
MREADME.md | 7++++---
Msrc/cli/common.c | 4++--
Msrc/cli/common.h | 6+++---
Msrc/cli/generate.c | 8+++++---
Msrc/cli/printkey.c | 13+++++++++----
Msrc/cli/sign.c | 27+++++++++++++++++++++------
Msrc/cli/verify.c | 33+++++++++++++++++++++------------
Mtest/test_printkey.sh | 4++++
Atest/test_single_mode.sh | 62++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
9 files changed, 131 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md @@ -193,11 +193,12 @@ a universal keyspace. `sfinx` is one binary that dispatches on its first argument. - `sfinx seed [length] [-o file] [--force]`: write `length` random seed bytes, default 32, to stdout or a file. -- `sfinx generate [length] [-L hash] [--out-fmt fmt] [-o file] [-F]`: generate a seed and derive its public key. `--out-fmt hdr` writes one combined file, `raw` and `hex` write a seed file and a `.pub` file beside it. Stdout carries the seed alone. -- `sfinx printkey -k file [-L hash] [--in-fmt fmt] [--out-fmt fmt] [-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. -- `sfinx sign -k keyfile [-L hash] [-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. +- `sfinx generate [length] [-L hash] [--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 seed file and a `.pub` file beside it. Stdout carries the seed alone. +- `sfinx printkey -k file [-L hash] [--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. +- `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. - `sfinx verify -k keyfile [-L hash] [-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. - `sfinx help` and `sfinx version`. +- `--single` selects single-key mode (`N = 0`), one WOTS key signing `H(message)` for a seed. It is one-time: signing two different messages with the same seed destroys unforgeability, so use a fresh seed per message. `verify` takes no flag and reads the mode from the signature. A key file carries a seed, a public key, or both. `hdr` is the text form (`hash:`, `seed:`, `public-key:`, `signature:`), and `raw`, `hex`, `rawpub`, and `hexpub` are the bare forms. The encode and decode code lives in the library, so any program using sfinx reads and writes the same files. diff --git a/src/cli/common.c b/src/cli/common.c @@ -51,7 +51,7 @@ sfinx_status cli_seed_random(size_t len, uint8_t **out) { return SFINX_OK; } -sfinx_status cli_key_derive(sfinx_key *key, size_t path_len) { +sfinx_status cli_key_derive(sfinx_key *key, int single) { size_t len; uint8_t *pub; sfinx_status status; @@ -66,7 +66,7 @@ sfinx_status cli_key_derive(sfinx_key *key, size_t path_len) { free(key->pub); key->pub = NULL; key->pub_len = 0; - if (path_len != 0) { + if (!single) { return sfinx_key_derive(key); } pub = malloc(len); diff --git a/src/cli/common.h b/src/cli/common.h @@ -27,10 +27,10 @@ sfinx_status cli_seed_random(size_t len, uint8_t **out); // Key derive {{{ // // Derive the public half of a key for one key mode -// path_len 0 selects the single-key mode, any other value the stacked subtrees -// a seed in the key wins over a stored public key, so --hash and --path-len cannot disagree with the file +// single selects the N = 0 key, otherwise the stacked subtrees +// a seed in the key wins over a stored public key, so --hash cannot disagree with the file -sfinx_status cli_key_derive(sfinx_key *key, size_t path_len); +sfinx_status cli_key_derive(sfinx_key *key, int single); // }}} #endif // __SFINX_CLI_COMMON_H__ diff --git a/src/cli/generate.c b/src/cli/generate.c @@ -65,6 +65,7 @@ static int cmd_generate(int argc, const char **argv) { const char *format = "hdr"; const char *pub_format; int hash = 0; + int single = 0; int force = 0; size_t seed_len = CLI_SEED_LEN_DEFAULT; uint8_t *seed = NULL; @@ -79,7 +80,7 @@ static int cmd_generate(int argc, const char **argv) { int rc = 1; static const char *const usages[] = { - "sfinx generate [length] [-L hash] [--out-fmt fmt] [-o file] [-F]", + "sfinx generate [length] [-L hash] [--out-fmt fmt] [--single] [-o file] [-F]", NULL, }; struct argparse_option options[] = { @@ -88,6 +89,7 @@ static int cmd_generate(int argc, const char **argv) { 0), OPT_INTEGER('L', "hash", &hash, "hash size 224/256/384/512", NULL, 0, 0), OPT_STRING('o', "out", &out_file, "key file, - for stdout", NULL, 0, 0), + OPT_BOOLEAN(0, "single", &single, "single-key mode, derive the N = 0 public key", NULL, 0, 0), OPT_BOOLEAN('F', "force", &force, "overwrite existing files", NULL, 0, 0), OPT_END(), }; @@ -130,7 +132,7 @@ static int cmd_generate(int argc, const char **argv) { fprintf(stderr, "sfinx: generate: invalid hash size: %d\n", hash); goto done; } - status = sfinx_key_derive(&key); + status = cli_key_derive(&key, single); if (status != SFINX_OK) { fprintf(stderr, "sfinx: generate: cannot derive the public key: %s\n", sfinx_strerror(status)); goto done; @@ -209,7 +211,7 @@ static struct cli_command generate_command = { .names = (const char *const[]){"generate", NULL}, .display = "generate", .description = "Generate a seed and its public key", - .help = "sfinx generate [length] [-L hash] [--out-fmt fmt] [-o file] [-F]", + .help = "sfinx generate [length] [-L hash] [--out-fmt fmt] [--single] [-o file] [-F]", .fn = cmd_generate, }; diff --git a/src/cli/printkey.c b/src/cli/printkey.c @@ -2,6 +2,7 @@ #include <stdio.h> #include <stdlib.h> +#include "common.h" #include "registry.h" #include "sfinx.h" #include "util/file.h" @@ -13,6 +14,7 @@ static int cmd_printkey(int argc, const char **argv) { const char *in_format = NULL; int hash = 0; int public_only = 0; + int single = 0; int force = 0; uint8_t *data = NULL; uint8_t *out = NULL; @@ -23,7 +25,7 @@ static int cmd_printkey(int argc, const char **argv) { int rc = 0; static const char *const usages[] = { - "sfinx printkey -k file [-L hash] [--in-fmt fmt] [--out-fmt fmt] [-o file] [--public-only]", + "sfinx printkey -k file [-L hash] [--in-fmt fmt] [--out-fmt fmt] [--single] [-o file] [--public-only] [--force]", NULL, }; struct argparse_option options[] = { @@ -34,6 +36,7 @@ static int cmd_printkey(int argc, const char **argv) { OPT_INTEGER('L', "hash", &hash, "hash size (224/256/384/512)", NULL, 0, 0), OPT_STRING('o', "out", &out_file, "write to a file instead of stdout", NULL, 0, 0), OPT_BOOLEAN(0, "public-only", &public_only, "output only the public key", NULL, 0, 0), + OPT_BOOLEAN(0, "single", &single, "single-key mode, derive the N = 0 public key", NULL, 0, 0), OPT_BOOLEAN(0, "force", &force, "overwrite an existing file", NULL, 0, 0), OPT_END(), }; @@ -69,7 +72,7 @@ static int cmd_printkey(int argc, const char **argv) { sfinx_key_free(&key); return 1; } - status = sfinx_key_derive(&key); + status = cli_key_derive(&key, single); if (status != SFINX_OK) { fprintf(stderr, "sfinx: printkey: cannot derive public key: %s\n", sfinx_strerror(status)); sfinx_key_free(&key); @@ -119,8 +122,10 @@ static struct cli_command printkey_command = { .names = (const char *const[]){"printkey", NULL}, .display = "printkey", .description = "Print or convert a key file", - .help = "sfinx printkey -k file [-L hash] [--in-fmt fmt] [--out-fmt fmt] [-o file] [--public-only]", - .fn = cmd_printkey, + .help = + "sfinx printkey -k file [-L hash] [--in-fmt fmt] [--out-fmt fmt] [--single] [-o file] [--public-only] " + "[--force]", + .fn = cmd_printkey, }; __attribute__((constructor)) static void printkey_register(void) { diff --git a/src/cli/sign.c b/src/cli/sign.c @@ -17,8 +17,9 @@ static int cmd_sign(int argc, const char **argv) { const char *path_hex = NULL; const char *message = NULL; const char *msg_file = NULL; + int single = 0; int hash = 0; - int path_len = SFINX_PATH_LEN_DEFAULT; + int path_len = -1; int force = 0; uint8_t *key_data = NULL; uint8_t *msg_data = NULL; @@ -35,7 +36,8 @@ static int cmd_sign(int argc, const char **argv) { int rc = 1; static const char *const usages[] = { - "sfinx sign -k keyfile [-L hash] [-p path-len | -P path] [-m message | -M message-file] [--key-fmt fmt] " + "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]", NULL, }; @@ -46,6 +48,7 @@ static int cmd_sign(int argc, const char **argv) { OPT_INTEGER('L', "hash", &hash, "hash size 224/256/384/512", NULL, 0, 0), OPT_INTEGER('p', "path-len", &path_len, "random path length", NULL, 0, 0), OPT_STRING('P', "path", &path_hex, "explicit path as hex", NULL, 0, 0), + OPT_BOOLEAN(0, "single", &single, "single-key mode, one WOTS key over H(message)", NULL, 0, 0), OPT_STRING('m', "message", &message, "message string", NULL, 0, 0), OPT_STRING('M', "message-file", &msg_file, "message file, - for stdin", NULL, 0, 0), OPT_STRING(0, "sig-fmt", &format, "signature format, hex on stdout and raw to a file by default", NULL, 0, 0), @@ -72,6 +75,13 @@ static int cmd_sign(int argc, const char **argv) { fprintf(stderr, "sfinx: sign: --message and --message-file are exclusive\n"); return 1; } + if (single && (path_hex || path_len != -1)) { + fprintf(stderr, "sfinx: sign: --single cannot be combined with --path-len or --path\n"); + return 1; + } + if (!single && path_len == -1) { + path_len = SFINX_PATH_LEN_DEFAULT; + } if (util_file_read(key_file, &key_data, &key_len) != 0) { fprintf(stderr, "sfinx: sign: cannot read %s\n", key_file); @@ -102,14 +112,16 @@ static int cmd_sign(int argc, const char **argv) { goto done; } - if (path_hex) { + if (single) { + path_bytes = 0; + } else if (path_hex) { if (cli_hex_decode(path_hex, &path, &path_bytes) != 0 || !sfinx_path_len_valid(path_bytes)) { fprintf(stderr, "sfinx: sign: invalid path\n"); goto done; } } else { if (path_len <= 0 || !sfinx_path_len_valid((size_t)path_len)) { - fprintf(stderr, "sfinx: sign: invalid path length: %d\n", path_len); + fprintf(stderr, "sfinx: sign: invalid path length: %d (use --single for single-key mode)\n", path_len); goto done; } path_bytes = (size_t)path_len; @@ -130,7 +142,9 @@ static int cmd_sign(int argc, const char **argv) { fprintf(stderr, "sfinx: sign: out of memory\n"); goto done; } - status = sfinx_tree_sign(key.hash, key.seed, key.seed_len, path, path_bytes, msg_data, msg_len, sig, sig_len, NULL); + status = single ? sfinx_single_sign(key.hash, key.seed, key.seed_len, msg_data, msg_len, sig, sig_len, NULL) + : sfinx_tree_sign(key.hash, key.seed, key.seed_len, path, path_bytes, msg_data, msg_len, sig, sig_len, + NULL); if (status != SFINX_OK) { fprintf(stderr, "sfinx: sign: %s\n", sfinx_strerror(status)); goto done; @@ -175,7 +189,8 @@ static struct cli_command sign_command = { .display = "sign", .description = "Sign a message", .help = - "sfinx sign -k keyfile [-L hash] [-p path-len | -P path] [-m message | -M message-file] [--key-fmt fmt] " + "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]", .fn = cmd_sign, }; diff --git a/src/cli/verify.c b/src/cli/verify.c @@ -26,12 +26,14 @@ static int cmd_verify(int argc, const char **argv) { size_t msg_len = 0; size_t sig_data_len = 0; size_t raw_len = 0; + sfinx_hash sig_hash; + size_t sig_path; sfinx_key key; sfinx_status status; int rc = 1; static const char *const usages[] = { - "sfinx verify -k keyfile [-L bits] [-s signature | -S signature-file] [-m message | -M message-file] " + "sfinx verify -k keyfile [-L hash] [-s signature | -S signature-file] [-m message | -M message-file] " "[--key-fmt fmt] [--sig-fmt fmt]", NULL, }; @@ -90,9 +92,8 @@ static int cmd_verify(int argc, const char **argv) { fprintf(stderr, "sfinx: verify: cannot decode %s: %s\n", key_file, sfinx_strerror(status)); goto done; } - if (sfinx_key_derive(&key) != SFINX_OK || !key.pub) { - fprintf(stderr, "sfinx: verify: key has no public key\n"); - goto done; + if (hash != 0) { + key.hash = (sfinx_hash)hash; } if (cli_read_message(message, msg_file, &msg_data, &msg_len) != 0) { @@ -122,13 +123,21 @@ static int cmd_verify(int argc, const char **argv) { } } - if (hash != 0) { - sfinx_hash sig_hash; - size_t sig_path; - if (sfinx_signature_info(raw_sig, raw_len, &sig_hash, &sig_path) != SFINX_OK || (int)sig_hash != hash) { - fprintf(stderr, "sfinx: verify: signature is not %d-bit\n", hash); - goto done; - } + if (sfinx_signature_info(raw_sig, raw_len, &sig_hash, &sig_path) != SFINX_OK) { + fprintf(stderr, "sfinx: verify: invalid signature\n"); + goto done; + } + if (hash != 0 && (int)sig_hash != hash) { + fprintf(stderr, "sfinx: verify: signature is not %d-bit\n", hash); + goto done; + } + if (key.seed && cli_key_derive(&key, sig_path == 0) != SFINX_OK) { + fprintf(stderr, "sfinx: verify: cannot derive the public key\n"); + goto done; + } + if (!key.pub) { + fprintf(stderr, "sfinx: verify: key has no public key\n"); + goto done; } if (sfinx_verify(key.pub, key.pub_len, msg_data, msg_len, raw_sig, raw_len) == SFINX_OK) { @@ -153,7 +162,7 @@ static struct cli_command verify_command = { .display = "verify", .description = "Verify a message signature", .help = - "sfinx verify -k keyfile [-L bits] [-s signature | -S signature-file] [-m message | -M message-file] " + "sfinx verify -k keyfile [-L hash] [-s signature | -S signature-file] [-m message | -M message-file] " "[--key-fmt fmt] [--sig-fmt fmt]", .fn = cmd_verify, }; diff --git a/test/test_printkey.sh b/test/test_printkey.sh @@ -29,6 +29,10 @@ tap "$([ "${n}" = 32 ] && echo 1 || echo 0)" "hdr auto-detect gives a 32-byte pu n=$(wc -c <"${TMP}/pub512.bin" | tr -d '[:space:]') tap "$([ "${n}" = 64 ] && echo 1 || echo 0)" "--hash 512 gives a 64-byte pub" "got ${n}" +"${BIN}" printkey -k "${TMP}/key.hdr" -L 512 --public-only --out-fmt rawpub >"${TMP}/pub512.stale" +cmp -s "${TMP}/pub512.stale" "${TMP}/pub512.bin" && ok=1 || ok=0 +tap "${ok}" "a stored 32-byte pub does not survive --hash 512" "differs" + "${BIN}" printkey -k "${TMP}/key.hdr" --public-only --out-fmt rawpub >"${TMP}/rawpub.bin" n=$(wc -c <"${TMP}/rawpub.bin" | tr -d '[:space:]') tap "$([ "${n}" = 32 ] && echo 1 || echo 0)" "out-fmt rawpub gives a 32-byte pub" "got ${n}" diff --git a/test/test_single_mode.sh b/test/test_single_mode.sh @@ -0,0 +1,62 @@ +#!/bin/sh +set -eu +HERE=$(cd "$(dirname "$0")" && pwd) +ROOT=$(cd "${HERE}/.." && pwd) +. "${HERE}/_tap.sh" + +BIN=$(ensure_bin "${ROOT}") +TMP=$(mktemp -d) +trap 'rm -rf "${TMP}"' EXIT + +bytes() { + wc -c <"$1" | tr -d '[:space:]' +} + +tap_begin "cli: single-key mode" + +"${BIN}" generate --single --out-fmt raw -o "${TMP}/s.key" +tap "$([ "$(bytes "${TMP}/s.key")" = 32 ] && [ "$(bytes "${TMP}/s.pub")" = 32 ] && echo 1 || echo 0)" \ + "single generate writes a seed and a public key" "key $(bytes "${TMP}/s.key") pub $(bytes "${TMP}/s.pub")" + +"${BIN}" sign --single -k "${TMP}/s.key" -m hello -o "${TMP}/sig.bin" +tap "$([ "$(bytes "${TMP}/sig.bin")" = 1090 ] && echo 1 || echo 0)" "single signature is size(0) bytes" \ + "got $(bytes "${TMP}/sig.bin")" + +"${BIN}" verify -k "${TMP}/s.pub" -m hello -S "${TMP}/sig.bin" >/dev/null && ok=1 || ok=0 +tap "${ok}" "single signature verifies with the public key" "failed" + +"${BIN}" sign --single -k "${TMP}/s.key" -m hello -o "${TMP}/a.bin" +"${BIN}" sign --single -k "${TMP}/s.key" -m hello -o "${TMP}/b.bin" +cmp -s "${TMP}/a.bin" "${TMP}/b.bin" && ok=1 || ok=0 +tap "${ok}" "single signing is deterministic" "differs" + +"${BIN}" printkey --in-fmt raw -k "${TMP}/s.key" --out-fmt rawpub --public-only >"${TMP}/tree.pub" +cmp -s "${TMP}/tree.pub" "${TMP}/s.pub" && ok=0 || ok=1 +tap "${ok}" "single and tree public keys differ for one seed" "same key" + +rc=0 +"${BIN}" verify -k "${TMP}/tree.pub" -m hello -S "${TMP}/sig.bin" >/dev/null 2>&1 || rc=$? +tap "$([ "${rc}" != 0 ] && echo 1 || echo 0)" "a tree public key rejects a single signature" "exit ${rc}" + +"${BIN}" printkey --in-fmt raw -k "${TMP}/s.key" --single --out-fmt rawpub --public-only >"${TMP}/single.pub" +cmp -s "${TMP}/single.pub" "${TMP}/s.pub" && ok=1 || ok=0 +tap "${ok}" "printkey --single matches the generated public key" "differs" + +"${BIN}" generate --single -o "${TMP}/h.hdr" +"${BIN}" sign --single -k "${TMP}/h.hdr" -m hello -o "${TMP}/h.sig" +"${BIN}" verify -k "${TMP}/h.hdr" -m hello -S "${TMP}/h.sig" >/dev/null && ok=1 || ok=0 +tap "${ok}" "verify derives the single key from a seed-bearing hdr" "failed" + +rc=0 +"${BIN}" sign --single -k "${TMP}/s.key" -m hi -P 0011 >/dev/null 2>&1 || rc=$? +tap "$([ "${rc}" != 0 ] && echo 1 || echo 0)" "--single refuses --path" "exit ${rc}" + +rc=0 +"${BIN}" sign --single -k "${TMP}/s.key" -m hi -p 8 >/dev/null 2>&1 || rc=$? +tap "$([ "${rc}" != 0 ] && echo 1 || echo 0)" "--single refuses --path-len" "exit ${rc}" + +out=$("${BIN}" sign -p 0 -k "${TMP}/s.key" -m hi 2>&1 || true) +case "${out}" in *--single*) ok=1 ;; *) ok=0 ;; esac +tap "${ok}" "-p 0 names --single in the error" "${out}" + +tap_plan