transcrypto 1.8.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

transcrypto/{modmath.py → core/modmath.py}

@@ -12,7 +12,8 @@ from collections import abc
 
 import gmpy2
 
-from . import base, constants
+from transcrypto.core import constants
+from transcrypto.utils import base, saferandom
 
 _MAX_PRIMALITY_SAFETY = 100  # this is an absurd number, just to have a max
 
@@ -21,6 +22,79 @@ class ModularDivideError(base.Error):
   """Divide-by-zero-like exception (TransCrypto)."""
 
 
+def GCD(a: int, b: int, /) -> int:
+  """Greatest Common Divisor for `a` and `b`, integers ≥0. Uses the Euclid method.
+
+  O(log(min(a, b)))
+
+  Args:
+    a (int): integer a ≥ 0
+    b (int): integer b ≥ 0 (can't be both zero)
+
+  Returns:
+    gcd(a, b)
+
+  Raises:
+    base.InputError: invalid inputs
+
+  """
+  # test inputs
+  if a < 0 or b < 0 or (not a and not b):
+    raise base.InputError(f'negative input or undefined gcd(0, 0): {a=} , {b=}')
+  # algo needs to start with a >= b
+  if a < b:
+    a, b = b, a
+  # euclid
+  while b:
+    r: int = a % b
+    a, b = b, r
+  return a
+
+
+def ExtendedGCD(a: int, b: int, /) -> tuple[int, int, int]:
+  """Greatest Common Divisor Extended for `a` and `b`, integers ≥0. Uses the Euclid method.
+
+  O(log(min(a, b)))
+
+  Args:
+    a (int): integer a ≥ 0
+    b (int): integer b ≥ 0 (can't be both zero)
+
+  Returns:
+    (gcd, x, y) so that a * x + b * y = gcd
+    x and y may be negative integers or zero but won't be both zero.
+
+  Raises:
+    base.InputError: invalid inputs
+
+  """
+  # test inputs
+  if a < 0 or b < 0 or (not a and not b):
+    raise base.InputError(f'negative input or undefined gcd(0, 0): {a=} , {b=}')
+  # algo needs to start with a >= b (but we remember if we did swap)
+  swapped = False
+  if a < b:
+    a, b = b, a
+    swapped = True
+  # trivial case
+  if not b:
+    return (a, 0 if swapped else 1, 1 if swapped else 0)
+  # euclid
+  x1: int = 0
+  x2: int = 1
+  y1: int = 1
+  y2: int = 0
+  q: int
+  r: int
+  x: int
+  y: int
+  while b:
+    q, r = divmod(a, b)
+    x, y = x2 - q * x1, y2 - q * y1
+    a, b, x1, x2, y1, y2 = b, r, x, x1, y, y1
+  return (a, y2 if swapped else x2, x2 if swapped else y2)
+
+
 def ModInv(x: int, m: int, /) -> int:
   """Modular inverse of `x` mod `m`: a `y` such that (x * y) % m == 1 if GCD(x, m) == 1.
 
@@ -33,7 +107,7 @@ def ModInv(x: int, m: int, /) -> int:
     this only exists if GCD(x, m) == 1, so to guarantee an inverse `m` must be prime
 
   Raises:
-    InputError: invalid modulus or x
+    base.InputError: invalid modulus or x
     ModularDivideError: divide-by-zero, i.e., GCD(x, m) != 1 or x == 0
 
   """
@@ -47,7 +121,7 @@ def ModInv(x: int, m: int, /) -> int:
   if reduced_x == 1:  # trivial degenerate case
     return 1
   # compute actual extended GCD and see if we will have an inverse
-  gcd, y, w = base.ExtendedGCD(reduced_x, m)
+  gcd, y, w = ExtendedGCD(reduced_x, m)
   if gcd != 1:
     raise ModularDivideError(f'invalid inverse {x=} mod {m=} with {gcd=}')
   assert y and w and y >= -m, f'should never happen: {x=} mod {m=} -> {w=} ; {y=}'  # noqa: PT018, S101
@@ -67,7 +141,7 @@ def ModDiv(x: int, y: int, m: int, /) -> int:
     this only exists if GCD(y, m) == 1, so to guarantee an inverse `m` must be prime
 
   Raises:
