Documentation and visibility

Ascon.cry

@@ -1,9 +1,8 @@
-/** Implementation of Ascon-Based Lightweight Cryptography
+/** Ascon-Based Lightweight Cryptography
  *
  * Author: Eric Mertens
  *
  * Key algorithms:
- * - Ascon_p: Core permutation function
  * - AEAD128_encrypt/decrypt: Authenticated encryption
  * - Hash256: Cryptographic hash function
  * - XOF128: Extendable output function
@@ -19,6 +18,7 @@
  */
 module Ascon where
 
+private
   // 2.1. Auxiliary Functions
 
   /** Parse function.
@@ -126,13 +126,18 @@ Const =
 
   // 3.3. Substitution Layer pS
 
+  /**
+   * The substitution layer 𝑝𝑆 updates the state S with 64 parallel
+   * applications of the 5-bit substitution box SBOX
+   */
   pS : State -> State
   pS S = transpose (map SBox (transpose S))
 
+  /** 5-bit substitution used in pS. */
   SBox : [5] -> [5]
   SBox i = SBoxTable@i
 
-/** Table 6. */
+  /** Table 6. Lookup table for SBox */
   SBoxTable : [32][5]
   SBoxTable =
       map drop
@@ -142,7 +147,8 @@ SBoxTable =
       , 0x10, 0x0c, 0x01, 0x19, 0x16, 0x0a, 0x0f, 0x17
       ]
 
-property SBoxCorrect x0 x1 x2 x3 x4 = [y0, y1, y2, y3, y4] == SBox [x0, x1, x2, x3, x4]
+  property
+    SBoxCorrect x0 x1 x2 x3 x4 = [y0, y1, y2, y3, y4] == SBox [x0, x1, x2, x3, x4]
       where
         y0 = x4&&x1 ^ x3 ^ x2&&x1 ^ x2 ^ x1&&x0 ^ x1 ^ x0
         y1 = x4 ^ x3&&x2 ^ x3&&x1 ^ x3 ^ x2&&x1 ^ x2 ^ x1 ^ x0
