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

transcrypto/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Basic cryptography primitives implementation."""
+
+__all__: list[str] = ['__author__', '__version__']
+__version__ = '1.8.0'  # remember to also update pyproject.toml
+__author__ = 'Daniel Balparda <balparda@github.com>'

transcrypto/aes.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python3
-#
-# Copyright 2025 Daniel Balparda (balparda@github.com) - Apache-2.0 license
-#
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
 """Balparda's TransCrypto Advanced Encryption Standard (AES) library.
 
 <https://en.wikipedia.org/wiki/Advanced_Encryption_Standard>
@@ -19,31 +17,27 @@ wrappers, consistent with the transcrypto style.
 from __future__ import annotations
 
 import dataclasses
-# import datetime
-# import pdb
-from typing import Self
+from typing import Self, cast
 
+from cryptography import exceptions as crypt_exceptions
 from cryptography.hazmat.primitives import ciphers
-from cryptography.hazmat.primitives.ciphers import algorithms, modes
 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 cryptography import exceptions as crypt_exceptions
 
 from . import base
 
-__author__ = 'balparda@github.com'
-__version__: str = base.__version__  # version comes from base!
-__version_tuple__: tuple[int, ...] = base.__version_tuple__
-
-
 # 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
 # keys will change and previous databases/encryptions will become inconsistent/unreadable!
 _PASSWORD_SALT_256: bytes = base.HexToBytes(
-    '63b56fe9260ed3ff752a86a3414e4358e4d8e3e31b9dbc16e11ec19809e2f3c0')  # fixed random salt: do NOT ever change!
+  '63b56fe9260ed3ff752a86a3414e4358e4d8e3e31b9dbc16e11ec19809e2f3c0'
+)  # fixed random salt: do NOT ever change!
 _PASSWORD_ITERATIONS = 2025103  # fixed iterations, purposefully huge: do NOT ever change!
-assert base.BytesToEncoded(_PASSWORD_SALT_256) == 'Y7Vv6SYO0_91KoajQU5DWOTY4-MbnbwW4R7BmAni88A=', 'should never happen: constant'
-assert _PASSWORD_ITERATIONS == (6075308 + 1) // 3, 'should never happen: constant'
+assert base.BytesToEncoded(_PASSWORD_SALT_256) == 'Y7Vv6SYO0_91KoajQU5DWOTY4-MbnbwW4R7BmAni88A=', (  # noqa: S101
+  'should never happen: constant'
+)
+assert _PASSWORD_ITERATIONS == (6075308 + 1) // 3, 'should never happen: constant'  # noqa: S101
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
@@ -54,6 +48,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
 
   Attributes:
     key256 (bytes): AES 256 bits key (32 bytes), so length is always 32
+
   """
 
   key256: bytes
@@ -63,9 +58,9 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
 
     Raises:
       InputError: invalid inputs
+
     """
