commit 09ac7fe49c114a50906a4dd41e014d86d0e615bb
parent fab691a3e1de754fbefdc22a4ce0794ed30a51c3
Author: finwo <finwo@pm.me>
Date: Sat, 10 Oct 2026 00:49:32 +0200
Single mode
Diffstat:
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