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

transcrypto/core/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Core crypto logic."""

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

@@ -25,7 +25,8 @@ from cryptography.hazmat.primitives import hashes as hazmat_hashes
 from cryptography.hazmat.primitives.ciphers import algorithms, modes
 from cryptography.hazmat.primitives.kdf import pbkdf2 as hazmat_pbkdf2
 
-from . import base
+from transcrypto.core import hashes, key
+from transcrypto.utils import base, saferandom
 
 # these fixed salt/iterations are for password->key generation only; NEVER use them to
 # build a database of passwords because it would not be safe; NEVER change them or the
@@ -41,7 +42,7 @@ assert _PASSWORD_ITERATIONS == (6075308 + 1) // 3, 'should never happen: constan
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
+class AESKey(key.CryptoKey, key.Encryptor, key.Decryptor):
   """Advanced Encryption Standard (AES) 256 bits key (32 bytes).
 
   No measures are taken here to prevent timing attacks.
@@ -57,7 +58,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     if len(self.key256) != 32:  # noqa: PLR2004
@@ -70,7 +71,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       string representation of AESKey without leaking secrets
 
     """
-    return f'AESKey(key256={base.ObfuscateSecret(self.key256)})'
+    return f'AESKey(key256={hashes.ObfuscateSecret(self.key256)})'
 
   @classmethod
   def FromStaticPassword(cls, str_password: str, /) -> Self:
@@ -98,7 +99,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       AESKey crypto key to use (URL-safe base64-encoded 32-byte key)
 
     Raises:
-      InputError: empty password
+      base.InputError: empty password
 
     """
     str_password = str_password.strip()
@@ -112,7 +113,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     )
     return cls(key256=kdf.derive(str_password.encode('utf-8')))
 
-  class ECBEncoderClass(base.Encryptor, base.Decryptor):
+  class ECBEncoderClass(key.Encryptor, key.Decryptor):
     """The simplest encryption possible (UNSAFE if misused): 128 bit block AES-ECB, 256 bit key.
 
     Note: Due to ECB encoding, this class is only safe-ish for blocks of random-looking data,
@@ -162,7 +163,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
         bytes: Ciphertext, a block of 128 bits (16 bytes)
 
       Raises:
-        InputError: invalid inputs
+        base.InputError: invalid inputs
 
       """
       if associated_data is not None:
@@ -189,7 +190,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
         bytes: Decrypted plaintext, a block of 128 bits (16 bytes)
 
       Raises:
-        InputError: invalid inputs
+        base.InputError: invalid inputs
 
       """
       if associated_data is not None:
@@ -227,7 +228,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
           str: encrypted hexadecimal block (length==64)
 
       Raises:
-          InputError: invalid inputs
+          base.InputError: invalid inputs
 
       """
       if len(plaintext_hex) != 64:  # noqa: PLR2004
@@ -262,7 +263,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
           str: plaintext hexadecimal block (length==64)
 
       Raises:
-          InputError: invalid inputs
+          base.InputError: invalid inputs
 
       """
       if len(ciphertext_hex) != 64:  # noqa: PLR2004
@@ -297,7 +298,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       must encode it within the returned bytes (or document how to retrieve it)
 
     """
-    iv: bytes = base.RandBytes(16)
+    iv: bytes = saferandom.RandBytes(16)
     cipher: ciphers.Cipher[modes.GCM] = ciphers.Cipher(
       algorithms.AES256(self.key256), modes.GCM(iv)
     )
@@ -339,12 +340,14 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       bytes: Decrypted plaintext bytes
 
     Raises:
