fips-collection 1.0.0__py3-none-any.whl

fips/FIPS204/__init__.py

@@ -0,0 +1,10 @@
+from .parameter import(
+    MLDSA_44, MLDSA_65, MLDSA_87
+)
+
+
+__all__ = [
+    "MLDSA_44",
+    "MLDSA_65",
+    "MLDSA_87",
+]

fips/FIPS204/auxilary.py

@@ -0,0 +1,369 @@
+class AUXILARY:
+    """
+    This class provides subroutines utilized by MLDSA, including function for data-type converstions and arithmetic.
+    """
+
+    def __init__(self, parameter: dict[str, int]):
+        self.q = parameter["q"]
+        self.N = parameter["N"]
+        self.eta = parameter["eta"]
+
+    def IntegerToBits(self, x: int, alpha: int):
+        """
+        Algorithm 9
+
+        Computes the base-2 representation of x mod 2^alpha in ``little-endian`` order.
+
+        Args:
+            x (``int``): A ``non-negative`` integer.
+            alpha (``int``): Number of ``bits`` to represent.
+
+        Returns:
+            str (``bits``): ``Bitstring`` of length ``alpha`` in ``little-endian`` order.
+
+        Raises:
+            ValueError: If x is ``negative`` or alpha is not a positive integer.
+            ValueError: If x is ``too big`` to be represented in alpha bits.
+            TypeError: If x or alpha is ``not an integer``.
+        """
+
+        if x < 0:
+            raise ValueError("x must be non-negative.")
+        if alpha <= 0:
+            raise ValueError("alpha must be a positive integer.")
+        if x >= 2 ** alpha:
+            raise ValueError(f"x = {x} cannot be represented in {alpha} bits.")
+        
+        x_mod = x
+        bits:list[str] = []
+        for _ in range(alpha):
+            bits.append(str(x_mod % 2))
+            x_mod //= 2
+
+        return ''.join(bits)
+
+    def BitsToInteger(self, y: str, alpha: int) -> int:
+        """
+        Algorithm 10
+
+        Computes the ``integer`` value expressed by a bit string using ``little-endian`` order.
+
+        Args:
+            y (``bitstring``): ``Bitstring`` to convert to an integer.
+            alpha (``int``): Number of ``bits`` to consider.
+
+        Returns:
+            integer (``int``): The ``integer`` value represented by the ``bitstring``.
+
+        Raises:
+            ValueError: If the length of ``y`` does not match alpha or if ``y`` contains invalid characters.
+            TypeError: If ``y`` is not a ``string`` or alpha is not an ``integer``.
+        """
+        if alpha <= 0:
+            raise ValueError("alpha must be a positive integer.")
+        if len(y) != alpha:
+            raise ValueError(f"Bit string y must have exactly {alpha} bits.")
+        if any(bit not in "01" for bit in y):
+            raise ValueError("Bit string y must contain only '0' and '1' characters.")
+
+        x = 0
+        for i in range(1, alpha + 1):
+            bit = int(y[alpha - i])  
+            x = 2 * x + bit
+        return x
+
+    def IntegerToBytes(self, x: int, alpha: int) -> bytes:
+        """
+        Algorithm 11
+
+        Computes a base-256 representation of x mod 256^alpha in ``little-endian`` order.
+
+        Args:
+            x (``int``): A ``non-negative`` integer.
+            alpha (``int``): Number of ``bytes`` in the output.
+
+        Returns:
+            bytes (``bytes``): ``Bytestring`` of length alpha in ``little-endian`` order.
+
+        Raises:
+            ValueError: x = _ cannot be represented in _ bytes.
+        """
+        try:
+            return x.to_bytes(alpha, byteorder = "little")
+        except OverflowError:
+            raise ValueError(f"x = {x} cannot be represented in {alpha} bytes.")
+
+    def BitsToBytes(self, y: str) -> bytes:
+        """
+        Algorithm 12
+
+        Converts a ``bitstring`` y into a ``bytestring`` using ``little-endian`` order.
+
+        Args:
+            y (``str``): ``Bitstring`` consisting of ``0`` and ``1``.
+
+        Returns:
+            bytes (``bytes``): ``Bytestring`` of length ceil ``(len(y) / 8)``.
+
+        Raises:
+            TypeError: If y is ``not a string``.
+            ValueError: If y contains characters other than ``0`` or ``1``.
+        """
+        if any(bit not in "01" for bit in y):
+            raise ValueError("Bit string y must contain only '0' and '1'.")
+
+        alpha = len(y)
+        byte_len = (alpha + 7) // 8  # Equivalent to ceil(alpha / 8)
+        z = [0] * byte_len
+
+        for i in range(alpha):
+            byte_index = i // 8
+            bit_index = i % 8
+            z[byte_index] |= int(y[i]) << bit_index
+
+        return bytes(z)
+        
+    def BytesToBits(self, z: bytes) -> str:
+        """
+        Algorithm 13
+
+        Converts a ``bytestring`` ``z`` into a ``bitstring`` in ``little-endian`` order.
+    
+        Args:
+            z (``bytes``): A ``bytestring``.
+    
+        Returns:
+            str (bit string): A ``bitstring`` of length ``8 * len(z)``, in ``little-endian`` order.
+    
+        Raises:
+            TypeError: If ``z`` is not a ``bytes`` object.
+        """
+        if not isinstance(z, (bytes, bytearray)):
+            raise TypeError("Input z must be a bytes or bytearray object.")
+    
+        bits: list[str] = []
+        for byte in z:
+            for i in range(8):
+                bits.append(str((byte >> i) & 1))  # Little-endian bit order
+
+        return ''.join(bits)
+
+    def CoeffFromThreeBytes(self, b0: int, b1: int, b2:int) -> int | None:
+        """
+        Algorithm 14
+
+        Generates an element of {``0``, ``1``, ``2``, ... , ``q - 1``} U { ``None`` }
+        
+        Args:
+            b0 (``int``): first byte
+            b1 (``int``): second byte
+            b2 (``int``): third byte
+
+        Returns:
+            z (``int``): sampled coefficient or ``None`` if rejected.
+
+        Raises:
+            TypeError: if any of ``b0``, ``b1``, ``b2`` is ``not an integer``.
+        """
+        # checks for validity of inputs.
+        for i, b in enumerate((b0, b1, b2), start = 0):
+            if not (0 <= b <= 255):
+                raise ValueError (f"b{i} must be in the range 0 - 255.")
+        
+        # line 1: make a copy of b2.
+        b2_prime = b2
+
+        # line 2 to 4: making sure b2_prime is 7 bits, not 8.
+        if b2_prime > 127:
+            b2_prime = b2_prime - 128
+        
+        # line 5: evaluate z for sampling.
+        z = (b2_prime << 16) + (b1 << 8) + b0
+        
+        # line 6 to 8: reject the sample z if it's greater than q. 
+        if z < self.q:
+            return z # accept sample
+        else:
+            return None # reject sample
+
+    def CoeffFromHalfByte(self, b: int) -> int | None:
+        """
+        Algorithm 15
+
+        Let ``eta`` ∈ {2, 4}.
+
+        Generates an element of {``-eta``, ``-eta + 1``, ... , ``eta``} U { ``None`` }
+
+        Args:
+            b (``int``): an integer in the range ``0 - 15``.
+
+        Returns:
+            z (``int``): sampled coefficient or ``None`` if rejected.
+
+        Raises:
+            TypeError: if b is ``not an integer``.
+            ValueError: if b is ``not`` in the range ``0 - 15``.
+        """
+        if not (0 <= b <= 15):
+                raise ValueError (f"{b} must be in the range 0 - 15.")
+
+        # line 1 and 2: rejection sampline from {-2, ... , 2 }
+        if self.eta == 2 and b < 15:
+            return 2 - (b % 5)
+        
+        # line 3: rejection sampline from {-4, ... , 4 }
+        elif self.eta == 4 and b < 9:
+            return 4 - b
+        
+        # line 4: sample is just rejected.
+        else:
+            return None
+
+    def CenteredModulus(self, z: int) -> int:
+        """
+        Additional Helper Function 1
+
+        Computes the centered modulus ``z mod± q``.
+
+        Maps each integer ``x`` to the unique ``r`` in ::
+        
+            [-(q-1)/2, (q-1)/2]
+
+        such that ::
+        
+            x ≡ r (mod q).
+
+        Args:
+            z(``int``): An integer
+
+        Returns:
+            CenteredModulus(``int``)
+
+        Raises:
+            TypeError: If ``z`` is ``not an integer``.
+        """
+        half_q = (self.q - 1) // 2
+
+        return (z + half_q) % self.q - half_q
+
+    def CenteredModulusList(self, z: list[int]) -> list[int]:
+        """
+        Additional Helper Function 2
+
+        Computes the centered modulus ``z mod± q`` for a ``list`` of ``Integers``.
+
+        Maps each integer ``x`` to the unique ``r`` in ::
+        
+            [-(q-1)/2, (q-1)/2]
+
+        such that ::
+        
+            x ≡ r (mod q).
+
+        Args:
+            z(``list[int]``): A list of ``integers``.
+
+        Returns:
+            CenteredModulus(``list[int]``)
+
+        Raises:
+            TypeError: If ``z`` is not a ``list[int]``.
+        """
+        half_q = (self.q - 1) // 2
+
+        return [(x + half_q) % self.q - half_q for x in z]
+    
+    def CenteredModulusMatrix(self, z: list[list[int]]) -> list[list[int]]:
+        """
+        Additional Helper Function 3
+
+        Computes the centered modulus ``z mod± q`` for a ``matrix`` of ``Integers``.
+
+        Maps each integer ``x`` to the unique ``r`` in ::
+        
+            [-(q-1)/2, (q-1)/2]
+
+        such that ::
+        
+            x ≡ r (mod q).
+
+        Args:
+            z(``list[list[int]]``): A matrix of ``integers``.
+
+        Returns:
+            CenteredModulus(``list[list[int]]``)
+
+        Raises:
+            TypeError: If ``z`` is not a ``list[list[int]]``.
+        """
+        
+        half_q = (self.q - 1) // 2
+
+        return [[(x + half_q) % self.q - half_q for x in z[k]] for k in range(len(z))]
+
+    def abs_for_list (self, z: list[int]) -> list[int]:
+        """
+        Additional Helper Function 4
+
+        Computes the absolute values of a ``list`` of integers.
+
+        Args:
+            z (``list[int]``): A ``list`` of integers.
+
+        Returns:
+            |z| (``list[int]``): A ``list`` containing the ``absolute`` values of the input ``integers``.
+        """
+        for p in range (len(z)):
+            z[p] = abs(z[p])
+
+        return z
+    
+    def InfinityNorm(self, z: list[list[int]]) -> int:
+        """
+        Additional Helper Function 5
+
+        Compute the ``L-Infinity Norm`` of a ``Matrix``.
+
+        Args:
+            z (``list[list[int]]``): A ``Matrix`` of integers.
+
+        Returns:
+            infinity_norm (``int``): The infinity norm (``maximum`` absolute value) among all lists.
+
+        Raises:
+            TypeError: If ``z`` is not a list of lists of ``integers``.
+            TypeError: If any element in the sublists is ``not an integer``.
+            TypeError: If elements of ``z[x]`` are not lists.
+        """
+        max_value = 0
+
+        for i in range (len(z)):
+            if max_value < max(self.abs_for_list(self.CenteredModulusList(z[i]))):
+                max_value = max(self.abs_for_list(self.CenteredModulusList(z[i])))
+
+        return max_value # returns the max value among all lists.
+    
+    def CalcOnes(self, h: list[list[int]]) -> int:
+        """
+        Additional Helper Function 6
+
+        Compute the number of ``1`` s inside a ``list[list[int]]`` .
+
+        Args:
+            h (``list[list[int]]``): A ``matrix`` containing ``0`` s and ``1`` s.
+
+        Returns:
+            Count(``int``): The count of ``1`` s in the ``matrix``.
+
+        Raises:
+            TypeError: If ``h`` is not a ``matrix`` of integers.
+            TypeError: If any element in the sublists is not an integer .
+            TypeError: If elements of ``h[x]`` are not ``0`` or ``1``.
+        """
+        count = 0
+        for i in range(len(h)):
+            for j in range(len(h[i])):
+                if h[i][j] == 1:
+                    count = count + 1
+
+        return count

