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

transcrypto/rsa.py

@@ -14,8 +14,7 @@ import logging
 # import pdb
 from typing import Self
 
-from . import base
-from . import modmath
+from . import base, modmath, aes
 
 __author__ = 'balparda@github.com'
 __version__: str = base.__version__  # version comes from base!
@@ -27,13 +26,15 @@ _BIG_ENCRYPTION_EXPONENT = 2 ** 16 + 1  # 65537
 
 _MAX_KEY_GENERATION_FAILURES = 15
 
+# fixed prefixes: do NOT ever change! will break all encryption and signature schemes
+_RSA_ENCRYPTION_AAD_PREFIX = b'transcrypto.RSA.Encryption.1.0\x00'
+_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):
+class RSAPublicKey(base.CryptoKey, base.Encryptor, base.Verifier):
   """RSA (Rivest-Shamir-Adleman) key, with the public part of the key.
 
-  BEWARE: This is raw RSA, no OAEP or PSS padding or validation!
-  These are pedagogical/raw primitives; do not use for new protocols.
   No measures are taken here to prevent timing attacks.
 
   By default and deliberate choice the encryption exponent will be either 7 or 65537,
@@ -70,12 +71,20 @@ class RSAPublicKey(base.CryptoKey):
       string representation of RSAPublicKey
     """
     return ('RSAPublicKey('
+            f'bits={self.public_modulus.bit_length()}, '
             f'public_modulus={base.IntToEncoded(self.public_modulus)}, '
             f'encrypt_exp={base.IntToEncoded(self.encrypt_exp)})')
 
-  def Encrypt(self, message: int, /) -> int:
+  @property
+  def modulus_size(self) -> int:
+    """Modulus size in bytes. The number of bytes used in Encrypt/Decrypt/Sign/Verify."""
+    return (self.public_modulus.bit_length() + 7) // 8
+
+  def RawEncrypt(self, message: int, /) -> int:
     """Encrypt `message` with this public key.
 
+    BEWARE: This is raw RSA, no OAEP or PSS padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
     We explicitly disallow `message` to be zero.
 
     Args:
@@ -93,9 +102,52 @@ class RSAPublicKey(base.CryptoKey):
     # encrypt
     return modmath.ModExp(message, self.encrypt_exp, self.public_modulus)
 
-  def VerifySignature(self, message: int, signature: int, /) -> bool:
+  def Encrypt(self, plaintext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
+    """Encrypt `plaintext` and return `ciphertext`.
+
+    • Let k = ceil(log2(n))/8 be the modulus size in bytes.
+    • Pick random r ∈ [2, n-1]
+    • ct = r^e mod n
+    • return Padded(ct, k) + AES-256-GCM(key=SHA512(r)[32:], plaintext,
+                                         associated_data="prefix" + len(aad) + aad + Padded(ct, k))
+
+    We pick fresh random r, send ct = r^e mod n, and derive the DEM key from r,
+    then use AES-GCM for the payload. This is the classic RSA-KEM construction.
+    With AEAD as the DEM, we get strong confidentiality and ciphertext integrity
+    (CCA resistance in the ROM under standard assumptions). There are no
+    Bleichenbacher-style issue because we do not expose any padding semantics.
+
+    Args:
+      plaintext (bytes): Data to encrypt.
+      associated_data (bytes, optional): Optional AAD; must be provided again on decrypt
+
+    Returns:
+      bytes: Ciphertext; see above:
+      Padded(ct, k) + AES-256-GCM(key=SHA512(r)[32:], plaintext,
+                                  associated_data="prefix" + len(aad) + aad + Padded(ct, k))
+
+    Raises:
+      InputError: invalid inputs
+      CryptoError: internal crypto failures
+    """
+    # 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())
+    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'
+    # encrypt plaintext with AES-256-GCM using SHA512(r)[32:] as key; return ct || Encrypt(...)
+    ss: bytes = base.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)
+
+  def RawVerify(self, message: int, signature: int, /) -> bool:
     """Verify a signature. True if OK; False if failed verification.
 
+    BEWARE: This is raw RSA, no OAEP or PSS padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
     We explicitly disallow `message` to be zero.
 
     Args:
