From 5fba528be526c0bedf805a01fd4f844533bff8b4 Mon Sep 17 00:00:00 2001
From: Neale Pickett <neale@woozle.org>
Date: Mon, 27 Sep 2010 09:02:54 -0600
Subject: [PATCH] Start talking about tokens

---
 doc/tokens.txt | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 doc/tokens.txt

diff --git a/doc/tokens.txt b/doc/tokens.txt
new file mode 100644
index 0000000..dad9999
--- /dev/null
+++ b/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.