-    super(AESKey, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
-    if len(self.key256) != 32:
+    if len(self.key256) != 32:  # noqa: PLR2004
       raise base.InputError(f'invalid key256: {self}')
 
   def __str__(self) -> str:
@@ -73,6 +68,7 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
 
     Returns:
       string representation of AESKey without leaking secrets
+
     """
     return f'AESKey(key256={base.ObfuscateSecret(self.key256)})'
 
@@ -102,38 +98,59 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       AESKey crypto key to use (URL-safe base64-encoded 32-byte key)
 
     Raises:
-      Error: empty password
+      InputError: empty password
+
     """
     str_password = str_password.strip()
     if not str_password:
       raise base.InputError('empty passwords not allowed, for safety reasons')
     kdf = hazmat_pbkdf2.PBKDF2HMAC(
-        algorithm=hazmat_hashes.SHA256(), length=32,
-        salt=_PASSWORD_SALT_256, iterations=_PASSWORD_ITERATIONS)
+      algorithm=hazmat_hashes.SHA256(),
+      length=32,
+      salt=_PASSWORD_SALT_256,
+      iterations=_PASSWORD_ITERATIONS,
+    )
     return cls(key256=kdf.derive(str_password.encode('utf-8')))
 
   class ECBEncoderClass(base.Encryptor, base.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,
+    like hashes for example.
+
     Please DO **NOT** use this for regular cryptography. For regular crypto use Encrypt()/Decrypt().
     This class was specifically built to encode/decode 128 bit / 16 bytes blocks using a
     pre-existing key. No measures are taken here to prevent timing attacks.
     """
 
     def __init__(self, key256: AESKey, /) -> None:
-      """Constructor.
+      """Construct.
 
       Args:
         key256 (AESKey): key
+
       """
       self._cipher: ciphers.Cipher[modes.ECB] = ciphers.Cipher(
-          algorithms.AES256(key256.key256), modes.ECB())
-      assert self._cipher.algorithm.key_size == 256, 'should never happen: AES256+ECB should have 256 bits key'
-      assert self._cipher.algorithm.block_size == 128, 'should never happen: AES256+ECB should have 128 bits block'  # type:ignore
+        algorithms.AES256(key256.key256),
+        modes.ECB(),  # noqa: S305
+      )
+      alg: ciphers.BlockCipherAlgorithm = cast(
+        'algorithms.BlockCipherAlgorithm',  # type: ignore
+        self._cipher.algorithm,
+      )
+      assert alg.key_size == 256, (  # noqa: PLR2004, S101
+        'should never happen: AES256+ECB should have 256 bits key'
+      )
+      assert alg.block_size == 128, (  # noqa: PLR2004, S101
+        'should never happen: AES256+ECB should have 128 bits block'
+      )
 
     def Encrypt(self, plaintext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
       """Encrypt a 128 bits block (16 bytes) `plaintext` and return `ciphertext` of 128 bits.
 
+      Note: Due to ECB encoding, this method is only safe-ish for blocks of random-looking data,
+      like hashes for example.
+
       Please DO **NOT** use this for regular cryptography.
       No measures are taken here to prevent timing attacks.
 
@@ -146,10 +163,11 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
 
       Raises:
         InputError: invalid inputs
+
       """
       if associated_data is not None:
         raise base.InputError('AES/ECB does not support associated_data')
-      if len(plaintext) != 16:
+      if len(plaintext) != 16:  # noqa: PLR2004
         raise base.InputError(f'plaintext must be 16 bytes long, got {len(plaintext)}')
       encryptor: ciphers.CipherContext = self._cipher.encryptor()
       return encryptor.update(plaintext) + encryptor.finalize()
@@ -157,6 +175,9 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     def Decrypt(self, ciphertext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
       """Decrypt a 128 bits block (16 bytes) `ciphertext` and return original 128 bits `plaintext`.
 
+      Note: Due to ECB encoding, this method is only safe-ish for blocks of random-looking data,
+      like hashes for example.
+
       Please DO **NOT** use this for regular cryptography.
       No measures are taken here to prevent timing attacks.
 
@@ -169,32 +190,92 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
 
       Raises:
         InputError: invalid inputs
+
       """
       if associated_data is not None:
         raise base.InputError('AES/ECB does not support associated_data')
-      if len(ciphertext) != 16:
+      if len(ciphertext) != 16:  # noqa: PLR2004
         raise base.InputError(f'ciphertext must be 16 bytes long, got {len(ciphertext)}')
       decryptor: ciphers.CipherContext = self._cipher.decryptor()
       return decryptor.update(ciphertext) + decryptor.finalize()
 
     def EncryptHex(self, plaintext_hex: str, /) -> str:
-      """Encrypt a 128 bits hexadecimal block, outputting also a 128 bits hexadecimal block."""
+      """Encrypt a 128 bits hexadecimal block, outputting also a 128 bits hexadecimal block.
+
+      Note: Due to ECB encoding, this method is only safe-ish for blocks of random-looking data,
+      like hashes for example.
+
+      Args:
+          plaintext_hex (str): plaintext hexadecimal block (length==32)
+
+      Returns:
+          str: encrypted hexadecimal block (length==32)
+
+      """
       return base.BytesToHex(self.Encrypt(base.HexToBytes(plaintext_hex)))
 
     def EncryptHex256(self, plaintext_hex: str, /) -> str:
-      """Encrypt a 256 bits hexadecimal block, outputting also a 256 bits hexadecimal block."""
+      """Encrypt a 256 bits hexadecimal block, outputting also a 256 bits hexadecimal block.
+
+      Note: Due to ECB encoding, this method is only safe-ish for blocks of random-looking data,
+      like hashes for example.
+
+      Args:
+          plaintext_hex (str): plaintext hexadecimal block (length==64)
+
+      Returns:
+          str: encrypted hexadecimal block (length==64)
+
+      Raises:
+          InputError: invalid inputs
+
+      """
+      if len(plaintext_hex) != 64:  # noqa: PLR2004
+        raise base.InputError(f'plaintext_hex must be 64 chars long, got {len(plaintext_hex)}')
       return self.EncryptHex(plaintext_hex[:32]) + self.EncryptHex(plaintext_hex[32:])
 
     def DecryptHex(self, ciphertext_hex: str, /) -> str:
-      """Decrypt a 128 bits hexadecimal block, outputting also a 128 bits hexadecimal block."""
+      """Decrypt a 128 bits hexadecimal block, outputting also a 128 bits hexadecimal block.
+
+      Note: Due to ECB encoding, this method is only safe-ish for blocks of random-looking data,
+      like hashes for example.
+
+      Args:
+          ciphertext_hex (str): encrypted hexadecimal block (length==32)
+
+      Returns:
+          str: plaintext hexadecimal block (length==32)
+
+      """
       return base.BytesToHex(self.Decrypt(base.HexToBytes(ciphertext_hex)))
 
     def DecryptHex256(self, ciphertext_hex: str, /) -> str:
-      """Decrypt a 256 bits hexadecimal block, outputting also a 256 bits hexadecimal block."""
+      """Decrypt a 256 bits hexadecimal block, outputting also a 256 bits hexadecimal block.
+
+      Note: Due to ECB encoding, this method is only safe-ish for blocks of random-looking data,
+      like hashes for example.
+
+      Args:
+          ciphertext_hex (str): encrypted hexadecimal block (length==64)
+
+      Returns:
+          str: plaintext hexadecimal block (length==64)
+
+      Raises:
+          InputError: invalid inputs
+
+      """
+      if len(ciphertext_hex) != 64:  # noqa: PLR2004
+        raise base.InputError(f'ciphertext_hex must be 64 chars long, got {len(ciphertext_hex)}')
       return self.DecryptHex(ciphertext_hex[:32]) + self.DecryptHex(ciphertext_hex[32:])
 
   def ECBEncoder(self) -> AESKey.ECBEncoderClass:
-    """Return a AESKey.ECBEncoderClass object using this key."""
+    """Return a AESKey.ECBEncoderClass object using this key.
+
+    Returns:
+        AESKey.ECBEncoderClass: ECB encoder with same key as self
+
+    """
     return AESKey.ECBEncoderClass(self)
 
   def Encrypt(self, plaintext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
@@ -215,22 +296,30 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
       bytes: Ciphertext; 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
     """
     iv: bytes = base.RandBytes(16)
     cipher: ciphers.Cipher[modes.GCM] = ciphers.Cipher(
-        algorithms.AES256(self.key256), modes.GCM(iv))
-    assert cipher.algorithm.key_size == 256, 'should never happen: AES256+GCM should have 256 bits key'
-    assert cipher.algorithm.block_size == 128, 'should never happen: AES256+GCM should have 128 bits block'  # type:ignore
+      algorithms.AES256(self.key256), modes.GCM(iv)
+    )
+    alg: ciphers.BlockCipherAlgorithm = cast(
+      'algorithms.BlockCipherAlgorithm',  # type: ignore
+      cipher.algorithm,
+    )
+    assert alg.key_size == 256, (  # noqa: PLR2004, S101
+      'should never happen: AES256+GCM should have 256 bits key'
+    )
+    assert alg.block_size == 128, (  # noqa: PLR2004, S101
+      'should never happen: AES256+GCM should have 128 bits block'
+    )
     encryptor: ciphers.CipherContext = cipher.encryptor()
     if associated_data:
       encryptor.authenticate_additional_data(associated_data)  # type:ignore
-    ciphertext: bytes = encryptor.update(plaintext) + encryptor.finalize()  # GCM doesn't need padding
+    ciphertext: bytes = (
+      encryptor.update(plaintext) + encryptor.finalize()
+    )  # GCM doesn't need padding
     tag: bytes = encryptor.tag  # type:ignore
-    assert len(iv) == 16, 'should never happen: AES256+GCM should have 128 bits IV/nonce'
-    assert len(tag) == 16, 'should never happen: AES256+GCM should have 128 bits tag'
+    assert len(iv) == 16, 'should never happen: AES256+GCM should have 128 bits IV/nonce'  # noqa: PLR2004, S101
+    assert len(tag) == 16, 'should never happen: AES256+GCM should have 128 bits tag'  # noqa: PLR2004, S101
     return iv + ciphertext + tag
 
   def Decrypt(self, ciphertext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
@@ -252,15 +341,32 @@ class AESKey(base.CryptoKey, base.Encryptor, base.Decryptor):
     Raises:
       InputError: invalid inputs
       CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+
     """
-    if len(ciphertext) < 32:
+    if len(ciphertext) < 32:  # noqa: PLR2004
       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()
+      algorithms.AES256(self.key256), modes.GCM(iv, tag)
+    ).decryptor()
     if associated_data:
       decryptor.authenticate_additional_data(associated_data)  # type:ignore
     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