-    InputError: invalid modulus or x or y
+    base.InputError: invalid modulus or x or y
     ModularDivideError: divide-by-zero, i.e., GCD(y, m) != 1 or y == 0
 
   """
@@ -105,7 +179,7 @@ def CRTPair(a1: int, m1: int, a2: int, m2: int) -> int:
     the least non-negative solution `x` such that a1 = x % m1 and a2 = x % m2 and 0 ≤ x < m1 * m2
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
     ModularDivideError: moduli are not co-prime, i.e. gcd(m1, m2) != 1
 
   """
@@ -137,7 +211,7 @@ def ModExp(x: int, y: int, m: int, /) -> int:
     (x ** y) mod m
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs
@@ -184,7 +258,7 @@ def ModPolynomial(x: int, polynomial: abc.Reversible[int], m: int, /) -> int:
     f(x) mod m
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs
@@ -228,7 +302,7 @@ def ModLagrangeInterpolate(x: int, points: dict[int, int], m: int, /) -> int:
     y-value solution for f(x) mod m given `points` mapping
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs
@@ -275,7 +349,7 @@ def FermatIsPrime(n: int, /, *, safety: int = 10, witnesses: set[int] | None = N
     False if certainly not prime ; True if (probabilistically) prime
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs and test for trivial cases: 1, 2, 3, divisible by 2
@@ -294,7 +368,7 @@ def FermatIsPrime(n: int, /, *, safety: int = 10, witnesses: set[int] | None = N
     safety = min(safety, max_safety)
     witnesses = set()
     while len(witnesses) < safety:
-      witnesses.add(base.RandInt(2, n - 2))
+      witnesses.add(saferandom.RandInt(2, n - 2))
   # we have our witnesses: do the actual Fermat algo
   for w in sorted(witnesses):
     if not 2 <= w <= (n - 2):  # noqa: PLR2004
@@ -323,7 +397,7 @@ def _MillerRabinWitnesses(n: int, /) -> set[int]:  # noqa: PLR0911
     {witness1, witness2, ...} for either "certainty" of primality or error chance < 10**25
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs
@@ -364,7 +438,7 @@ def _MillerRabinSR(n: int, /) -> tuple[int, int]:
     (s, r) so that (2 ** s) * r == (n - 1)
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs
@@ -395,7 +469,7 @@ def MillerRabinIsPrime(n: int, /, *, witnesses: set[int] | None = None) -> bool:
     False if certainly not prime ; True if (probabilistically) prime
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs and test for trivial cases: 1, 2, 3, divisible by 2
@@ -456,7 +530,7 @@ def PrimeGenerator(start: int, /) -> abc.Generator[int]:
     prime numbers (int)
 
   Raises:
-    InputError: invalid inputs
+    base.InputError: invalid inputs
 
   """
   # test inputs and make sure we start at an odd number
@@ -508,8 +582,8 @@ def NBitRandomPrimes(n_bits: int, /, *, serial: bool = True, n_primes: int = 1)
     set[int]: `n_primes` random primes with `n_bits` bits
 
   Raises:
-    InputError: invalid inputs
-    Error: prime search failed
+    base.InputError: invalid inputs
+    base.Error: prime search failed
 
   """
   # test inputs
@@ -563,7 +637,7 @@ def _PrimeSearchShard(n_bits: int) -> int | None:
 
   """
   shard_len: int = max(2000, 6 * int(0.693 * n_bits))  # ~6x expected prime gap ~2^k (≈ 0.693*k)
-  pr: int = base.RandBits(n_bits) | 1  # random position; make ODD
+  pr: int = saferandom.RandBits(n_bits) | 1  # random position; make ODD
   count: int = 0
   while count < shard_len and pr.bit_length() == n_bits:
     if IsPrime(pr):

transcrypto/{rsa.py → core/rsa.py}

@@ -13,7 +13,8 @@ from typing import Self
 
 import gmpy2
 
-from . import aes, base, modmath
+from transcrypto.core import aes, hashes, key, modmath
+from transcrypto.utils import base, saferandom
 
 _SMALL_ENCRYPTION_EXPONENT = 7
 _BIG_ENCRYPTION_EXPONENT = 2**16 + 1  # 65537
@@ -26,7 +27,7 @@ _RSA_SIGNATURE_HASH_PREFIX = b'transcrypto.RSA.Signature.1.0\x00'
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class RSAPublicKey(base.CryptoKey, base.Encryptor, base.Verifier):
+class RSAPublicKey(key.CryptoKey, key.Encryptor, key.Verifier):
   """RSA (Rivest-Shamir-Adleman) key, with the public part of the key.
 
   No measures are taken here to prevent timing attacks.
@@ -48,7 +49,7 @@ class RSAPublicKey(base.CryptoKey, base.Encryptor, base.Verifier):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     if self.public_modulus < 6 or modmath.IsPrime(self.public_modulus):  # noqa: PLR2004
@@ -92,7 +93,7 @@ class RSAPublicKey(base.CryptoKey, base.Encryptor, base.Verifier):
       ciphertext message (int, 1 ≤ c < modulus) = (m ** encrypt_exp) mod modulus
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -128,13 +129,13 @@ class RSAPublicKey(base.CryptoKey, base.Encryptor, base.Verifier):
     """
     # generate random r and encrypt it
     r: int = 0
-    while not 1 < r < self.public_modulus or base.GCD(r, self.public_modulus) != 1:
-      r = base.RandBits(self.public_modulus.bit_length())
+    while not 1 < r < self.public_modulus or modmath.GCD(r, self.public_modulus) != 1:
+      r = saferandom.RandBits(self.public_modulus.bit_length())
     k: int = self.modulus_size
     ct: bytes = base.IntToFixedBytes(self.RawEncrypt(r), k)
     assert len(ct) == k, 'should never happen: c_kem should be exactly k bytes'  # noqa: S101
     # encrypt plaintext with AES-256-GCM using SHA512(r)[32:] as key; return ct || Encrypt(...)
-    ss: bytes = base.Hash512(base.IntToFixedBytes(r, k))
+    ss: bytes = hashes.Hash512(base.IntToFixedBytes(r, k))
     aad: bytes = b'' if associated_data is None else associated_data
     aad_prime: bytes = _RSA_ENCRYPTION_AAD_PREFIX + base.IntToFixedBytes(len(aad), 8) + aad + ct
     return ct + aes.AESKey(key256=ss[32:]).Encrypt(plaintext, associated_data=aad_prime)
@@ -172,16 +173,16 @@ class RSAPublicKey(base.CryptoKey, base.Encryptor, base.Verifier):
       Hash512("prefix" || len(aad) || aad || message || salt)
 
     Raises:
-      CryptoError: hash output is out of range
+      key.CryptoError: hash output is out of range
 
     """
     aad: bytes = b'' if associated_data is None else associated_data
     la: bytes = base.IntToFixedBytes(len(aad), 8)
     assert len(salt) == 64, 'should never happen: salt should be exactly 64 bytes'  # noqa: PLR2004, S101
-    y: int = base.BytesToInt(base.Hash512(_RSA_SIGNATURE_HASH_PREFIX + la + aad + message + salt))
-    if not 1 < y < self.public_modulus or base.GCD(y, self.public_modulus) != 1:
+    y: int = base.BytesToInt(hashes.Hash512(_RSA_SIGNATURE_HASH_PREFIX + la + aad + message + salt))
+    if not 1 < y < self.public_modulus or modmath.GCD(y, self.public_modulus) != 1:
       # will only reasonably happen if modulus is small
-      raise base.CryptoError(f'hash output {y} is out of range/invalid {self.public_modulus}')
+      raise key.CryptoError(f'hash output {y} is out of range/invalid {self.public_modulus}')
     return y
 
   def Verify(
@@ -204,7 +205,7 @@ class RSAPublicKey(base.CryptoKey, base.Encryptor, base.Verifier):
       True if signature is valid, False otherwise
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     k: int = self.modulus_size
@@ -257,8 +258,8 @@ class RSAObfuscationPair(RSAPublicKey):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
-      CryptoError: modulus math is inconsistent with values
+      base.InputError: invalid inputs
+      key.CryptoError: modulus math is inconsistent with values
 
     """
     super(RSAObfuscationPair, self).__post_init__()
@@ -269,7 +270,7 @@ class RSAObfuscationPair(RSAPublicKey):
     ):
       raise base.InputError(f'invalid keys: {self}')
     if (self.random_key * self.key_inverse) % self.public_modulus != 1:
-      raise base.CryptoError(f'inconsistent keys: {self}')
+      raise key.CryptoError(f'inconsistent keys: {self}')
 
   def __str__(self) -> str:
     """Safe (no secrets) string representation of the RSAObfuscationPair.
@@ -281,8 +282,8 @@ class RSAObfuscationPair(RSAPublicKey):
     return (
       'RSAObfuscationPair('
       f'{super(RSAObfuscationPair, self).__str__()}, '
-      f'random_key={base.ObfuscateSecret(self.random_key)}, '
-      f'key_inverse={base.ObfuscateSecret(self.key_inverse)})'
+      f'random_key={hashes.ObfuscateSecret(self.random_key)}, '
+      f'key_inverse={hashes.ObfuscateSecret(self.key_inverse)})'
     )
 
   def ObfuscateMessage(self, message: int, /) -> int:
@@ -297,7 +298,7 @@ class RSAObfuscationPair(RSAPublicKey):
       obfuscated message (int, 1 ≤ o < modulus) = (m * (random_key ** encrypt_exp)) mod modulus
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -322,31 +323,31 @@ class RSAObfuscationPair(RSAPublicKey):
       signature * key_inverse mod modulus
 
     Raises:
-      CryptoError: some signatures were invalid (either plain or obfuscated)
+      key.CryptoError: some signatures were invalid (either plain or obfuscated)
 
     """
     # verify that obfuscated signature is valid
     obfuscated: int = self.ObfuscateMessage(message)
     if not self.RawVerify(obfuscated, signature):
-      raise base.CryptoError(f'obfuscated message was not signed: {message=} ; {signature=}')
+      raise key.CryptoError(f'obfuscated message was not signed: {message=} ; {signature=}')
     # compute signature for original message and check it
     original: int = (signature * self.key_inverse) % self.public_modulus
     if not self.RawVerify(message, original):
-      raise base.CryptoError(f'failed signature recovery: {message=} ; {signature=}')
+      raise key.CryptoError(f'failed signature recovery: {message=} ; {signature=}')
     return original
 
   @classmethod
-  def New(cls, key: RSAPublicKey, /) -> Self:
-    """Generate new obfuscation pair for this `key`, respecting the size of the public modulus.
+  def New(cls, rsa_key: RSAPublicKey, /) -> Self:
+    """Generate new obfuscation pair for this `rsa_key`, respecting the size of the public modulus.
 
     Args:
-      key (RSAPublicKey): public RSA key to use as base for a new RSAObfuscationPair
+      rsa_key (RSAPublicKey): public RSA key to use as base for a new RSAObfuscationPair
 
     Returns:
       RSAObfuscationPair object ready for use
 
     Raises:
-      CryptoError: failed generation
+      key.CryptoError: failed generation
 
     """
     # find a suitable random key based on the bit_length
@@ -356,29 +357,29 @@ class RSAObfuscationPair(RSAPublicKey):
     while (
       not random_key
       or not key_inverse
-      or random_key in {key.encrypt_exp, key_inverse}
-      or key_inverse == key.encrypt_exp
+      or random_key in {rsa_key.encrypt_exp, key_inverse}
+      or key_inverse == rsa_key.encrypt_exp
     ):
-      random_key = base.RandBits(key.public_modulus.bit_length() - 1)
+      random_key = saferandom.RandBits(rsa_key.public_modulus.bit_length() - 1)
       try:
-        key_inverse = modmath.ModInv(random_key, key.public_modulus)
+        key_inverse = modmath.ModInv(random_key, rsa_key.public_modulus)
       except modmath.ModularDivideError as err:
         key_inverse = 0
         failures += 1
         if failures >= _MAX_KEY_GENERATION_FAILURES:
-          raise base.CryptoError(f'failed key generation {failures} times') from err
+          raise key.CryptoError(f'failed key generation {failures} times') from err
         logging.warning(err)
     # build object
     return cls(
-      public_modulus=key.public_modulus,
-      encrypt_exp=key.encrypt_exp,
+      public_modulus=rsa_key.public_modulus,
+      encrypt_exp=rsa_key.encrypt_exp,
       random_key=random_key,
       key_inverse=key_inverse,
     )
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
+class RSAPrivateKey(RSAPublicKey, key.Decryptor, key.Signer):
   """RSA (Rivest-Shamir-Adleman) private key.
 
   No measures are taken here to prevent timing attacks.
@@ -409,8 +410,8 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
-      CryptoError: modulus math is inconsistent with values
+      base.InputError: invalid inputs
+      key.CryptoError: modulus math is inconsistent with values
 
     """
     super(RSAPrivateKey, self).__post_init__()
@@ -438,15 +439,15 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
     if self.remainder_p < 2 or self.remainder_q < 2 or self.q_inverse_p < 2:  # noqa: PLR2004
       raise base.InputError(f'trivial remainder_p/remainder_q/q_inverse_p: {self}')
     if self.modulus_p * self.modulus_q != self.public_modulus:
-      raise base.CryptoError(f'inconsistent modulus_p * modulus_q: {self}')
+      raise key.CryptoError(f'inconsistent modulus_p * modulus_q: {self}')
     if (self.encrypt_exp * self.decrypt_exp) % phi != 1:
-      raise base.CryptoError(f'inconsistent exponents: {self}')
+      raise key.CryptoError(f'inconsistent exponents: {self}')
     if (
       self.remainder_p != self.decrypt_exp % (self.modulus_p - 1)
       or self.remainder_q != self.decrypt_exp % (self.modulus_q - 1)
       or (self.q_inverse_p * self.modulus_q) % self.modulus_p != 1
     ):
-      raise base.CryptoError(f'inconsistent speedup remainder_p/remainder_q/q_inverse_p: {self}')
+      raise key.CryptoError(f'inconsistent speedup remainder_p/remainder_q/q_inverse_p: {self}')
 
   def __str__(self) -> str:
     """Safe (no secrets) string representation of the RSAPrivateKey.
@@ -458,9 +459,9 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
     return (
       'RSAPrivateKey('
       f'{super(RSAPrivateKey, self).__str__()}, '
-      f'modulus_p={base.ObfuscateSecret(self.modulus_p)}, '
-      f'modulus_q={base.ObfuscateSecret(self.modulus_q)}, '
-      f'decrypt_exp={base.ObfuscateSecret(self.decrypt_exp)})'
+      f'modulus_p={hashes.ObfuscateSecret(self.modulus_p)}, '
+      f'modulus_q={hashes.ObfuscateSecret(self.modulus_q)}, '
+      f'decrypt_exp={hashes.ObfuscateSecret(self.decrypt_exp)})'
     )
 
   def RawDecrypt(self, ciphertext: int, /) -> int:
@@ -477,7 +478,7 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
       decrypted message (int, 1 ≤ m < modulus) = (m ** decrypt_exp) mod modulus
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -509,7 +510,7 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
       bytes: Decrypted plaintext bytes
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     k: int = self.modulus_size
@@ -518,7 +519,7 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
     # split ciphertext in two parts: the first k bytes is ct, the rest is AES-256-GCM
     rsa_ct, aes_ct = ciphertext[:k], ciphertext[k:]
     r: int = self.RawDecrypt(base.BytesToInt(rsa_ct))
-    ss: bytes = base.Hash512(base.IntToFixedBytes(r, k))
+    ss: bytes = hashes.Hash512(base.IntToFixedBytes(r, k))
     aad: bytes = b'' if associated_data is None else associated_data
     aad_prime: bytes = _RSA_ENCRYPTION_AAD_PREFIX + base.IntToFixedBytes(len(aad), 8) + aad + rsa_ct
     return aes.AESKey(key256=ss[32:]).Decrypt(aes_ct, associated_data=aad_prime)
@@ -538,7 +539,7 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
       identical to Decrypt()
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -569,13 +570,13 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
       bytes: Signature; salt || Padded(s, k) - see above
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     k: int = self.modulus_size
     if k <= 64:  # noqa: PLR2004
       raise base.InputError(f'modulus too small for signing operations: {k} bytes')
-    salt: bytes = base.RandBytes(64)
+    salt: bytes = saferandom.RandBytes(64)
     s_int: int = self.RawSign(self._DomainSeparatedHash(message, associated_data, salt))
     s_bytes: bytes = base.IntToFixedBytes(s_int, k)
     assert len(s_bytes) == k, 'should never happen: s_bytes should be exactly k bytes'  # noqa: S101
@@ -592,8 +593,8 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
       RSAPrivateKey object ready for use
 
     Raises:
-      InputError: invalid inputs
-      CryptoError: failed generation
+      base.InputError: invalid inputs
+      key.CryptoError: failed generation
 
     """
     # test inputs
@@ -632,5 +633,5 @@ class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):
       except (base.InputError, modmath.ModularDivideError) as err:
         failures += 1
         if failures >= _MAX_KEY_GENERATION_FAILURES:
-          raise base.CryptoError(f'failed key generation {failures} times') from err
+          raise key.CryptoError(f'failed key generation {failures} times') from err
         logging.warning(err)