@@ -109,7 +161,68 @@ class RSAPublicKey(base.CryptoKey):
     Raises:
       InputError: invalid inputs
     """
-    return self.Encrypt(signature) == message
+    return self.RawEncrypt(signature) == message
+
+  def _DomainSeparatedHash(
+      self, message: bytes, associated_data: bytes | None, salt: bytes, /) -> int:
+    """Compute the domain-separated hash for signing and verifying.
+
+    Args:
+      message (bytes): message to sign/verify
+      associated_data (bytes | None): optional associated data
+      salt (bytes): salt to use in the hash
+
+    Returns:
+      int: integer representation of the hash output;
+      Hash512("prefix" || len(aad) || aad || message || salt)
+
+    Raises:
+      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'
+    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:
+      # will only reasonably happen if modulus is small
+      raise base.CryptoError(f'hash output {y} is out of range/invalid {self.public_modulus}')
+    return y
+
+  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.
+
+    • Let k = ceil(log2(n))/8 be the modulus size in bytes.
+    • Split signature in two parts: the first 64 bytes is salt, the rest is s
+    • y_check = s^e mod n
+    • return y_check == Hash512("prefix" || len(aad) || aad || message || salt)
+    • return False for any malformed signature
+
+    Args:
+      message (bytes): Data that was signed
+      signature (bytes): Signature data to verify
+      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
+    """
+    k: int = self.modulus_size
+    if k <= 64:
+      raise base.InputError(f'modulus too small for signing operations: {k} bytes')
+    if len(signature) != (64 + k):
+      logging.info(f'invalid signature length: {len(signature)} ; expected {64 + k}')
+      return False
+    try:
+      return self.RawVerify(
+          self._DomainSeparatedHash(message, associated_data, signature[:64]),
+          base.BytesToInt(signature[64:]))
+    except base.InputError as err:
+      logging.info(err)
+      return False
 
   @classmethod
   def Copy(cls, other: RSAPublicKey, /) -> Self:
@@ -154,7 +267,8 @@ class RSAObfuscationPair(RSAPublicKey):
     Returns:
       string representation of RSAObfuscationPair without leaking secrets
     """
