[implem-python] Documentation de Lilliput-Ⅰ et Lilliput-TBC

Idem, renommage des fonctions privées  avec un souligné pour que l'API
soit plus simple à comprendre.

⚠  Pas testé,  ça prend  littéralement 20  minutes à  l'implémentation
Python de générer les vecteurs de test, et c'est l'heure du dodo…

1 files changed, 61 insertions, 44 deletions

diff --git a/src/add_python/lilliput/tbc.py b/src/add_python/lilliput/tbc.py
index 5291994..50f9e2f 100644
--- a/src/add_python/lilliput/tbc.py
+++ b/src/add_python/lilliput/tbc.py
@@ -1,34 +1,51 @@
+# Implementation of the Lilliput-AE tweakable block cipher.
+#
+# Authors, hereby denoted as "the implementer":
+#     Kévin Le Gouguec,
+#     Léo Reynaud
+#     2019.
+#
+# For more information, feedback or questions, refer to our website:
+# https://paclido.fr/lilliput-ae
+#
+# To the extent possible under law, the implementer has waived all copyright
+# and related or neighboring rights to the source code in this file.
+# http://creativecommons.org/publicdomain/zero/1.0/
+
+"""Lilliput-TBC tweakable block cipher.
+
+This module provides functions to encrypt and decrypt blocks of 128 bits.
 """
