*
* 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 {
* | 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 {
/*----- The AEAD transform ------------------------------------------------*
*
- * This transform uses a general authenticated encryption scheme (the
- * additional data isn't necessary). Good options include
- * `chacha20-poly1305' or `rijndael-ocb3'.
+ * This transform uses a general authenticated encryption scheme. Processing
+ * additional authenticated data isn't needed for encrypting messages, but it
+ * is required for challenge generation. Good options include `chacha20-
+ * poly1305' or `rijndael-ocb3'; alas, `salsa20-naclbox' isn't acceptable.
*
* To be acceptable, the scheme must accept at least a 40-bit nonce. (All of
- * Catacomb's current AEAD schemes are suitable.) The low 32 bits are the
- * sequence number. The type is written to the next 8--32 bytes: if the
- * nonce size is 64 bits or more (preferred, for compatibility reasons) then
- * the type is written as 32 bits, and the remaining space is padded with
- * zero bytes; otherwise, the type is right-aligned in the remaining space.
- * Both fields are big-endian.
+ * Catacomb's current AEAD schemes are suitable in this respect.) The low 32
+ * bits are the sequence number. The type is written to the next 8--32
+ * bytes: if the nonce size is 64 bits or more (preferred, for compatibility
+ * reasons) then the type is written as 32 bits, and the remaining space is
+ * padded with zero bytes; otherwise, the type is right-aligned in the
+ * remaining space. Both fields are big-endian.
*
* +--------+--+
* | seq |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
* 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 {