-      InputError: invalid inputs
-      CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+      base.InputError: invalid inputs
+      key.CryptoError: internal crypto failures, authentication failure, key mismatch, etc
 
     """
     if len(ciphertext) < 32:  # noqa: PLR2004
       raise base.InputError(f'AES256+GCM should have ≥32 bytes IV/CT/tag: {len(ciphertext)}')
+    iv: bytes
+    tag: bytes
     iv, tag = ciphertext[:16], ciphertext[-16:]
     decryptor: ciphers.CipherContext = ciphers.Cipher(
       algorithms.AES256(self.key256), modes.GCM(iv, tag)
@@ -354,19 +357,4 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     try:
       return decryptor.update(ciphertext[16:-16]) + decryptor.finalize()
     except crypt_exceptions.InvalidTag as err:
-      raise base.CryptoError('failed decryption') from err
-
-
-def _TestCryptoKeyEncoding(obj: base.CryptoKey, tp: type[base.CryptoKey]) -> None:  # pyright: ignore[reportUnusedFunction]
-  """Test encoding for a CryptoKey instance. Only for use from test modules."""
-  assert tp.FromJSON(obj.json) == obj  # noqa: S101
-  assert tp.FromJSON(obj.formatted_json) == obj  # noqa: S101
-  assert tp.Load(obj.blob) == obj  # noqa: S101
-  assert tp.Load(obj.encoded) == obj  # noqa: S101
-  assert tp.Load(obj.hex) == obj  # noqa: S101
-  assert tp.Load(obj.raw) == obj  # noqa: S101
-  key = AESKey(key256=b'x' * 32)
-  assert tp.Load(obj.Blob(key=key), key=key) == obj  # noqa: S101
-  assert tp.Load(obj.Encoded(key=key), key=key) == obj  # noqa: S101
-  assert tp.Load(obj.Hex(key=key), key=key) == obj  # noqa: S101
-  assert tp.Load(obj.Raw(key=key), key=key) == obj  # noqa: S101
+      raise key.CryptoError('failed decryption') from err

transcrypto/core/bid.py

@@ -0,0 +1,161 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's TransCrypto bidding protocols."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Self
+
+from transcrypto.core import hashes, key
+from transcrypto.utils import base, saferandom
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
+class PublicBid512(key.CryptoKey):
+  """Public commitment to a (cryptographically secure) bid that can be revealed/validated later.
+
+  Bid is computed as: public_hash = Hash512(public_key || private_key || secret_bid)
+
+  Everything is bytes. The public part is (public_key, public_hash) and the private
+  part is (private_key, secret_bid). The whole computation can be checked later.
+
+  No measures are taken here to prevent timing attacks (probably not a concern).
+
+  Attributes:
+    public_key (bytes): 512-bits random value
+    public_hash (bytes): SHA-512 hash of (public_key || private_key || secret_bid)
+
+  """
+
+  public_key: bytes
+  public_hash: bytes
+
+  def __post_init__(self) -> None:
+    """Check data.
+
+    Raises:
+      base.InputError: invalid inputs
+
+    """
+    if len(self.public_key) != 64 or len(self.public_hash) != 64:  # noqa: PLR2004
+      raise base.InputError(f'invalid public_key or public_hash: {self}')
+
+  def __str__(self) -> str:
+    """Safe string representation of the PublicBid.
+
+    Returns:
+      string representation of PublicBid
+
+    """
+    return (
+      'PublicBid512('
+      f'public_key={base.BytesToEncoded(self.public_key)}, '
+      f'public_hash={base.BytesToHex(self.public_hash)})'
+    )
+
+  def VerifyBid(self, private_key: bytes, secret: bytes, /) -> bool:
+    """Verify a bid. True if OK; False if failed verification.
+
+    Args:
+      private_key (bytes): 512-bits private key
+      secret (bytes): Any number of bytes (≥1) to bid on (e.g., UTF-8 encoded string)
+
+    Returns:
+      True if bid is valid, False otherwise
+
+    """
+    try:
+      # creating the PrivateBid object will validate everything; InputError we allow to propagate
+      PrivateBid512(
+        public_key=self.public_key,
+        public_hash=self.public_hash,
+        private_key=private_key,
+        secret_bid=secret,
+      )
+      return True  # if we got here, all is good
+    except key.CryptoError:
+      return False  # bid does not match the public commitment
+
+  @classmethod
+  def Copy(cls, other: PublicBid512, /) -> Self:
+    """Initialize a public bid by taking the public parts of a public/private bid.
+
+    Args:
+        other (PublicBid512): the bid to copy from
+
+    Returns:
+        Self: an initialized PublicBid512
+
+    """
+    return cls(public_key=other.public_key, public_hash=other.public_hash)
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
+class PrivateBid512(PublicBid512):
+  """Private bid that can be revealed and validated against a public commitment (see PublicBid).
+
+  Attributes:
+    private_key (bytes): 512-bits random value
+    secret_bid (bytes): Any number of bytes (≥1) to bid on (e.g., UTF-8 encoded string)
+
+  """
+
+  private_key: bytes
+  secret_bid: bytes
+
+  def __post_init__(self) -> None:
+    """Check data.
+
+    Raises:
+      base.InputError: invalid inputs
+      key.CryptoError: bid does not match the public commitment
+
+    """
+    super(PrivateBid512, self).__post_init__()
+    if len(self.private_key) != 64 or len(self.secret_bid) < 1:  # noqa: PLR2004
+      raise base.InputError(f'invalid private_key or secret_bid: {self}')
+    if self.public_hash != hashes.Hash512(self.public_key + self.private_key + self.secret_bid):
+      raise key.CryptoError(f'inconsistent bid: {self}')
+
+  def __str__(self) -> str:
+    """Safe (no secrets) string representation of the PrivateBid.
+
+    Returns:
+      string representation of PrivateBid without leaking secrets
+
+    """
+    return (
+      'PrivateBid512('
+      f'{super(PrivateBid512, self).__str__()}, '
+      f'private_key={hashes.ObfuscateSecret(self.private_key)}, '
+      f'secret_bid={hashes.ObfuscateSecret(self.secret_bid)})'
+    )
+
+  @classmethod
+  def New(cls, secret: bytes, /) -> Self:
+    """Make the `secret` into a new bid.
+
+    Args:
+      secret (bytes): Any number of bytes (≥1) to bid on (e.g., UTF-8 encoded string)
+
+    Returns:
+      PrivateBid object ready for use (use PublicBid.Copy() to get the public part)
+
+    Raises:
+      base.InputError: invalid inputs
+
+    """
+    # test inputs
+    if len(secret) < 1:
+      raise base.InputError(f'invalid secret length: {len(secret)}')
+    # generate random values
+    public_key: bytes = saferandom.RandBytes(64)  # 512 bits
+    private_key: bytes = saferandom.RandBytes(64)  # 512 bits
+    # build object
+    return cls(
+      public_key=public_key,
+      public_hash=hashes.Hash512(public_key + private_key + secret),
+      private_key=private_key,
+      secret_bid=secret,
+    )

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

@@ -19,7 +19,8 @@ from typing import Self
 
 import gmpy2
 
-from . import base, constants, modmath
+from transcrypto.core import constants, hashes, key, modmath
+from transcrypto.utils import base, saferandom
 
 _MAX_KEY_GENERATION_FAILURES = 15
 
@@ -68,8 +69,8 @@ def NBitRandomDSAPrimes(
     that p % q == 1 and m == (p - 1) // q
 
   Raises:
-    InputError: invalid inputs
-    Error: prime search failed
+    base.InputError: invalid inputs
+    base.Error: prime search failed
 
   """
   # test inputs
@@ -140,7 +141,7 @@ def _PrimePSearchShard(q: int, p_bits: int) -> tuple[int | None, int | None]:
     return all(m % r != f for r, f in forbidden.items())
 
   # try searching starting here
-  m: int = base.RandInt(min_m, max_m)
+  m: int = saferandom.RandInt(min_m, max_m)
   if m % 2:
     m += 1  # make even
   count: int = 0
@@ -158,7 +159,7 @@ def _PrimePSearchShard(q: int, p_bits: int) -> tuple[int | None, int | None]:
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class DSASharedPublicKey(base.CryptoKey):
+class DSASharedPublicKey(key.CryptoKey):
   """DSA shared public key. This key can be shared by a group.
 
   No measures are taken here to prevent timing attacks.
@@ -178,7 +179,7 @@ class DSASharedPublicKey(base.CryptoKey):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     if self.prime_seed < 7 or not modmath.IsPrime(self.prime_seed):  # noqa: PLR2004
@@ -227,16 +228,16 @@ class DSASharedPublicKey(base.CryptoKey):
       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(_DSA_SIGNATURE_HASH_PREFIX + la + aad + message + salt))
+    y: int = base.BytesToInt(hashes.Hash512(_DSA_SIGNATURE_HASH_PREFIX + la + aad + message + salt))
     if not 1 < y < self.prime_seed - 1:
       # will only reasonably happen if prime seed is small
-      raise base.CryptoError(f'hash output {y} is out of range/invalid {self.prime_seed}')
+      raise key.CryptoError(f'hash output {y} is out of range/invalid {self.prime_seed}')
     return y
 
   @classmethod
@@ -257,13 +258,13 @@ class DSASharedPublicKey(base.CryptoKey):
     # generate random number, create object (should never fail)
     g: int = 0
     while g < 3:  # noqa: PLR2004
-      h: int = base.RandBits(p_bits - 1)
+      h: int = saferandom.RandBits(p_bits - 1)
       g = int(gmpy2.powmod(h, m, p))
     return cls(prime_modulus=p, prime_seed=q, group_base=g)
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class DSAPublicKey(DSASharedPublicKey, base.Verifier):
+class DSAPublicKey(DSASharedPublicKey, key.Verifier):
   """DSA public key. This is an individual public key.
 
   No measures are taken here to prevent timing attacks.
@@ -279,7 +280,7 @@ class DSAPublicKey(DSASharedPublicKey, base.Verifier):
     """Check data.
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     super(DSAPublicKey, self).__post_init__()
@@ -315,7 +316,7 @@ class DSAPublicKey(DSASharedPublicKey, base.Verifier):
       self.group_base,
       self.individual_base,
     }:
-      ephemeral_key = base.RandBits(bit_length - 1)
+      ephemeral_key = saferandom.RandBits(bit_length - 1)
     return (ephemeral_key, modmath.ModInv(ephemeral_key, self.prime_seed))
 
   def RawVerify(self, message: int, signature: tuple[int, int], /) -> bool:
@@ -333,7 +334,7 @@ class DSAPublicKey(DSASharedPublicKey, base.Verifier):
       True if signature is valid, False otherwise
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -371,7 +372,7 @@ class DSAPublicKey(DSASharedPublicKey, base.Verifier):
       True if signature is valid, False otherwise
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     k: int = self.modulus_size[1]  # use prime_seed size
@@ -409,7 +410,7 @@ class DSAPublicKey(DSASharedPublicKey, base.Verifier):
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class DSAPrivateKey(DSAPublicKey, base.Signer):
+class DSAPrivateKey(DSAPublicKey, key.Signer):
   """DSA private key.
 
   No measures are taken here to prevent timing attacks.
@@ -425,8 +426,8 @@ class DSAPrivateKey(DSAPublicKey, 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(DSAPrivateKey, self).__post_init__()
@@ -436,7 +437,7 @@ class DSAPrivateKey(DSAPublicKey, base.Signer):
     }:
       raise base.InputError(f'invalid decrypt_exp: {self}')
     if gmpy2.powmod(self.group_base, self.decrypt_exp, self.prime_modulus) != self.individual_base:
-      raise base.CryptoError(f'inconsistent g**d % p == i: {self}')
+      raise key.CryptoError(f'inconsistent g**d % p == i: {self}')
 
   def __str__(self) -> str:
     """Safe (no secrets) string representation of the DSAPrivateKey.
@@ -448,7 +449,7 @@ class DSAPrivateKey(DSAPublicKey, base.Signer):
     return (
       'DSAPrivateKey('
       f'{super(DSAPrivateKey, self).__str__()}, '
-      f'decrypt_exp={base.ObfuscateSecret(self.decrypt_exp)})'
+      f'decrypt_exp={hashes.ObfuscateSecret(self.decrypt_exp)})'
     )
 
   def RawSign(self, message: int, /) -> tuple[int, int]:
@@ -465,7 +466,7 @@ class DSAPrivateKey(DSAPublicKey, base.Signer):
       signed message tuple ((int, int), 2 ≤ s1,s2 < prime_seed
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     # test inputs
@@ -502,13 +503,13 @@ class DSAPrivateKey(DSAPublicKey, base.Signer):
       bytes: Signature; salt || Padded(s, k) - see above
 
     Raises:
-      InputError: invalid inputs
+      base.InputError: invalid inputs
 
     """
     k: int = self.modulus_size[1]  # use prime_seed size
     if k <= 64:  # noqa: PLR2004
       raise base.InputError(f'modulus/seed too small for signing operations: {k} bytes')
-    salt: bytes = base.RandBytes(64)
+    salt: bytes = saferandom.RandBytes(64)
     s_int: tuple[int, int] = self.RawSign(self._DomainSeparatedHash(message, associated_data, salt))
     s_bytes: bytes = base.IntToFixedBytes(s_int[0], k) + base.IntToFixedBytes(s_int[1], k)
     assert len(s_bytes) == 2 * k, 'should never happen: s_bytes should be exactly 2k bytes'  # noqa: S101
@@ -525,8 +526,8 @@ class DSAPrivateKey(DSAPublicKey, base.Signer):
       DSAPrivateKey object ready for use
 
     Raises:
-      InputError: invalid inputs
-      CryptoError: failed generation
+      base.InputError: invalid inputs
+      key.CryptoError: failed generation
 
     """
     # test inputs
@@ -542,7 +543,7 @@ class DSAPrivateKey(DSAPublicKey, base.Signer):
         while (
           not 2 < decrypt_exp < shared_key.prime_seed or decrypt_exp == shared_key.group_base  # noqa: PLR2004
         ):
-          decrypt_exp = base.RandBits(bit_length - 1)
+          decrypt_exp = saferandom.RandBits(bit_length - 1)
         # make the object
         return cls(
           prime_modulus=shared_key.prime_modulus,
@@ -556,5 +557,5 @@ class DSAPrivateKey(DSAPublicKey, base.Signer):
       except base.InputError 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)