-    Lilliput TBC
-"""
+
 from .constants import BLOCK_BYTES, Sbox
 from .multiplications import ALPHAS
 
 
-permutation = [14, 11, 12, 10, 8, 9, 13, 15, 3, 1, 4, 5, 6, 0, 2, 7]
-permutationInv = [13, 9, 14, 8, 10, 11, 12, 15, 4, 5, 3, 1, 2, 6 ,0 ,7]
+_permutation = [14, 11, 12, 10, 8, 9, 13, 15, 3, 1, 4, 5, 6, 0, 2, 7]
+_permutationInv = [13, 9, 14, 8, 10, 11, 12, 15, 4, 5, 3, 1, 2, 6 ,0 ,7]
 
 ################################################################################
 
-def BuildTweakey(tweak, key):
+def _BuildTweakey(tweak, key):
     return tweak+key
 
 #############################
 
-def _lane(TK, j):
+def _Lane(TK, j):
     return TK[j*8:(j+1)*8]
 
-def RoundTweakeySchedule(tweakey):
+
+def _RoundTweakeySchedule(tweakey):
     p = len(tweakey)//8
 
     multiplied_lanes = (
-        ALPHAS[j](_lane(tweakey, j)) for j in range(p)
+        ALPHAS[j](_Lane(tweakey, j)) for j in range(p)
     )
 
     return [byte for lane in multiplied_lanes for byte in lane]
 
 
-def SubTweakeyExtract(tweakey, Ci):
+def _SubTweakeyExtract(tweakey, Ci):
     RTKi = [0]*8
 
     for j, byte in enumerate(tweakey):
@@ -39,22 +56,22 @@ def SubTweakeyExtract(tweakey, Ci):
     return RTKi
 
 
-def TweakeyScheduleWhole(tweakey, r):
-    # store main tweakey in TKs[0]
-    # and corresponding round tweakey in RTKs[0]
+def _TweakeyScheduleWhole(tweakey, r):
+    # Store the initial tweakey in TKs[0], and the corresponding round tweakey
+    # in RTKs[0].
     TKs = [tweakey]
-    RTKs = [SubTweakeyExtract(TKs[0], 0)]
+    RTKs = [_SubTweakeyExtract(TKs[0], 0)]
 
     for i in range(1, r):
-        TKs.append(RoundTweakeySchedule(TKs[i-1]))
-        RTKs.append(SubTweakeyExtract(TKs[i], i))
+        TKs.append(_RoundTweakeySchedule(TKs[i-1]))
+        RTKs.append(_SubTweakeyExtract(TKs[i], i))
 
     return RTKs
 
 
 ################################################################################
 
-def NonLinearLayer(state, subtweakey):
+def _NonLinearLayer(state, subtweakey):
 
     variables_xored = [0 for byte in range(0, 8)]
     for byte in range(0,8):
@@ -73,7 +90,7 @@ def NonLinearLayer(state, subtweakey):
     return state_output
 
 
-def LinearLayer(state):
+def _LinearLayer(state):
     state_output = [0 for byte in range(0, BLOCK_BYTES)]
     for byte in range(0, BLOCK_BYTES):
         state_output[byte] = state[byte]
@@ -87,44 +104,44 @@ def LinearLayer(state):
     return state_output
 
 
-def PermutationLayerEnc(state):
+def _PermutationLayerEnc(state):
     state_output = [0 for byte in range(0, BLOCK_BYTES)]
     for byte in range(0, BLOCK_BYTES):
-        state_output[byte] = state[permutation[byte]]
+        state_output[byte] = state[_permutation[byte]]
 
     return state_output
 
-def PermutationLayerDec(state):
+def _PermutationLayerDec(state):
     state_output = [0 for byte in range(0, BLOCK_BYTES)]
     for byte in range(0, BLOCK_BYTES):
-        state_output[byte] = state[permutationInv[byte]]
+        state_output[byte] = state[_permutationInv[byte]]
 
     return state_output
 
 
-def OneRoundEGFNEnc(state, subtweakey):
-    state_non_linear = NonLinearLayer(state, subtweakey)
-    state_linear = LinearLayer(state_non_linear)
-    state_permutation = PermutationLayerEnc(state_linear)
+def _OneRoundEGFNEnc(state, subtweakey):
+    state_non_linear = _NonLinearLayer(state, subtweakey)
+    state_linear = _LinearLayer(state_non_linear)
+    state_permutation = _PermutationLayerEnc(state_linear)
 
     return state_permutation
 
-def LastRoundEGFN(state, subtweakey):
-    state_non_linear = NonLinearLayer(state, subtweakey)
-    state_linear = LinearLayer(state_non_linear)
+def _LastRoundEGFN(state, subtweakey):
+    state_non_linear = _NonLinearLayer(state, subtweakey)
+    state_linear = _LinearLayer(state_non_linear)
 
     return state_linear
 
 
-def OneRoundEGFNDec(state, subtweakey):
-    state_non_linear = NonLinearLayer(state, subtweakey)
-    state_linear = LinearLayer(state_non_linear)
-    state_permutation = PermutationLayerDec(state_linear)
+def _OneRoundEGFNDec(state, subtweakey):
+    state_non_linear = _NonLinearLayer(state, subtweakey)
+    state_linear = _LinearLayer(state_non_linear)
+    state_permutation = _PermutationLayerDec(state_linear)
 
     return state_permutation
 
 
-def _rounds(key_bytes):
+def _Rounds(key_bytes):
     rounds = {
         128: 32,
         192: 36,
@@ -134,45 +151,45 @@ def _rounds(key_bytes):
 
 
 ################################################################################
-# Lilliput TBC
+
 
 def encrypt(tweak, key, message):
-    r = _rounds(len(key))
+    r = _Rounds(len(key))
 
-    tweakey = BuildTweakey(tweak, key)
-    RTKs = TweakeyScheduleWhole(tweakey, r)
+    tweakey = _BuildTweakey(tweak, key)
+    RTKs = _TweakeyScheduleWhole(tweakey, r)
 
     state = [0 for byte in range(0, BLOCK_BYTES)]
     for byte in range(0, BLOCK_BYTES):
         state[byte] = message[byte]
 
     for i in range(0, r-1):
-        state_output = OneRoundEGFNEnc(state, RTKs[i])
+        state_output = _OneRoundEGFNEnc(state, RTKs[i])
 
         for byte in range(0, BLOCK_BYTES):
             state[byte] = state_output[byte]
 
-    state_output = LastRoundEGFN(state, RTKs[r-1])
+    state_output = _LastRoundEGFN(state, RTKs[r-1])
 
     return state_output
 
 
 def decrypt(tweak, key, cipher):
-    r = _rounds(len(key))
+    r = _Rounds(len(key))
 
-    tweakey = BuildTweakey(tweak, key)
-    RTKs = TweakeyScheduleWhole(tweakey, r)
+    tweakey = _BuildTweakey(tweak, key)
+    RTKs = _TweakeyScheduleWhole(tweakey, r)
 
     state = [0 for byte in range(0, BLOCK_BYTES)]
     for byte in range(0, BLOCK_BYTES):
         state[byte] = cipher[byte]
 
     for i in range(0, r-1):
-        state_output = OneRoundEGFNDec(state, RTKs[r-i-1])
+        state_output = _OneRoundEGFNDec(state, RTKs[r-i-1])
 
         for byte in range(0, BLOCK_BYTES):
             state[byte] = state_output[byte]
 
-    state_output = LastRoundEGFN(state, RTKs[0])
+    state_output = _LastRoundEGFN(state, RTKs[0])
 
     return state_output