[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, 34 insertions, 18 deletions

diff --git a/src/add_python/lilliput/lilliput_ae_1.py b/src/add_python/lilliput/lilliput_ae_1.py
index 0da2a95..1429002 100644
--- a/src/add_python/lilliput/lilliput_ae_1.py
+++ b/src/add_python/lilliput/lilliput_ae_1.py
@@ -1,5 +1,21 @@
-"""
-    OCB 3 for lilliput ae i
+# 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-I Authenticated Encryption mode.
+
+This module provides the functions for authenticated encryption and decryption
+using Lilliput-AE's nonce-misuse-resistant mode based on ΘCB3.
 """
 
 from enum import Enum
@@ -20,7 +36,7 @@ TWEAK_BITS = 192
 TWEAK_BYTES = TWEAK_BITS//8
 
 
-def LowPart(array, number_bits):
+def _LowPart(array, number_bits):
     shifted = 0
     for byte in range(0, len(array)):
         shifted |= (array[byte] << (8 * byte))
@@ -51,7 +67,7 @@ class _MessageTweak(Enum):
     FINAL = 0b0101
 
 
-def TweakMessage(N, j, padding):
+def _TweakMessage(N, j, padding):
     tweak = [0 for byte in range(0, TWEAK_BYTES)]
     for byte in range(NONCE_BYTES-1, -1, -1):
         tweak[byte + (TWEAK_BYTES-NONCE_BYTES)] |= (N[byte] & 0xf0) >> 4
@@ -66,7 +82,7 @@ def TweakMessage(N, j, padding):
     return tweak
 
 
-def TreatMessageEnc(M, N, key):
+def _TreatMessageEnc(M, N, key):
     checksum = [0 for byte in range(0, BLOCK_BYTES)]
 
     l = len(M)//BLOCK_BYTES
@@ -77,28 +93,28 @@ def TreatMessageEnc(M, N, key):
 
     for j in range(0, l):
         checksum = XorState(checksum, M[j])
-        tweak = TweakMessage(N, j, _MessageTweak.BLOCK)
+        tweak = _TweakMessage(N, j, _MessageTweak.BLOCK)
         C.append(tbc.encrypt(tweak, key, M[j]))
 
     if padding_bytes == 0:
-        tweak = TweakMessage(N, l, _MessageTweak.NO_PADDING)
+        tweak = _TweakMessage(N, l, _MessageTweak.NO_PADDING)
         Final = tbc.encrypt(tweak, key, checksum)
 
     else:
         m_padded = Padding10LSB(M[l])
         checksum = XorState(checksum, m_padded)
-        tweak = TweakMessage(N, l, _MessageTweak.PAD)
+        tweak = _TweakMessage(N, l, _MessageTweak.PAD)
         pad = tbc.encrypt(tweak, key, [0 for byte in range(0, BLOCK_BYTES)])
 
-        lower_part = LowPart(pad, padding_bytes*8)
+        lower_part = _LowPart(pad, padding_bytes*8)
         C.append(XorState(M[l], lower_part))
-        tweak_final = TweakMessage(N, l+1, _MessageTweak.FINAL)
+        tweak_final = _TweakMessage(N, l+1, _MessageTweak.FINAL)
         Final = tbc.encrypt(tweak_final, key, checksum)
 
     return (Final, C)
 
 
-def TreatMessageDec(C, N, key):
+def _TreatMessageDec(C, N, key):
     checksum = [0 for byte in range(0, BLOCK_BYTES)]
 
     l = len(C)//BLOCK_BYTES
@@ -108,23 +124,23 @@ def TreatMessageDec(C, N, key):
     M = []
 
     for j in range(0, l):
-        tweak = TweakMessage(N, j, _MessageTweak.BLOCK)
+        tweak = _TweakMessage(N, j, _MessageTweak.BLOCK)
         M.append(tbc.decrypt(tweak, key, C[j]))
         checksum = XorState(checksum, M[j])
 
     if padding_bytes == 0:
-        tweak = TweakMessage(N, l, _MessageTweak.NO_PADDING)
+        tweak = _TweakMessage(N, l, _MessageTweak.NO_PADDING)
         Final = tbc.encrypt(tweak, key, checksum)
 
     else:
-        tweak = TweakMessage(N, l, _MessageTweak.PAD)
+        tweak = _TweakMessage(N, l, _MessageTweak.PAD)
         pad = tbc.encrypt(tweak, key, [0 for byte in range(0, BLOCK_BYTES)])
-        lower_part = LowPart(pad, padding_bytes*8)
+        lower_part = _LowPart(pad, padding_bytes*8)
         M.append(XorState(C[l], lower_part))
 
         m_padded = Padding10LSB(M[l])
         checksum = XorState(checksum, m_padded)
-        tweak_final = TweakMessage(N, l+1, _MessageTweak.FINAL)
+        tweak_final = _TweakMessage(N, l+1, _MessageTweak.FINAL)
         Final = tbc.encrypt(tweak_final, key, checksum)
 
     return (Final, M)
@@ -135,7 +151,7 @@ def encrypt(A, M, N, key):
     K = list(key)
 
     Auth = BuildAuth(TWEAK_BITS, A, K)
-    (Final, C) = TreatMessageEnc(M, N, K)
+    (Final, C) = _TreatMessageEnc(M, N, K)
     tag = XorState(Auth, Final)
 
     return BlockbytesMatrixToBytes(C), bytes(tag)
@@ -146,7 +162,7 @@ def decrypt(A, C, N, tag, key):
     tag = list(tag)
 
     Auth = BuildAuth(TWEAK_BITS, A, K)
-    (Final, M) = TreatMessageDec(C, N, K)
+    (Final, M) = _TreatMessageDec(C, N, K)
     tag2 = XorState(Auth, Final)
 
     if tag != tag2: