transcrypto 1.1.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

transcrypto/aes.py

@@ -47,7 +47,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.SymmetricCrypto):
+class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
   """Advanced Encryption Standard (AES) 256 bits key (32 bytes).
 
   No measures are taken here to prevent timing attacks.
@@ -112,7 +112,7 @@ class AESKey(base.CryptoKey, base.SymmetricCrypto):
         salt=_PASSWORD_SALT_256, iterations=_PASSWORD_ITERATIONS)
     return cls(key256=kdf.derive(str_password.encode('utf-8')))
 
-  class ECBEncoderClass(base.SymmetricCrypto):
+  class ECBEncoderClass(base.Encryptor, base.Decryptor):
     """The simplest encryption possible (UNSAFE if misused): 128 bit block AES-ECB, 256 bit key.
 
     Please DO **NOT** use this for regular cryptography. For regular crypto use Encrypt()/Decrypt().
@@ -245,7 +245,8 @@ class AESKey(base.CryptoKey, base.SymmetricCrypto):
       InputError: invalid inputs
       CryptoError: internal crypto failures, authentication failure, key mismatch, etc
     """
-    assert len(ciphertext) >= 32, 'should never happen: AES256+GCM should have ≥32 bytes IV/CT/tag'
+    if len(ciphertext) < 32:
+      raise base.InputError(f'AES256+GCM should have ≥32 bytes IV/CT/tag: {len(ciphertext)}')
     iv, tag = ciphertext[:16], ciphertext[-16:]
     decryptor: ciphers.CipherContext = ciphers.Cipher(
         algorithms.AES256(self.key256), modes.GCM(iv, tag)).decryptor()

transcrypto/base.py

@@ -19,12 +19,11 @@ import pickle
 # import pdb
 import secrets
 import time
-from typing import Any, Callable, final, MutableSequence, Self, TypeVar
-
+from typing import Any, Callable, final, MutableSequence, Protocol, runtime_checkable, Self, TypeVar
 import zstandard
 
 __author__ = 'balparda@github.com'
-__version__ = '1.1.2'  # v1.1.2, 2025-08-29
+__version__ = '1.3.0'  # 2025-09-07, Sun
 __version_tuple__: tuple[int, ...] = tuple(int(v) for v in __version__.split('.'))
 
 # MIN_TM = int(  # minimum allowed timestamp
@@ -35,8 +34,8 @@ BytesToInt: Callable[[bytes], int] = lambda b: int.from_bytes(b, 'big', signed=F
 BytesToEncoded: Callable[[bytes], str] = lambda b: base64.urlsafe_b64encode(b).decode('ascii')
 
 HexToBytes: Callable[[str], bytes] = bytes.fromhex
-IntToBytes: Callable[[int], bytes] = lambda i: i.to_bytes(
-    (i.bit_length() + 7) // 8, 'big', signed=False)
+IntToFixedBytes: Callable[[int, int], bytes] = lambda i, n: i.to_bytes(n, 'big', signed=False)
+IntToBytes: Callable[[int], bytes] = lambda i: IntToFixedBytes(i, (i.bit_length() + 7) // 8)
 IntToEncoded: Callable[[int], str] = lambda i: BytesToEncoded(IntToBytes(i))
 EncodedToBytes: Callable[[str], bytes] = lambda e: base64.urlsafe_b64decode(e.encode('ascii'))
 
@@ -46,7 +45,7 @@ PadBytesTo: Callable[[bytes, int], bytes] = lambda b, i: b.rjust((i + 7) // 8, b
 # these control the pickling of data, do NOT ever change, or you will break all databases
 # <https://docs.python.org/3/library/pickle.html#pickle.DEFAULT_PROTOCOL>
 _PICKLE_PROTOCOL = 4  # protocol 4 available since python v3.8 # do NOT ever change!
-_PICKLE_AAD = b'transcrypto.base.Serialize'  # do NOT ever change!
+_PICKLE_AAD = b'transcrypto.base.Serialize.1.0'  # do NOT ever change!
 # these help find compressed files, do NOT change unless zstandard changes
 _ZSTD_MAGIC_FRAME = 0xFD2FB528
 _ZSTD_MAGIC_SKIPPABLE_MIN = 0x184D2A50
@@ -646,11 +645,11 @@ class CryptoKey(abc.ABC):
     return BytesToEncoded(self.blob)
 
   @final
-  def Blob(self, /, *, key: SymmetricCrypto | None = None, silent: bool = True) -> bytes:
+  def Blob(self, /, *, key: Encryptor | None = None, silent: bool = True) -> bytes:
     """Serial (bytes) representation of the object with more options, including encryption.
 
     Args:
-      key (SymmetricCrypto, optional): if given will key.Encrypt() data before saving
+      key (Encryptor, optional): if given will key.Encrypt() data before saving
       silent (bool, optional): if True (default) will not log
 
     Returns:
@@ -659,11 +658,11 @@ class CryptoKey(abc.ABC):
     return Serialize(self, compress=-2, key=key, silent=silent)
 
   @final
-  def Encoded(self, /, *, key: SymmetricCrypto | None = None, silent: bool = True) -> str:
+  def Encoded(self, /, *, key: Encryptor | None = None, silent: bool = True) -> str:
     """Base-64 representation of the object with more options, including encryption.
 
     Args:
-      key (SymmetricCrypto, optional): if given will key.Encrypt() data before saving
+      key (Encryptor, optional): if given will key.Encrypt() data before saving
       silent (bool, optional): if True (default) will not log
 
     Returns:
@@ -674,14 +673,13 @@ class CryptoKey(abc.ABC):
   @final
   @classmethod
   def Load(
-      cls, data: str | bytes, /, *,
-      key: SymmetricCrypto | None = None, silent: bool = True) -> Self:
+      cls, data: str | bytes, /, *, key: Decryptor | None = None, silent: bool = True) -> Self:
     """Load (create) object from serialized bytes or string.
 
     Args:
       data (str | bytes): if bytes is assumed from CryptoKey.blob/Blob(), and
           if string is assumed from CryptoKey.encoded/Encoded()
-      key (SymmetricCrypto, optional): if given will key.Encrypt() data before saving
+      key (Decryptor, optional): if given will key.Encrypt() data before saving
       silent (bool, optional): if True (default) will not log
 
     Returns:
@@ -698,20 +696,21 @@ class CryptoKey(abc.ABC):
     return obj  # type:ignore
 
 
-class SymmetricCrypto(abc.ABC):
-  """Abstract interface for symmetric encryption.
+@runtime_checkable
+class Encryptor(Protocol):  # pylint: disable=too-few-public-methods
+  """Abstract interface for a class that has encryption
 
   Contract:
     - If algorithm accepts a `nonce` or `tag` these have to be handled internally by the
-      implementation and appended to the ciphertext.
+      implementation and appended to the `ciphertext`/`signature`.
     - If AEAD is supported, `associated_data` (AAD) must be authenticated. If not supported
       then `associated_data` different from None must raise InputError.
 
   Notes:
     The interface is deliberately minimal: byte-in / byte-out.
     Metadata like nonce/tag may be:
-      - returned alongside ciphertext, or
-      - bundled/serialized into `ciphertext` by the implementation.
+      - returned alongside `ciphertext`/`signature`, or
+      - bundled/serialized into `ciphertext`/`signature` by the implementation.
   """
 
   @abc.abstractmethod
@@ -732,6 +731,11 @@ class SymmetricCrypto(abc.ABC):
       CryptoError: internal crypto failures
     """
 
+
+@runtime_checkable
+class Decryptor(Protocol):  # pylint: disable=too-few-public-methods
+  """Abstract interface for a class that has decryption (see contract/notes in Encryptor)."""
+
   @abc.abstractmethod
   def Decrypt(self, ciphertext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
     """Decrypt `ciphertext` and return the original `plaintext`.
@@ -749,9 +753,55 @@ class SymmetricCrypto(abc.ABC):
     """
 
 
+@runtime_checkable
+class Verifier(Protocol):  # pylint: disable=too-few-public-methods
+  """Abstract interface for asymmetric signature verify. (see contract/notes in Encryptor)."""
+
+  @abc.abstractmethod
+  def Verify(
+      self, message: bytes, signature: bytes, /, *, associated_data: bytes | None = None) -> bool:
+    """Verify a `signature` for `message`. True if OK; False if failed verification.
+
+    Args:
+      message (bytes): Data that was signed (including any embedded nonce/tag if applicable)
+      signature (bytes): Signature data to verify (including any embedded nonce/tag if applicable)
+      associated_data (bytes, optional): Optional AAD (must match what was used during signing)
+
+    Returns:
+      True if signature is valid, False otherwise
+
+    Raises:
+      InputError: invalid inputs
+      CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+    """
+
+
+@runtime_checkable
+class Signer(Protocol):  # pylint: disable=too-few-public-methods
+  """Abstract interface for asymmetric signing. (see contract/notes in Encryptor)."""
+
+  @abc.abstractmethod
+  def Sign(self, message: bytes, /, *, associated_data: bytes | None = None) -> bytes:
+    """Sign `message` and return the `signature`.
+
+    Args:
+      message (bytes): Data to sign.
+      associated_data (bytes, optional): Optional AAD for AEAD modes; must be
+          provided again on decrypt
+
+    Returns:
+      bytes: Signature; if a nonce/tag is needed for decryption, the implementation
+      must encode it within the returned bytes (or document how to retrieve it)
+
+    Raises:
+      InputError: invalid inputs
+      CryptoError: internal crypto failures
+    """
+
+
 def Serialize(
     python_obj: Any, /, *, file_path: str | None = None,
-    compress: int | None = 3, key: SymmetricCrypto | None = None, silent: bool = False) -> bytes:
+    compress: int | None = 3, key: Encryptor | None = None, silent: bool = False) -> bytes:
   """Serialize a Python object into a BLOB, optionally compress / encrypt / save to disk.
 
   Data path is:
@@ -777,7 +827,7 @@ def Serialize(
     file_path (str, optional): full path to optionally save the data to
     compress (int | None, optional): Compress level before encrypting/saving; -22 ≤ compress ≤ 22;
         None is no compression; default is 3, which is fast, see table above for other values
-    key (SymmetricCrypto, optional): if given will key.Encrypt() data before saving
+    key (Encryptor, optional): if given will key.Encrypt() data before saving
     silent (bool, optional): if True will not log; default is False (will log)
 
   Returns:
@@ -819,7 +869,7 @@ def Serialize(
 
 def DeSerialize(
     *, data: bytes | None = None, file_path: str | None = None,
-    key: SymmetricCrypto | None = None, silent: bool = False) -> Any:
+    key: Decryptor | None = None, silent: bool = False) -> Any:
   """Loads (de-serializes) a BLOB back to a Python object, optionally decrypting / decompressing.
 
   Data path is:
@@ -835,7 +885,7 @@ def DeSerialize(
        if you use this option, `file_path` will be ignored
     file_path (str, optional): if given, use this as file path to load binary data string (input);
        if you use this option, `data` will be ignored
-    key (SymmetricCrypto, optional): if given will key.Decrypt() data before decompressing/loading
+    key (Decryptor, optional): if given will key.Decrypt() data before decompressing/loading
     silent (bool, optional): if True will not log; default is False (will log)
 
   Returns:
@@ -893,7 +943,7 @@ def DeSerialize(
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class PublicBid(CryptoKey):
+class PublicBid512(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)
@@ -901,6 +951,8 @@ class PublicBid(CryptoKey):
   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)
@@ -915,7 +967,7 @@ class PublicBid(CryptoKey):
     Raises:
       InputError: invalid inputs
     """
-    super(PublicBid, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
+    super(PublicBid512, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
     if len(self.public_key) != 64 or len(self.public_hash) != 64:
       raise InputError(f'invalid public_key or public_hash: {self}')
 
@@ -925,7 +977,8 @@ class PublicBid(CryptoKey):
     Returns:
       string representation of PublicBid
     """
-    return (f'PublicBid(public_key={BytesToEncoded(self.public_key)}, '
+    return ('PublicBid512('
+            f'public_key={BytesToEncoded(self.public_key)}, '
             f'public_hash={BytesToHex(self.public_hash)})')
 
   def VerifyBid(self, private_key: bytes, secret: bytes, /) -> bool:
@@ -943,7 +996,7 @@ class PublicBid(CryptoKey):
     """
     try:
       # creating the PrivateBid object will validate everything; InputError we allow to propagate
-      PrivateBid(
+      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
@@ -951,13 +1004,13 @@ class PublicBid(CryptoKey):
       return False  # bid does not match the public commitment
 
   @classmethod
-  def Copy(cls, other: PublicBid, /) -> Self:
+  def Copy(cls, other: PublicBid512, /) -> Self:
     """Initialize a public bid by taking the public parts of a public/private bid."""
     return cls(public_key=other.public_key, public_hash=other.public_hash)
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class PrivateBid(PublicBid):
+class PrivateBid512(PublicBid512):
   """Private bid that can be revealed and validated against a public commitment (see PublicBid).
 
   Attributes:
@@ -975,7 +1028,7 @@ class PrivateBid(PublicBid):
       InputError: invalid inputs
       CryptoError: bid does not match the public commitment
     """
-    super(PrivateBid, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
+    super(PrivateBid512, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
     if len(self.private_key) != 64 or len(self.secret_bid) < 1:
       raise InputError(f'invalid private_key or secret_bid: {self}')
     if self.public_hash != Hash512(self.public_key + self.private_key + self.secret_bid):
@@ -987,7 +1040,8 @@ class PrivateBid(PublicBid):
     Returns:
       string representation of PrivateBid without leaking secrets
     """
-    return (f'PrivateBid({super(PrivateBid, self).__str__()}, '  # pylint: disable=super-with-arguments
+    return ('PrivateBid512('
+            f'{super(PrivateBid512, self).__str__()}, '  # pylint: disable=super-with-arguments
             f'private_key={ObfuscateSecret(self.private_key)}, '
             f'secret_bid={ObfuscateSecret(self.secret_bid)})')