Réécriture des commentaires schématiques sur les tweaks

3 files changed, 42 insertions, 29 deletions

diff --git a/src/ref/lilliput-ae-utils.h b/src/ref/lilliput-ae-utils.h
index a66b75c..19b4623 100644
--- a/src/ref/lilliput-ae-utils.h
+++ b/src/ref/lilliput-ae-utils.h
@@ -102,12 +102,15 @@ static inline void fill_index_tweak(
     uint8_t tweak[TWEAK_BYTES]
 )
 {
-    /* With an s-bit block index, the t-bit tweak is filled as follows:
+    /* The t-bit tweak is filled as follows:
      *
-     * [     1,   4]: 4-bit prefix
-     * [     5,   t]: block index
-     *  [    5, t-s]: 0-padding
-     *  [t-s+1,   t]: actual block index, from MSB to LSB
+     *   1    4    5         t
+     * [ prefix || block index ]
+     *
+     * The s-bit block index is encoded as follows:
+     *
+     *   5        t-s    t-s+1                t
+     * [ zero padding || block index, MSB first ]
      */
 
     tweak[0] = prefix<<4;
diff --git a/src/ref/lilliput-i.c b/src/ref/lilliput-i.c
index fb06237..3358b10 100644
--- a/src/ref/lilliput-i.c
+++ b/src/ref/lilliput-i.c
@@ -44,13 +44,15 @@ static uint8_t _lower_nibble(uint8_t i)
 
 static void _init_msg_tweak(const uint8_t N[NONCE_BYTES], uint8_t tweak[TWEAK_BYTES])
 {
-    /* With an s-bit block index, the t-bit tweak is filled as follows:
+    /* The t-bit tweak is filled as follows:
      *
-     * [     1,     4]: 4-bit prefix
-     * [     5, |N|+4]: nonce
-     * [ |N|+5,     t]: block index
-     *  [|N|+5,   t-s]: 0-padding
-     *  [t-s+1,     t]: actual block index, from MSB to LSB
+     *   1    4    5     |N|+4    |N|+5     t
+     * [ prefix ||  nonce      || block index ]
+     *
+     * The s-bit block index is encoded as follows:
+     *
+     *   |N|+5    t-s    t-s+1                t
+     * [ zero padding || block index, MSB first ]
      *
      * This function sets bits 5 to t-s once and for all.
      */
@@ -77,13 +79,15 @@ static void _fill_msg_tweak(
     uint8_t tweak[TWEAK_BYTES]
 )
 {
-    /* With an s-bit block index, the t-bit tweak is filled as follows:
+    /* The t-bit tweak is filled as follows:
+     *
+     *   1    4    5     |N|+4    |N|+5     t
+     * [ prefix ||  nonce      || block index ]
+     *
+     * The s-bit block index is encoded as follows:
      *
-     * [     1,     4]: 4-bit prefix
-     * [     5, |N|+4]: nonce
-     * [ |N|+5,     t]: block index
-     *  [|N|+5,   t-s]: 0-padding
-     *  [t-s+1,     t]: actual block index, from MSB to LSB
+     *   |N|+5    t-s    t-s+1                t
+     * [ zero padding || block index, MSB first ]
      *
      * This function assumes bits 5 to t-s have already been set, and
      * only sets bits 1 to 4 and t-s+1 to t.
diff --git a/src/ref/lilliput-ii.c b/src/ref/lilliput-ii.c
index 9ed17a2..bb43d08 100644
--- a/src/ref/lilliput-ii.c
+++ b/src/ref/lilliput-ii.c
@@ -28,12 +28,15 @@ This file implements Lilliput-AE's nonce-misuse-resistant mode based on SCT-2.
 
 static void _init_msg_tweak(const uint8_t tag[TAG_BYTES], uint8_t tweak[TWEAK_BYTES])
 {
-    /* With an s-bit block index, the t-bit tweak is filled as follows:
+    /* The t-bit tweak is filled as follows:
+     *
+     *   1    2                      t
+     * [ 1 || tag[2,t] XOR block index  ]
+     *
+     * The s-bit block index is XORed to the tag as follows:
      *
-     * 1: 1
-     * [     2,   t]: tag[    2,   t] XOR block index
-     *  [    2, t-s]: tag[    2, t-s]
-     *  [t-s+1,   t]: tag[t-s+1,   t] XOR block index
+     *   2       t-s    t-s+1                                  t
+     * [ tag[2, t-s] || tag[t-s+1, t] XOR block index, MSB first ]
      *
      * This function sets bits 1 to t-s once and for all.
      */
@@ -44,12 +47,15 @@ static void _init_msg_tweak(const uint8_t tag[TAG_BYTES], uint8_t tweak[TWEAK_BY
 
 static void _fill_msg_tweak(const uint8_t tag[TAG_BYTES], size_t block_index, uint8_t tweak[TWEAK_BYTES])
 {
-    /* With an s-bit block index, the t-bit tweak is filled as follows:
+    /* The t-bit tweak is filled as follows:
+     *
+     *   1    2                      t
+     * [ 1 || tag[2,t] XOR block index  ]
+     *
+     * The s-bit block index is XORed to the tag as follows:
      *
-     * 1: 1
-     * [     2,   t]: tag + block index
-     *  [    2, t-s]: tag[    2, t-s]
-     *  [t-s+1,   t]: tag[t-s+1,   t] XOR block index
+     *   2       t-s    t-s+1                                  t
+     * [ tag[2, t-s] || tag[t-s+1, t] XOR block index, MSB first ]
      *
      * This function assumes bits 1 to t-s have already been set, and
      * only sets bits t-s+1 to t.
@@ -67,8 +73,8 @@ static void _fill_tag_tweak(const uint8_t N[NONCE_BYTES], uint8_t tweak[TWEAK_BY
 {
     /* The t-bit tweak is filled as follows:
      *
-     * [      1, 8]: 0001||0^4
-     * [t-|N|+1, t]: N
+     *   1  4    5   8    t-|N|+1     t
+     * [ 0001 ||  0^4  ||        nonce  ]
      */
 
     tweak[0] = 0x10;