@@ -152,6 +158,7 @@ property SBoxCorrect x0 x1 x2 x3 x4 = [y0, y1, y2, y3, y4] == SBox [x0, x1, x2,
 
   // 3.4. Linear Diffusion Layer pL
 
+  /** The linear diffusion layer 𝑝𝐿 provides diffusion within each 64-bit word 𝑆𝑖. */
   pL : State -> State
   pL [S0, S1, S2, S3, S4] =
       [ sigma S0 19 28
@@ -164,20 +171,26 @@ pL [S0, S1, S2, S3, S4] =
           sigma : [64] -> [6] -> [6] -> [64]
           sigma x i j = x ^ x>>>i ^ x>>>j
 
+  /** Concatenate a sequence of integers into a little-endian bitstream. */
   wordsToBits : {w, n} (fin w) => [n][w] -> [w*n]
   wordsToBits M = join (map reverse M)
 
+  /** Split a little-endian bitstream in to a sequence of integers. */
   bitsToWords : {w, n} (fin w) => [w*n] -> [n][w]
   bitsToWords M = map reverse (split M)
 
 // 4. Authenticated Encryption Schema: Ascon-AEAD128
 
-/** Encryption using Ascon-AEAD128
+/** Ascon-AEAD128 encryption algorithm on bitstreams
+ *
+ * Type parameters:
+ * - a: Bit-length of associated data
+ * - p: Bit-length of plaintext
  *
  * Parameters:
  * - K: Key
  * - N: Nonce
- * - A: Additional data
+ * - A: Associated data
  * - P: Plaintext
  *
  * Returns:
@@ -189,11 +202,10 @@ AEAD128_encrypt K N A P = C # T
     [K0, K1] = bitsToWords K
     [N0, N1] = bitsToWords N
 
-    S0 = Ascon_p`{12} [Ascon_AEAD128_IV, K0, K1, N0, N1] ^ [0, 0, 0, K0, K1]
+    S0 = Ascon_p`{12} [AEAD128_IV, K0, K1, N0, N1] ^ [0, 0, 0, K0, K1]
     SA = AddAD S0 A
 
     SCs = [XorBlock s p | s <- [SA] # map Ascon_p`{8} SCs | p <- toBlocks P]
-
     C = take (join (map ExtractC SCs))
 
     ST = Ascon_p`{12} (last SCs ^ [0, 0, K0, K1, 0])
@@ -202,13 +214,13 @@ AEAD128_encrypt K N A P = C # T
 /** Ascon-AEAD128 decryption algorithm on bitstreams.
  *
  * Type parameters:
- * - a: Bit-length of additional data
+ * - a: Bit-length of associated data
  * - p: Bit-length of plaintext
  *
  * Parameters:
  * - K: Key
  * - N: Nonce
- * - A: Additional data
+ * - A: Associated data
  * - C: Ciphertext
  *
  * Returns:
@@ -216,39 +228,36 @@ AEAD128_encrypt K N A P = C # T
  * - None on authentication failure
  */
 AEAD128_decrypt : {a, p} (fin a, fin p) => [128] -> [128] -> [a] -> [p + 128] -> Option [p]
-AEAD128_decrypt K N A (Cs_ # Cl # T) =
-  if T == T' then Some P else None
+AEAD128_decrypt K N A (C # T) = if T == T' then Some P else None
   where
     // key and nonce as two 64-bit integers
     [K0, K1] = bitsToWords K
     [N0, N1] = bitsToWords N
 
-    S0 = Ascon_p`{12} [Ascon_AEAD128_IV, K0, K1, N0, N1] ^ [0, 0, 0, K0, K1]
+    S0 = Ascon_p`{12} [AEAD128_IV, K0, K1, N0, N1] ^ [0, 0, 0, K0, K1]
     SA = AddAD S0 A
 
-    Cs = split`{p / 128} Cs_
+    (Cs, Cl1) = parse C
+    SCs = [SA] # [Ascon_p`{8} (AssignC s c) | s <- SCs | c <- Cs]
 
-    SCs # [SCl] = [SA] # [Ascon_p`{8} (AssignC s c) | s <- SCs | c <- Cs]
-    Masks = map ExtractC SCs
+    Mask # Cl2 = join (map ExtractC SCs)
+    P = Mask ^ C
 
-    Maskl # SCl' = ExtractC SCl
-    Sl' = AssignC SCl (Cl # (0b1#0 ^ SCl'))
+    Cl = Cl1 # (0b1#0 ^ Cl2) // xor toggles the padding bit
+    ST1 = AssignC (last SCs) Cl
+    ST2 = Ascon_p`{12} (ST1 ^ [0, 0, K0, K1, 0])
+    T' = ExtractT ST2 ^ K
 
-    P = join (Masks ^ Cs) # (Maskl ^ Cl)
-
-    ST = Ascon_p`{12} (Sl' ^ [0, 0, K0, K1, 0])
-    T' = ExtractT ST ^ K
-
-/** Ascon-AEAD128 encryption function on bytes.
+/** Ascon-AEAD128 encryption algorithm on bytes.
  *
  * Type parameters:
- * - a: Byte-length of additional data
+ * - a: Byte-length of associated data
  * - p: Byte-length of plaintext
  *
  * Parameters:
  * - K: Key
  * - N: Nonce
- * - A: Additional data
+ * - A: Associated data
  * - P: Plaintext
  *
  * Returns:
@@ -261,13 +270,13 @@ AEAD128_encrypt_bytes K N A P =
 /** Ascon-AEAD128 decryption algorithm on bytes.
  *
  * Type parameters:
- * - a: Bit-length of additional data
- * - p: Bit-length of plaintext
+ * - a: Byte-length of associated data
+ * - p: Byte-length of plaintext
  *
  * Parameters:
  * - K: Key
  * - N: Nonce
- * - A: Additional data
+ * - A: Associated data
  * - C: Ciphertext
  *
  * Returns:
@@ -280,39 +289,52 @@ AEAD128_decrypt_bytes K N A C =
     None -> None
     Some p -> Some (bitsToWords p)
 
+private
+  /** Absorb all of the associated data into the permutation state. */
   AddAD : {a} (fin a) => State -> [a] -> State
   AddAD S A
       | a == 0 => DomainSep S
-    | a > 0  => DomainSep (foldl AbsorbBlock128 S (toBlocks A))
+      | a > 0  => DomainSep (foldl AbsorbADBlock S (toBlocks A))
 
+  /** Absorb a single block of associated data into the permutation state. */
+  AbsorbADBlock : State -> [128] -> State
+  AbsorbADBlock S X = Ascon_p`{8} (XorBlock S X)
+
+  /** Toggle the domain separation bit indicating end of associated data. */
   DomainSep : State -> State
   DomainSep [s0, s1, s2, s3, s4] = [s0, s1, s2, s3, s4 ^ 0b1#0]
 
-AbsorbBlock128 : State -> [128] -> State
-AbsorbBlock128 S X = Ascon_p`{8} (XorBlock S X)
-
+  /** Add a single block of data into the permutation state. */
   XorBlock : State -> [128] -> State
   XorBlock [s0, s1, s2, s3, s4] (xhi # xlo) = [s0 ^ xlo, s1 ^ xhi, s2, s3, s4]
 
+  /** Extracts the first two words of permutation state as a bitstream. */
   ExtractC : State -> [128]
   ExtractC [s0, s1, _, _, _] = wordsToBits [s0, s1]
 
+  /** Assigns a bitstream into the first two words of permutation state. */
   AssignC : State -> [128] -> State
   AssignC [_, _, s2, s3, s4] C = bitsToWords C # [s2, s3, s4]
 
+  /** Extracts the last two words of permutation state as a bitstream. */
   ExtractT : State -> [128]
   ExtractT [_, _, _, s3, s4] = wordsToBits [s3, s4]
 
-Ascon_AEAD128_IV : [64]
-Ascon_AEAD128_IV = 0x00001000808c0001
+  /** Ascon-AEAD128 initialization vector */
+  AEAD128_IV : [64]
+  AEAD128_IV = 0x00001000808c0001
 
 // 5. Hash and eXtendable-Output Functions (XOFs)
 
+private
   /** Hash function construction
    *
    * Parameters:
    * - Initialization vector
    * - List of blocks as integers
+   *
+   * Returns:
+   * - Infinite message digest bitstream to be truncated by caller
    */
   hashBlocks : {n} (fin n) => [64] -> [n][64] -> [inf]
   hashBlocks IV Ms = wordsToBits [head S | S <- iterate Ascon_p`{12} Sn]
@@ -332,6 +354,9 @@ AbsorbBlock64 [s0, s1, s2, s3, s4] X = Ascon_p`{12} [X ^ s0, s1, s2, s3, s4]
  *
  * Parameters:
  * - M: Message
+ *
+ * Returns:
+ * - Message digest
  */
 Hash256 : {m} (fin m) => [m] -> [256]
 Hash256 M = take (hashBlocks Hash256_IV (toBlocks M))
@@ -343,13 +368,16 @@ Hash256 M = take (hashBlocks Hash256_IV (toBlocks M))
  *
  * Parameters:
  * - M: Message
+ *
+ * Returns:
+ * - Message digest
  */
 Hash256_bytes : {m} (fin m) => [m][8] -> [32][8]
 Hash256_bytes M = bitsToWords (Hash256 (wordsToBits M))
 
 /** Ascon-Hash256 initialization vector */
 Hash256_IV : [64]
-Hash256_IV = 0x0000080100cc0002
+private Hash256_IV = 0x0000080100cc0002
 
 // 5.2. Specification of Ascon-XOF128
 
@@ -361,17 +389,31 @@ Hash256_IV = 0x0000080100cc0002
  *
  * Parameters:
  * - M: Message
+ *
+ * Returns:
+ * - Variable-length message digest
  */
 XOF128 : {r, m} (fin m, fin r) => [m] -> [r]
 XOF128 M = take (hashBlocks XOF128_IV (toBlocks M))
 
-/** Ascon-XOF256 implementation on bytes. */
+/** Ascon-XOF256 implementation on bytes.
+ *
+ * Type parameters:
+ * - r: Byte-length of digest
+ * - m: Byte-length of message
+ *
+ * Parameters:
+ * - M: Message
+ *
+ * Returns:
+ * - Variable-length message digest
+ */
 XOF128_bytes : {r, n} (fin n, fin r) => [n][8] -> [r][8]
 XOF128_bytes M = bitsToWords (XOF128 (wordsToBits M))
 
 /** Ascon-XOF128 initialization vector */
 XOF128_IV : [64]
-XOF128_IV = 0x0000080000cc0003
+private XOF128_IV = 0x0000080000cc0003
 
 // 5.3. Specification of Ascon-CXOF128
 
@@ -385,6 +427,9 @@ XOF128_IV = 0x0000080000cc0003
  * Parameters:
  * - Z: User-defined customization string
  * - M: Message
+ *
+ * Returns:
+ * - Variable-length message digest
  */
 CXOF128 : {r, c, m} (fin m, fin r, fin c, 64 >= width c) => [c] -> [m] -> [r]
 CXOF128 Z M = take (hashBlocks CXOF128_IV Ms)
@@ -403,10 +448,13 @@ CXOF128 Z M = take (hashBlocks CXOF128_IV Ms)
  * Parameters:
  * - Z: User-defined customization string
  * - M: Message
+ *
+ * Returns:
+ * - Variable-length message digest
  */
 CXOF128_bytes : {r, z, m} (fin m, fin r, 61 >= width z) => [z][8] -> [m][8] -> [r][8]
 CXOF128_bytes Z M = bitsToWords (CXOF128 (wordsToBits Z) (wordsToBits M))
 
 /** Ascon-CXOF128 initialization vector */
 CXOF128_IV : [64]
-CXOF128_IV = 0x0000080000cc0004
+private CXOF128_IV = 0x0000080000cc0004