Start talking about tokens

doc/tokens.txt

@@ -0,0 +1,42 @@
+Tokens
+======
+
+Tokens are good for a single point in a single category.  They are
+formed by prepending the category and a colon to the bubblebabble digest
+of 3 random octets.  A token for the "merfing" category might look like
+this:
+
+    merfing:xunap-motex
+
+
+Entropy
+-------
+
+3 octets provides 24 bits of entropy.  This gives 16777216 possible
+tokens in each category.  The longest contest yet run lasted 24 hours,
+which would give 2^24/24/60 = 11650 tokens per category per minute.  I
+think this is a large enough pool to discourage brute-force attacks.
+Assuming /dev/urandom is as good as is claimed, brute-force would be the
+only way to attack it.
+
+
+Token server
+------------
+
+Sometimes it's a good idea to have certain puzzles run on a different
+machine than the server.  For instance, something that loads down the
+CPU, or something that carries a high risk of local exploit.  The token
+server listens on TCP port 1, issuing tokens encrypted with ARC4
+(symmetric encryption).  Here's how the transaction goes:
+
+   C: category
+   S: nonce (4 bytes)
+   C: nonce encrypted with symmetric key
+   S: token encrypted with symmetric key
+
+
+Token client
+------------
+
+The token client (in package "tokencli") runs as a daemon, requesting a
+new token every minute for each puzzle.