fips/FIPS204/encode.py

@@ -0,0 +1,300 @@
+from .pack import PACK
+
+class ENCODE:
+    """
+    Translate keys and signature for MLDSA into byte strings.
+    """
+
+    def __init__(self, parameter: dict[str, int]):
+        self.pack = PACK(parameter)
+
+        self.q = parameter["q"]
+        self.d = parameter["d"]
+        self.N = parameter["N"]
+
+        self.k = parameter["k"]
+        self.l = parameter["l"]
+        self.eta = parameter["eta"]
+        self.gamma1 = parameter["gamma1"]
+        self.gamma2 = parameter["gamma2"]
+        self._lambda = parameter["_lambda"] # using _lambda because lambda is not allowed.
+
+        self.omega = parameter["omega"]
+
+    def pkEncode(self, rho: bytes, t1_vec: list[list[int]]) -> bytes:
+        """
+        Algorithm 22
+
+        Encodes a ``public key`` for MLDSA into a ``bytestring``.
+
+        Args:
+            rho (``bytes``): The ``32-byte`` seed.
+            t1_vec (``list``): The vector of ``k`` polynomials for ``t₁``.
+
+        Returns:
+            public_key (``bytes``): The final encoded ``public key`` as a ``bytestring``.
+
+        Raises: 
+            ValueError: if ``rho`` or ``t1_vec`` are of incorrect types or lengths.
+        """
+        if not isinstance(rho, (bytes, bytearray)) or len(rho) != 32:
+            raise ValueError("rho must be a 32-byte  bytestring.")
+        # if not isinstance(t1_vec, list) or len(t1_vec) != self.k:
+        #     raise ValueError(f"t1 must be a list of {self.k} polynomials.")
+
+        # 1: pk ← ρ
+        # Using a bytearray for efficient concatenation
+        pk = bytearray(rho)
+
+        # Calculate the number of bits needed to store each t₁ coefficient
+        max_bit = pow(2, (self.q - 1).bit_length() - self.d) - 1 # This is 23 - 13 = 10
+
+        # 2: for i from 0 to k - 1 do
+        for poly_t1 in t1_vec:
+            # 3: pk ← pk || SimpleBitPack(...)
+            packed_poly = self.pack.SimpleBitPack(poly_t1, max_bit)
+            pk.extend(packed_poly)
+
+        # 5: return pk
+        return bytes(pk)
+
+    def pkDecode(self, pk: bytes) -> tuple[bytes, list[list[int]]]:
+        """
+        Algorithm 23
+
+        Reverses the procedure ``pkEncode``.
+
+        Args:
+            pk (bytes): public key bytestring::
+
+                Byte string of length 32 + k * length_p, where length_p = ceil(256 * bitlen(q-1)-d / 8)
+
+        Returns:
+            rho(``bytes``) : 32-byte seed rho.
+
+            t1(``list[int]``): List of ``k`` polynomials, each with ::
+            
+                256 coefficients in the range [0, 2^(bitlen(q-1)-d) - 1].
+        
+        Raises: 
+            ValueError: if ``pk`` is of incorrect type.
+        """
+        if not  isinstance(pk, (bytes, bytearray)):
+            raise ValueError("pk must be a bytestring.")
+
+        bitlen = (self.q - 1).bit_length() - self.d
+        # expected_len = 32 + 32 * self.k * bitlen
+
+        # if not isinstance(pk, (bytes, bytearray)) or len(pk) != expected_len:
+        #     raise ValueError(f"pk must be a byte string of length {expected_len} bytes.")
+
+        rho = pk[:32] # assign the first 32 bits
+        t1: list[list[int]] = [] # initialize empty list
+
+        offset = 32
+        for i in range(self.k):
+            start = i * 32 * bitlen + offset
+            end = start + 32 * bitlen
+            segment = pk[start:end]
+            coeffs = self.pack.SimpleBitUnpack(segment, pow(2, bitlen) - 1)
+            if len(coeffs) != 256:
+                raise ValueError("Each unpacked polynomial must have 256 coefficients.")
+            t1.append(coeffs)
+
+        return rho, t1
+
+    def skEncode(self, rho: bytes, K_seed: bytes, tr: bytes, s1_vec: list[list[int]], s2_vec: list[list[int]], t0_vec: list[list[int]]) -> bytes:
+        """
+        Algorithm 24
+        
+        Encodes a ``secret key`` for MLDSA into a ``bytestring``.
+
+        Args:
+            rho (``bytes``): The 32-byte seed.
+            K_seed (``bytes``): The 32-byte ``K`` seed.
+            tr (``bytes``): The 64-byte ``tr`` value.
+            s1_vec (``list[int]``): The vector of ``l`` polynomials for ``s₁``.
+            s2_vec (``list[int]``): The vector of ``k`` polynomials for ``s₂``.
+            t0_vec (``list[int]``): The vector of ``k`` polynomials for ``t₀``.
+
+        Returns:
+            private_key(``bytes``): The final encoded private key as a ``bytestring``.
+
+        Raises: 
+            ValueError: if ``rho``, ``K_seed``, ``tr``, ``s₁_vec``, ``s2_vec``, or ``t0_vec`` are of incorrect types or lengths.
+        """
+        if not isinstance(rho, (bytes, bytearray)) or len(rho) != 32:
+            raise ValueError("rho must be a 32-byte bytestring.")
+        if not isinstance(K_seed, (bytes, bytearray)) or len(K_seed) != 32:
+            raise ValueError("K_seed must be a 32-byte bytestring.")
+        if not isinstance(tr, (bytes, bytearray)) or len(tr) != 64:
+            raise ValueError("tr must be a 64-byte bytestring.")
+        
+        # 1: sk ← ρ || K || tr
+        sk = bytearray(rho + K_seed + tr)
+
+        # 2-4: Pack and append s₁
+        for poly in s1_vec:
+            sk.extend(self.pack.BitPack(poly, self.eta, self.eta))
+
+        # 5-7: Pack and append s₂
+        for poly in s2_vec:
+            sk.extend(self.pack.BitPack(poly, self.eta, self.eta))
+
+        # 8-10: Pack and append t₀
+        for poly in t0_vec:
+            sk.extend(self.pack.BitPack(poly, (1 << (self.d - 1)) - 1, (1 << (self.d - 1))))
+
+        # 11: return sk
+        return bytes(sk)
+
+    def skDecode(self, private_key: bytes):
+        """
+        Algorithm 25
+
+        Reverses the procedure performed by skEncode.
+
+        Args:
+            private_key (``bytes``): The byte string representing the ``private key``.
+        
+        Returns:
+            (Tuple[ ``bytes``, ``bytes``, ``bytes``, ``list``, ``list`` , ``list``]): A tuple containing (``rho``, ``K_seed``, ``tr``, ``s₁``, ``s2``, ``t0_vec``).
+
+        Raises:
+            ValueError: if private_key is of incorrect type.
+        """
+        if not isinstance(private_key, (bytes, bytearray)):
+            raise ValueError("private_key must be a bytestring.")   
+        
+        if self.eta == 2:
+            s_bytes = 96
+        else:
+            s_bytes = 128
+
+        # find length of all the vectors
+        s1_len = s_bytes * self.l 
+        s2_len = s_bytes * self.k
+        t0_len = 416 * self.k
+
+        # check length of private_key
+        if len(private_key) != 2 * 32 + 64 + s1_len + s2_len + t0_len:
+            raise ValueError("SK packed bytes is of the wrong length")
+        
+        # Split bytes between seeds and vectors
+        sk_seed_bytes, sk_vec_bytes = private_key[:128], private_key[128:]
+
+        # Unpack seed bytes
+        rho, K_seed, tr = (
+            sk_seed_bytes[:32],
+            sk_seed_bytes[32:64],
+            sk_seed_bytes[64:128],
+        )
+
+        # Unpack vector bytes
+        s1_bytes = sk_vec_bytes[:s1_len]
+        s2_bytes = sk_vec_bytes[s1_len : s1_len + s2_len]
+        t0_bytes = sk_vec_bytes[-t0_len:]
+        # print(s1_len, " ", s2_len, " ", t0_len)
+
+        # Unpack bytes to vectors
+        s1 = [[0] for _ in range(int(s1_len / s_bytes))]
+        for i in range(int(s1_len / s_bytes)):
+            s1[i] = self.pack.BitUnpack(s1_bytes[i * s_bytes: (i + 1) * s_bytes], self.eta, self.eta)
+
+        s2 = [[0] for _ in range(int(s2_len / s_bytes))]
+        for i in range(int(s2_len / s_bytes)):
+            s2[i] = self.pack.BitUnpack(s2_bytes[i * s_bytes: (i + 1) * s_bytes], self.eta, self.eta)
+
+        t0_vec = [[0] for _ in range(int(t0_len / 416))]
+        for i in range(int(t0_len / 416)):
+            t0_vec[i] = self.pack.BitUnpack(t0_bytes[i * 416 : (i + 1) * 416], pow(2, self.d - 1) - 1, pow(2, self.d - 1))
+
+        return rho, K_seed, tr, s1, s2, t0_vec
+
+    def sigEncode(self, c_tilda: bytes, z: list[list[int]], h: list[list[int]]):
+        """
+        Algorithm 26
+
+        Encodes a ``signature`` into a ``bytestring``.
+
+        Args:
+            c_tilda (``bytes``): The byte string representing ``c_tilda``.
+            z (``bytes``): The list of ``l`` polynomials representing ``z``.
+            h (``bytes``): The list representing the hint vector ``h``.
+        
+        Returns:
+            signature (``bytes``): The final encoded signature as a ``bytestring``.
+        
+        Raises: 
+            ValueError: if ``c_tilda``, ``z``, or ``h`` are of incorrect types or lengths.
+        """
+        if not isinstance(c_tilda, (bytes, bytearray)) or len(c_tilda) != int(self._lambda / 4):
+            raise ValueError(f"c_tilda must be a bytestring of length {int(self._lambda / 4)}.")
+
+        sigma = b""
+        sigma = sigma + c_tilda
+        for i in range(self.l):
+            sigma = sigma + self.pack.BitPack(z[i], self.gamma1 -1, self.gamma1)
+        
+        sigma = sigma + self.pack.HintBitPack(h)
+
+        return sigma
+
+    def sigDecode(self, signature: bytes) -> tuple[bytes | bytearray, list[list[int]], list[list[int]] | None]:
+        """
+        Algorithm 27
+
+        Reverses the procedue ``sigEncode``.
+
+        Args:
+            signature (``bytes``): The ``bytestring`` representing the signature.
+
+        Returns:
+            tuple (``c_tilda``, ``z``, ``h``): A tuple containing the decoded components.
+
+        Raises: 
+            ValueError: if signature is of incorrect type.
+        """
+        if not isinstance(signature, (bytes, bytearray)):
+            raise ValueError("signature must be a bytestring.")
+
+        c_tilda = signature[:int(self._lambda / 4)]
+        x_list = signature[int(self._lambda / 4) : int(self._lambda / 4) + (32 * (1 + int((self.gamma1 - 1).bit_length()))) * self.l]
+        y = signature[-(self.omega + self.k):] # last remaining elements.
+
+        z: list[list[int]] = []   
+        size_x = 32 * (1 + (self.gamma1 -1).bit_length())
+
+        for i in range(self.l):
+            start = i * size_x
+            end = start + size_x
+            segment = x_list[start : end]
+            coefficients = self.pack.BitUnpack(segment, self.gamma1 -1, self.gamma1)
+            z.append(coefficients)
+        
+        h = self.pack.HintBitUnpack(y)
+
+        return (c_tilda, z, h)
+    
+    def w1Encode(self, w:list[list[int]]):
+        """
+        Algorithm 28
+
+        Encodes a polynomial vector ``w₁`` into a bytestring. 
+
+        Args:
+            w (``list``): The list of ``k`` polynomials representing ``w``.
+        
+        Returns:
+            w₁ (``bytes``): The encoded byte string ``w₁``.
+        
+        Raises: 
+            ValueError: if ``w`` is of incorrect type or length.
+        """
+        # if not isinstance(w, list) or len(w) != self.k:
+        #     raise ValueError(f"w must be a list of {self.k} polynomials.")
+        
+        w1 = b''
+        for i in range(self.k):
+            w1 = w1 + self.pack.SimpleBitPack(w[i], int((self.q - 1)/(2 * self.gamma2)) - 1)
+        return w1