[implem-python] Documentation du mode authentifié Lilliput-Ⅱ

Ajout d'un souligné devant les fonctions privées ; de cette façon,

    >>> from lilliput import lilliput_ae_1
    >>> help(lilliput_ae_1)

…  ne   montre  que  les   fonctions  "publiques",  i.e.   celles  que
l'utilisateur est censé appeler.

1 files changed, 32 insertions, 16 deletions

diff --git a/src/add_python/lilliput/lilliput_ae_2.py b/src/add_python/lilliput/lilliput_ae_2.py
index 61aa86e..fb6feff 100644
--- a/src/add_python/lilliput/lilliput_ae_2.py
+++ b/src/add_python/lilliput/lilliput_ae_2.py
@@ -1,5 +1,21 @@
-"""
-    SCT 2 for lilliput ae 2
+# 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-II Authenticated Encryption mode.
+
+This module provides the functions for authenticated encryption and decryption
+using Lilliput-AE's nonce-misuse-resistant mode based on SCT-2.
 """
 
 from .constants import BLOCK_BYTES
@@ -18,7 +34,7 @@ TWEAK_BITS = 128
 TWEAK_BYTES = TWEAK_BITS//8
 
 
-def TweakTag(j, padded):
+def _TweakTag(j, padded):
     tweak = [0 for byte in range(0, TWEAK_BYTES)]
 
     tweak[TWEAK_BYTES - 1] |= ((j >> 120) & 0xf)
@@ -31,7 +47,7 @@ def TweakTag(j, padded):
     return tweak
 
 
-def TweakTagEnd(N):
+def _TweakTagEnd(N):
     tweak = [0 for byte in range(0, TWEAK_BYTES)]
 
     for byte in range(0, TWEAK_BYTES - 1):
@@ -41,7 +57,7 @@ def TweakTagEnd(N):
     return tweak
 
 
-def AddTagJ(tag, j):
+def _AddTagJ(tag, j):
     array_j = [0 for byte in range(0, TWEAK_BYTES)]
     for byte in range(0, TWEAK_BYTES):
         array_j[byte] = (j >> (byte * 8))
@@ -53,7 +69,7 @@ def AddTagJ(tag, j):
     return xorr
 
 
-def MesssageAuthTag(M, N, Auth, key):
+def _MesssageAuthTag(M, N, Auth, key):
     l = len(M)//BLOCK_BYTES
     need_padding = len(M)%BLOCK_BYTES > 0
 
@@ -61,24 +77,24 @@ def MesssageAuthTag(M, N, Auth, key):
     M = ArrayToBlockbytesMatrix(M)
 
     for j in range(0, l):
-        tweak = TweakTag(j, False)
+        tweak = _TweakTag(j, False)
         encryption = tbc.encrypt(tweak, key, M[j])
         tag = XorState(tag, encryption)
 
     if need_padding:
-        tweak = TweakTag(l, True)
+        tweak = _TweakTag(l, True)
         m_padded = Padding10LSB(M[l])
         encryption = tbc.encrypt(tweak, key, m_padded)
         tag = XorState(tag, encryption)
 
-    tweak = TweakTagEnd(N)
+    tweak = _TweakTagEnd(N)
     encryption = tbc.encrypt(tweak, key, tag)
     tag = encryption
 
     return tag
 
 
-def MessageEncryption(M, N, tag, key):
+def _MessageEncryption(M, N, tag, key):
     l = len(M)//BLOCK_BYTES
     need_padding = len(M)%BLOCK_BYTES > 0
 
@@ -86,13 +102,13 @@ def MessageEncryption(M, N, tag, key):
     C = []
 
     for j in range(0, l):
-        tweak = AddTagJ(tag, j)
+        tweak = _AddTagJ(tag, j)
         padded_nonce = list(N) + [0x00]
         encryption = tbc.encrypt(tweak, key, padded_nonce)
         C.append(XorState(M[j], encryption))
 
     if need_padding:
-        tweak = AddTagJ(tag, l)
+        tweak = _AddTagJ(tag, l)
         padded_nonce = list(N) + [0x00]
         encryption = tbc.encrypt(tweak, key, padded_nonce)
         C.append(XorState(M[l], encryption))
@@ -105,8 +121,8 @@ def encrypt(A, M, N, key):
     K = list(key)
 
     Auth = BuildAuth(TWEAK_BITS, A, K)
-    tag = MesssageAuthTag(M, N, Auth, K)
-    C = MessageEncryption(M, N, tag, K)
+    tag = _MesssageAuthTag(M, N, Auth, K)
+    C = _MessageEncryption(M, N, tag, K)
 
     return BlockbytesMatrixToBytes(C), bytes(tag)
 
@@ -116,10 +132,10 @@ def decrypt(A, C, N, tag, key):
     tag = list(tag)
 
     M = BlockbytesMatrixToBytes(
-        MessageEncryption(C, N, tag, K)
+        _MessageEncryption(C, N, tag, K)
     )
     Auth = BuildAuth(TWEAK_BITS, A, K)
-    tag2 = MesssageAuthTag(M, N, Auth, K)
+    tag2 = _MesssageAuthTag(M, N, Auth, K)
 
     if tag != tag2:
         raise TagValidationError(tag, tag2)