tally

commit 8456f3446f1b13394de904dc22b6efddf56e1a5a
parent c5a86b704d0ff77fd00cc7db5b80005c7f10b5f5
author Owen Rusk <owen@papermothgames.com>
date   2024-07-09 21:30:26 -0500

readme

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..24be5fd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+# tally
+
+Split a secret into n shares. Any k of them rebuild it. Fewer than k tell you nothing.
+
+shamir's secret sharing over gf(256), one byte at a time. standard library only, randomness from `secrets`.
+
+## install
+
+python 3.12 or newer. from a checkout:
+
+    pip install .
+
+or run it in place with `python -m tally`.
+
+## split
+
+    tally split -k 3 -n 5 secret.txt
+    tally split -k 2 -n 3 --secret 'something'
+
+reads the secret from the file, or from stdin if there's no file, and prints n shares, one per line. 2 <= k <= n <= 255.
+
+## join
+
+    tally join SHARE SHARE SHARE
+    tally join < shares.txt
+
+takes the shares as arguments, or one per line on stdin, and prints the secret. it refuses fewer than k, and shares from different splits.
+
+## share format
+
+    t1-xxxx-xxxx-xxxx-...
+
+`t1` is the format version. the rest is crockford's base32 (digits and lowercase letters, no i, l, o or u) in groups of five, carrying:
+
+    id     4 bytes, random, the same on every share of one split
+    k      1 byte, how many shares it takes
+    x      1 byte, this share's number, 1 to n
+    data   as long as the secret
+    check  4 bytes, crc32 of "t1" and everything above
+
+case, spaces and dashes don't matter when reading a share back, and o reads as 0, i and l as 1. a typo fails the check instead of rebuilding the wrong secret.
+
+a share gives away k and the secret's length. nothing else.