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

transcrypto/cli/publicalgos.py

@@ -4,10 +4,12 @@
 
 from __future__ import annotations
 
+import click
 import typer
 
-from transcrypto import dsa, elgamal, rsa, transcrypto
+from transcrypto import transcrypto
 from transcrypto.cli import clibase
+from transcrypto.core import dsa, elgamal, rsa
 
 # ================================== "RSA" COMMAND =================================================
 
@@ -42,7 +44,7 @@ transcrypto.app.add_typer(rsa_app, name='rsa')
 @clibase.CLIErrorGuard
 def RSANew(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   bits: int = typer.Option(
     3332,
     '-b',
@@ -74,7 +76,7 @@ def RSANew(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSARawEncrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Integer message to encrypt, 1≤`message`<*modulus*'),
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
@@ -101,7 +103,7 @@ def RSARawEncrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSARawDecrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   ciphertext: str = typer.Argument(
     ..., help='Integer ciphertext to decrypt, 1≤`ciphertext`<*modulus*'
   ),
@@ -125,7 +127,7 @@ def RSARawDecrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSARawSign(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Integer message to sign, 1≤`message`<*modulus*'),
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
@@ -152,7 +154,7 @@ def RSARawSign(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSARawVerify(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(
     ..., help='Integer message that was signed earlier, 1≤`message`<*modulus*'
   ),
@@ -185,7 +187,7 @@ def RSARawVerify(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSAEncrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   plaintext: str = typer.Argument(..., help='Message to encrypt'),
   aad: str = typer.Option(
     '',
@@ -216,7 +218,7 @@ def RSAEncrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSADecrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   ciphertext: str = typer.Argument(..., help='Ciphertext to decrypt'),
   aad: str = typer.Option(
     '',
@@ -246,7 +248,7 @@ def RSADecrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSASign(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Message to sign'),
   aad: str = typer.Option(
     '',
@@ -280,7 +282,7 @@ def RSASign(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def RSAVerify(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Message that was signed earlier'),
   signature: str = typer.Argument(..., help='Putative signature for `message`'),
   aad: str = typer.Option(
@@ -338,7 +340,7 @@ transcrypto.app.add_typer(eg_app, name='elgamal')
 @clibase.CLIErrorGuard
 def ElGamalShared(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   bits: int = typer.Option(
     3332,
     '-b',
@@ -364,7 +366,7 @@ def ElGamalShared(  # documentation is help/epilog/args # noqa: D103
   ),
 )
 @clibase.CLIErrorGuard
-def ElGamalNew(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+def ElGamalNew(*, ctx: click.Context) -> None:  # documentation is help/epilog/args # noqa: D103
   config: transcrypto.TransConfig = ctx.obj
   base_path: str = transcrypto.RequireKeyPath(config, 'elgamal')
   shared_eg: elgamal.ElGamalSharedPublicKey = transcrypto.LoadObj(
@@ -392,7 +394,7 @@ def ElGamalNew(*, ctx: typer.Context) -> None:  # documentation is help/epilog/a
 @clibase.CLIErrorGuard
 def ElGamalRawEncrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Integer message to encrypt, 1≤`message`<*modulus*'),
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
@@ -423,7 +425,7 @@ def ElGamalRawEncrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def ElGamalRawDecrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   ciphertext: str = typer.Argument(
     ...,
     help=(
@@ -456,7 +458,7 @@ def ElGamalRawDecrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def ElGamalRawSign(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Integer message to sign, 1≤`message`<*modulus*'),
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
@@ -490,7 +492,7 @@ def ElGamalRawSign(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def ElGamalRawVerify(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(
     ..., help='Integer message that was signed earlier, 1≤`message`<*modulus*'
   ),
@@ -527,7 +529,7 @@ def ElGamalRawVerify(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def ElGamalEncrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   plaintext: str = typer.Argument(..., help='Message to encrypt'),
   aad: str = typer.Option(
     '',
@@ -560,7 +562,7 @@ def ElGamalEncrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def ElGamalDecrypt(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   ciphertext: str = typer.Argument(..., help='Ciphertext to decrypt'),
   aad: str = typer.Option(
     '',
@@ -592,7 +594,7 @@ def ElGamalDecrypt(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def ElGamalSign(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Message to sign'),
   aad: str = typer.Option(
     '',
@@ -628,7 +630,7 @@ def ElGamalSign(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def ElGamalVerify(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Message that was signed earlier'),
   signature: str = typer.Argument(..., help='Putative signature for `message`'),
   aad: str = typer.Option(
@@ -689,7 +691,7 @@ transcrypto.app.add_typer(dsa_app, name='dsa')
 @clibase.CLIErrorGuard
 def DSAShared(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   p_bits: int = typer.Option(
     4096,
     '-b',
@@ -725,7 +727,7 @@ def DSAShared(  # documentation is help/epilog/args # noqa: D103
   ),
 )
 @clibase.CLIErrorGuard
-def DSANew(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+def DSANew(*, ctx: click.Context) -> None:  # documentation is help/epilog/args # noqa: D103
   config: transcrypto.TransConfig = ctx.obj
   base_path: str = transcrypto.RequireKeyPath(config, 'dsa')
   dsa_shared: dsa.DSASharedPublicKey = transcrypto.LoadObj(
@@ -753,7 +755,7 @@ def DSANew(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args
 @clibase.CLIErrorGuard
 def DSARawSign(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Integer message to sign, 1≤`message`<`q`'),
 ) -> None:
   config: transcrypto.TransConfig = ctx.obj
@@ -784,7 +786,7 @@ def DSARawSign(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def DSARawVerify(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(
     ..., help='Integer message that was signed earlier, 1≤`message`<`q`'
   ),
@@ -821,7 +823,7 @@ def DSARawVerify(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def DSASign(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Message to sign'),
   aad: str = typer.Option(
     '',
@@ -855,7 +857,7 @@ def DSASign(  # documentation is help/epilog/args # noqa: D103
 @clibase.CLIErrorGuard
 def DSAVerify(  # documentation is help/epilog/args # noqa: D103
   *,
-  ctx: typer.Context,
+  ctx: click.Context,
   message: str = typer.Argument(..., help='Message that was signed earlier'),
   signature: str = typer.Argument(..., help='Putative signature for `message`'),
   aad: str = typer.Option(

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,
+    )