server/bulkcrypto.c: Document the procedures for producing challenges.

diff --git a/server/bulkcrypto.c b/server/bulkcrypto.c
index 92e67c0..f4d37c1 100644 (file)
--- a/server/bulkcrypto.c
+++ b/server/bulkcrypto.c
@@ -303,6 +303,14 @@ static void gencomp_freechal(bulkchal *bc)
  *
  * Decryption: checks the overall size, verifies the tag, then decrypts the
  * ciphertext and extracts the sequence number.
+ *
+ * Challenge tags are calculated by applying the MAC to the sequence number
+ * and message, concatenated as follows.
+ *
+ *             +--------+---...---+
+ *             |  seq   |    m    |
+ *             +--------+---...---+
+ *                 32       msz
  */
 
 typedef struct v0_algs {
@@ -538,6 +546,14 @@ static int v0_decrypt(bulkctx *bbc, unsigned ty,
  *             |   tag   | seq  |   ciphertext  |
  *             +---...---+------+------...------+
  *                tagsz     32         sz
+ *
+ * Challenge tags are calculated by applying the MAC to the sequence number
+ * and message, concatenated as follows.
+ *
+ *             +--------+---...---+
+ *             |  seq   |    m    |
+ *             +--------+---...---+
+ *                 32       msz
  */
 
 typedef struct iiv_algs {
@@ -856,6 +872,14 @@ static int iiv_decrypt(bulkctx *bbc, unsigned ty,
  *             +---...---+--------+------...------+
  *                tagsz      32          sz
  *
+ * Challenge tags are calculated by encrypting the message, using the
+ * sequence number as a nonce (as a big-endian integer, padding with leading
+ * zeroes as needed to fill the space), and discarding the ciphertext.
+ *
+ *             +---...---+--------+ +-----...------+
+ *             |    0    |  seq   | |   message    |
+ *             +---...---+--------+ +-----...------+
+ *              nsz - 32     32           msz
  */
 
 #define AEAD_NONCEMAX 64
@@ -1208,6 +1232,21 @@ static int aead_decrypt(bulkctx *bbc, unsigned ty,
  * Note that there is no need to authenticate the type separately, since it
  * was used to select the cipher nonce, and hence the Poly1305 key.  The
  * Poly1305 tag length is fixed.
+ *
+ * Challenge formation is rather tricky.  We can't use Poly1305 directly
+ * because we need a random mask.  So we proceed as follows.  The challenge
+ * generator has a Salsa20 or ChaCha key.  The sequence number is used as the
+ * Salsa20 message number/nonce, padded at the start with zeroes to form,
+ * effectively, a 64-bit big-endian integer.
+ *
+ *             +--------+--------+
+ *             |   0    |  seq   |
+ *             +--------+--------+
+ *                 32       32
+ *
+ * 256 bits (32 bytes) of keystream are generated and used as a Poly1305 hash
+ * key r and mask s.  These are then used to hash the message, and the
+ * resulting tag is the challenge.
  */
 
 typedef struct naclbox_algs {