-    return (f'RSAObfuscationPair({super(RSAObfuscationPair, self).__str__()}, '  # pylint: disable=super-with-arguments
+    return ('RSAObfuscationPair('
+            f'{super(RSAObfuscationPair, self).__str__()}, '  # pylint: disable=super-with-arguments
             f'random_key={base.ObfuscateSecret(self.random_key)}, '
             f'key_inverse={base.ObfuscateSecret(self.key_inverse)})')
 
@@ -198,11 +312,11 @@ class RSAObfuscationPair(RSAPublicKey):
     """
     # verify that obfuscated signature is valid
     obfuscated: int = self.ObfuscateMessage(message)
-    if not self.VerifySignature(obfuscated, signature):
+    if not self.RawVerify(obfuscated, signature):
       raise base.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.VerifySignature(message, original):
+    if not self.RawVerify(message, original):
       raise base.CryptoError(f'failed signature recovery: {message=} ; {signature=}')
     return original
 
@@ -243,11 +357,9 @@ class RSAObfuscationPair(RSAPublicKey):
 
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
-class RSAPrivateKey(RSAPublicKey):
+class RSAPrivateKey(RSAPublicKey, base.Decryptor, base.Signer):  # pylint: disable=too-many-ancestors
   """RSA (Rivest-Shamir-Adleman) private key.
 
-  BEWARE: This is raw RSA, no OAEP or PSS padding or validation!
-  These are pedagogical/raw primitives; do not use for new protocols.
   No measures are taken here to prevent timing attacks.
 
   The attributes modulus_p (p), modulus_q (q) and decrypt_exp (d) are "enough" for a working key,
@@ -280,7 +392,7 @@ class RSAPrivateKey(RSAPublicKey):
     """
     super(RSAPrivateKey, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
     phi: int = (self.modulus_p - 1) * (self.modulus_q - 1)
-    min_prime_distance: int = 2 ** (self.public_modulus.bit_length() // 3 + 1)
+    min_prime_distance: int = 1 << (self.public_modulus.bit_length() // 4)  # ≈ n**(1/4)
     if (self.modulus_p < 2 or not modmath.IsPrime(self.modulus_p) or  # pylint: disable=too-many-boolean-expressions
         self.modulus_q < 3 or not modmath.IsPrime(self.modulus_q) or
         self.modulus_q <= self.modulus_p or
@@ -313,14 +425,17 @@ class RSAPrivateKey(RSAPublicKey):
     Returns:
       string representation of RSAPrivateKey without leaking secrets
     """
-    return (f'RSAPrivateKey({super(RSAPrivateKey, self).__str__()}, '  # pylint: disable=super-with-arguments
+    return ('RSAPrivateKey('
+            f'{super(RSAPrivateKey, self).__str__()}, '  # pylint: disable=super-with-arguments
             f'modulus_p={base.ObfuscateSecret(self.modulus_p)}, '
             f'modulus_q={base.ObfuscateSecret(self.modulus_q)}, '
             f'decrypt_exp={base.ObfuscateSecret(self.decrypt_exp)})')
 
-  def Decrypt(self, ciphertext: int, /) -> int:
+  def RawDecrypt(self, ciphertext: int, /) -> int:
     """Decrypt `ciphertext` with this private key.
 
+    BEWARE: This is raw RSA, no OAEP or PSS padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
     We explicitly allow `ciphertext` to be zero for completeness, but it shouldn't be in practice.
 
     Args:
@@ -342,9 +457,44 @@ class RSAPrivateKey(RSAPublicKey):
     h: int = (self.q_inverse_p * (m_p - m_q)) % self.modulus_p
     return (m_q + h * self.modulus_q) % self.public_modulus
 
-  def Sign(self, message: int, /) -> int:
+  def Decrypt(self, ciphertext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
+    """Decrypt `ciphertext` and return the original `plaintext`.
+
+    • Let k = ceil(log2(n))/8 be the modulus size in bytes.
+    • Split ciphertext in two parts: the first k bytes is ct, the rest is AES-256-GCM
+    • r = ct^d mod n
+    • return AES-256-GCM(key=SHA512(r)[32:], ciphertext,
+                         associated_data="prefix" + len(aad) + aad + Padded(ct, k))
+
+    Args:
+      ciphertext (bytes): Data to decrypt; see Encrypt() above:
+          Padded(ct, k) + AES-256-GCM(key=SHA512(r)[32:], plaintext,
+                                      associated_data="prefix" + len(aad) + aad + Padded(ct, k))
+      associated_data (bytes, optional): Optional AAD (must match what was used during encrypt)
+
+    Returns:
+      bytes: Decrypted plaintext bytes
+
+    Raises:
+      InputError: invalid inputs
+      CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+    """
+    k: int = self.modulus_size
+    if len(ciphertext) < (k + 32):
+      raise base.InputError(f'invalid ciphertext length: {len(ciphertext)} ; {k=}')
+    # 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))
+    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)
+
+  def RawSign(self, message: int, /) -> int:
     """Sign `message` with this private key.
 
+    BEWARE: This is raw RSA, no OAEP or PSS padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
     We explicitly disallow `message` to be zero.
 
     Args:
@@ -361,7 +511,41 @@ class RSAPrivateKey(RSAPublicKey):
     if not 0 < message < self.public_modulus:
       raise base.InputError(f'invalid message: {message=}')
     # call decryption
-    return self.Decrypt(message)
+    return self.RawDecrypt(message)
+
+  def Sign(self, message: bytes, /, *, associated_data: bytes | None = None) -> bytes:
+    """Sign `message` and return the `signature`.
+
+    • Let k = ceil(log2(n))/8 be the modulus size in bytes.
+    • Pick random salt of 64 bytes
+    • s = (Hash512("prefix" || len(aad) || aad || message || salt))^d mod n
+    • return salt || Padded(s, k)
+
+    This is basically Full-Domain Hash RSA with a 512-bit hash and per-signature salt,
+    which is EUF-CMA secure in the ROM. Our domain-separation prefix and explicit AAD
+    length prefix are both correct and remove composition/ambiguity pitfalls.
+    There are no Bleichenbacher-style issue because we do not expose any padding semantics.
+
+    Args:
+      message (bytes): Data to sign.
+      associated_data (bytes, optional): Optional AAD for AEAD modes; must be
+          provided again on decrypt
+
+    Returns:
+      bytes: Signature; salt || Padded(s, k) - see above
+
+    Raises:
+      InputError: invalid inputs
+      CryptoError: internal crypto failures
+    """
+    k: int = self.modulus_size
+    if k <= 64:
+      raise base.InputError(f'modulus too small for signing operations: {k} bytes')
+    salt: bytes = base.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'
+    return salt + s_bytes
 
   @classmethod
   def New(cls, bit_length: int, /) -> Self:

transcrypto/sss.py

@@ -14,25 +14,23 @@ import logging
 # import pdb
 from typing import Collection, Generator, Self
 
-from . import base
-from . import modmath
+from . import base, modmath, aes
 
 __author__ = 'balparda@github.com'
 __version__: str = base.__version__  # version comes from base!
 __version_tuple__: tuple[int, ...] = base.__version_tuple__
 
 
+# fixed prefixes: do NOT ever change! will break all encryption and signature schemes
+_SSS_ENCRYPTION_AAD_PREFIX = b'transcrypto.SSS.Sharing.1.0\x00'
+
+
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
 class ShamirSharedSecretPublic(base.CryptoKey):
   """Shamir Shared Secret (SSS) public part.
 
-  BEWARE: This is raw SSS, no modern message wrapping, padding or validation!
-  These are pedagogical/raw primitives; do not use for new protocols.
   No measures are taken here to prevent timing attacks.
-
-  This is the information-theoretic SSS but with no authentication or binding between
-  share and secret. Malicious share injection is possible! Add MAC or digital signature
-  in hostile settings.
+  Malicious share injection is possible! Add MAC or digital signature in hostile settings.
 
   Attributes:
     minimum (int): minimum shares needed for recovery, ≥ 2
@@ -61,13 +59,24 @@ class ShamirSharedSecretPublic(base.CryptoKey):
       string representation of ShamirSharedSecretPublic
     """
     return ('ShamirSharedSecretPublic('
+            f'bits={self.modulus.bit_length()}, '
             f'minimum={self.minimum}, '
             f'modulus={base.IntToEncoded(self.modulus)})')
 
-  def RecoverSecret(
+  @property
+  def modulus_size(self) -> int:
+    """Modulus size in bytes. The number of bytes used in MakeDataShares/RecoverData."""
+    return (self.modulus.bit_length() + 7) // 8
+
+  def RawRecoverSecret(
       self, shares: Collection[ShamirSharePrivate], /, *, force_recover: bool = False) -> int:
     """Recover the secret from ShamirSharePrivate objects.
 
+    BEWARE: This is raw SSS, no modern message wrapping, padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
+    This is the information-theoretic SSS but with no authentication or binding between
+    share and secret.
+
     Args:
       shares (Collection[ShamirSharePrivate]): shares to use to recover the secret
       force_recover (bool, optional): if True will try to recover (default: False)
@@ -114,9 +123,8 @@ class ShamirSharedSecretPublic(base.CryptoKey):
 class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
   """Shamir Shared Secret (SSS) private keys.
 
-  BEWARE: This is raw SSS, no modern message wrapping, padding or validation!
-  These are pedagogical/raw primitives; do not use for new protocols.
   No measures are taken here to prevent timing attacks.
+  Malicious share injection is possible! Add MAC or digital signature in hostile settings.
 
   We deliberately choose prime coefficients. This shrinks the key-space and leaks a bit of
   structure. It is "unusual", but with large enough modulus (bit length > ~ 500) it makes no
@@ -148,12 +156,18 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
     Returns:
       string representation of ShamirSharedSecretPrivate without leaking secrets
     """
-    return (f'ShamirSharedSecretPrivate({super(ShamirSharedSecretPrivate, self).__str__()}, '  # pylint: disable=super-with-arguments
+    return ('ShamirSharedSecretPrivate('
+            f'{super(ShamirSharedSecretPrivate, self).__str__()}, '  # pylint: disable=super-with-arguments
             f'polynomial=[{", ".join(base.ObfuscateSecret(i) for i in self.polynomial)}])')
 
-  def Share(self, secret: int, /, *, share_key: int = 0) -> ShamirSharePrivate:
+  def RawShare(self, secret: int, /, *, share_key: int = 0) -> ShamirSharePrivate:
     """Make a new ShamirSharePrivate for the `secret`.
 
+    BEWARE: This is raw SSS, no modern message wrapping, padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
+    This is the information-theoretic SSS but with no authentication or binding between
+    share and secret.
+
     Args:
       secret (int): secret message to encrypt and share, 0 ≤ s < modulus
       share_key (int, optional): if given, a random value to use, 1 ≤ r < modulus;
@@ -181,10 +195,15 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
         share_key=share_key,
         share_value=modmath.ModPolynomial(share_key, [secret] + self.polynomial, self.modulus))
 
-  def Shares(
+  def RawShares(
       self, secret: int, /, *, max_shares: int = 0) -> Generator[ShamirSharePrivate, None, None]:
     """Make any number of ShamirSharePrivate for the `secret`.
 
+    BEWARE: This is raw SSS, no modern message wrapping, padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
+    This is the information-theoretic SSS but with no authentication or binding between
+    share and secret.
+
     Args:
       secret (int): secret message to encrypt and share, 0 ≤ s < modulus
       max_shares (int, optional): if given, number (≥ 2) of shares to generate; else infinite
@@ -206,16 +225,63 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
       while not share_key or share_key in self.polynomial or share_key in used_keys:
         share_key = base.RandBits(self.modulus.bit_length() - 1)
       try:
-        yield self.Share(secret, share_key=share_key)
+        yield self.RawShare(secret, share_key=share_key)
         used_keys.add(share_key)
         count += 1
       except base.InputError as err:
         # it could happen, for example, that the share_key will generate a value of 0
         logging.warning(err)
 
-  def VerifyShare(self, secret: int, share: ShamirSharePrivate, /) -> bool:
+  def MakeDataShares(self, secret: bytes, total_shares: int, /) -> list[ShamirShareData]:
+    """Make `total_shares` ShamirShareData objects with encrypted `secret`.
+
+    • Let k = ceil(log2(n))/8 be the modulus size in bytes
+    • r = random 32 bytes
+    • shares = SSS.Shares(r, total_shares)
+    • ct = AES-256-GCM(key=SHA512("prefix" + r)[32:], plaintext=secret,
+                       associated_data="prefix" + minimum + modulus)
+    • return [share + ct for share in shares]
+
+    Args:
+      secret (bytes): Data to encrypt and distribute (encrypted) in each share.
+      total_shares (int): Number of shares to make, ≥ minimum
+
+    Returns:
+      list[ShamirShareData]: the list of shares with encrypted data
+
+    Raises:
+      InputError: invalid inputs
+      CryptoError: internal crypto failures
+    """
+    if total_shares < self.minimum:
+      raise base.InputError(f'invalid total_shares: {total_shares=} < {self.minimum=}')
+    k: int = self.modulus_size
+    if k <= 32:
+      raise base.InputError(f'modulus too small for key operations: {k} bytes')
+    key256: bytes = base.RandBytes(32)
+    shares: list[ShamirSharePrivate] = list(
+        self.RawShares(base.BytesToInt(key256), max_shares=total_shares))
+    aad: bytes = (
+        _SSS_ENCRYPTION_AAD_PREFIX +
+        base.IntToFixedBytes(self.minimum, 8) + base.IntToFixedBytes(self.modulus, k))
+    aead_key: bytes = base.Hash512(_SSS_ENCRYPTION_AAD_PREFIX + key256)
+    ct: bytes = aes.AESKey(key256=aead_key[32:]).Encrypt(secret, associated_data=aad)
+    return [ShamirShareData(
+        minimum=s.minimum,
+        modulus=s.modulus,
+        share_key=s.share_key,
+        share_value=s.share_value,
+        encrypted_data=ct,
+    ) for s in shares]
+
+  def RawVerifyShare(self, secret: int, share: ShamirSharePrivate, /) -> bool:
     """Verify a ShamirSharePrivate object for the `secret`.
 
+    BEWARE: This is raw SSS, no modern message wrapping, padding or validation!
+    These are pedagogical/raw primitives; do not use for new protocols.
+    This is the information-theoretic SSS but with no authentication or binding between
+    share and secret.
+
     Args:
       secret (int): secret message to encrypt and share, 0 ≤ s < modulus
       share (ShamirSharePrivate): share to verify
@@ -226,7 +292,7 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
     Raises:
       InputError: invalid inputs
     """
-    return share == self.Share(secret, share_key=share.share_key)
+    return share == self.RawShare(secret, share_key=share.share_key)
 
   @classmethod
   def New(cls, minimum_shares: int, bit_length: int, /) -> Self:
@@ -265,9 +331,8 @@ class ShamirSharedSecretPrivate(ShamirSharedSecretPublic):
 class ShamirSharePrivate(ShamirSharedSecretPublic):
   """Shamir Shared Secret (SSS) one share.
 
-  BEWARE: This is raw SSS, no modern message wrapping, padding or validation!
-  These are pedagogical/raw primitives; do not use for new protocols.
   No measures are taken here to prevent timing attacks.
+  Malicious share injection is possible! Add MAC or digital signature in hostile settings.
 
   Attributes:
     share_key (int): share secret key; a randomly picked value, 1 ≤ k < modulus
@@ -294,6 +359,80 @@ class ShamirSharePrivate(ShamirSharedSecretPublic):
     Returns:
       string representation of ShamirSharePrivate without leaking secrets
     """
-    return (f'ShamirSharePrivate({super(ShamirSharePrivate, self).__str__()}, '  # pylint: disable=super-with-arguments
+    return ('ShamirSharePrivate('
+            f'{super(ShamirSharePrivate, self).__str__()}, '  # pylint: disable=super-with-arguments
             f'share_key={base.ObfuscateSecret(self.share_key)}, '
             f'share_value={base.ObfuscateSecret(self.share_value)})')
+
+  @classmethod
+  def CopyShare(cls, other: ShamirSharePrivate, /) -> Self:
+    """Initialize a share taking the parts of another share."""
+    return cls(
+        minimum=other.minimum, modulus=other.modulus,
+        share_key=other.share_key, share_value=other.share_value)
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
+class ShamirShareData(ShamirSharePrivate):
+  """Shamir Shared Secret (SSS) one share.
+
+  No measures are taken here to prevent timing attacks.
+  Malicious share injection is possible! Add MAC or digital signature in hostile settings.
+
+  Attributes:
+    share_key (int): share secret key; a randomly picked value, 1 ≤ k < modulus
+    share_value (int): share secret value, 1 ≤ v < modulus; (k, v) is a "point" of f(k)=v
+  """
+
+  encrypted_data: bytes
+
+  def __post_init__(self) -> None:
+    """Check data.
+
+    Raises:
+      InputError: invalid inputs
+    """
+    super(ShamirShareData, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
+    if len(self.encrypted_data) < 32:
+      raise base.InputError(f'AES256+GCM SSS should have ≥32 bytes IV/CT/tag: {self}')
+
+  def __str__(self) -> str:
+    """Safe (no secrets) string representation of the ShamirShareData.
+
+    Returns:
+      string representation of ShamirShareData without leaking secrets
+    """
+    return ('ShamirShareData('
+            f'{super(ShamirShareData, self).__str__()}, '  # pylint: disable=super-with-arguments
+            f'encrypted_data={base.ObfuscateSecret(self.encrypted_data)})')
+
+  def RecoverData(self, other_shares: list[ShamirSharePrivate]) -> bytes:
+    """Recover the encrypted data from ShamirSharePrivate objects.
+
+    * key256 = SSS.RecoverSecret([this] + other_shares)
+    * return AES-256-GCM(key=SHA512("prefix" + key256)[32:], ciphertext=encrypted_data,
+                         associated_data="prefix" + minimum + modulus)
+
+    Args:
+      other_shares (list[ShamirSharePrivate]): Other shares to use to recover the secret
+
+    Returns:
+      bytes: Decrypted plaintext bytes
+
+    Raises:
+      InputError: invalid inputs
+      CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+    """
+    k: int = self.modulus_size
+    if k <= 32:
+      raise base.InputError(f'modulus too small for key operations: {k} bytes')
+    # recover secret; raise if shares are invalid
+    secret: int = self.RawRecoverSecret([self] + other_shares)
+    if not 0 <= secret < (1 << 256):
+      raise base.CryptoError('recovered key out of range for 256-bit key')
+    key256: bytes = base.IntToFixedBytes(secret, 32)
+    aad: bytes = (
+        _SSS_ENCRYPTION_AAD_PREFIX +
+        base.IntToFixedBytes(self.minimum, 8) + base.IntToFixedBytes(self.modulus, k))
+    aead_key: bytes = base.Hash512(_SSS_ENCRYPTION_AAD_PREFIX + key256)
+    return aes.AESKey(key256=aead_key[32:]).Decrypt(self.encrypted_data, associated_data=aad)