lightphe 0.0.16__tar.gz → 0.0.17__tar.gz

{lightphe-0.0.16 → lightphe-0.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lightphe
-Version: 0.0.16
+Version: 0.0.17
 Summary: A Lightweight Partially Homomorphic Encryption Library for Python
 Home-page: https://github.com/serengil/LightPHE
 Author: Sefik Ilkin Serengil
@@ -67,7 +67,7 @@ from lightphe import LightPHE
 
 In summary, LightPHE is covering following algorithms and these are partially homomorphic with respect to the operations mentioned in the following table.
 
-| Algorithm | Multiplicatively<br>Homomorphic | Additively<br>Homomorphic | Multiplication with a Plain Constant | Exclusively<br>Homomorphic | Regeneration<br>of Ciphertext |
+| Algorithm | Multiplicatively<br>Homomorphic | Additively<br>Homomorphic | Scalar Multiplication | Exclusively<br>Homomorphic | Regeneration<br>of Ciphertext |
 | --- | --- | --- | --- | --- | --- |
 | RSA | ✅ | ❌ | ❌ | ❌ | ❌ |
 | ElGamal | ✅ | ❌ | ❌ | ❌ | ✅ |
@@ -98,124 +98,56 @@ algorithms = [
   "EllipticCurve-ElGamal"
 ]
 
-phe = LightPHE(algorithm_name = algorithms[0])
-```
-
-# Encryption & Decryption
-
-Once you built your cryptosystem, you will be able to encrypt and decrypt messages with the built cryptosystem.
-
-```python
-# define plaintext
-m = 17
-
-# calculate ciphertext
-c = phe.encrypt(m)
-
-# proof of work
-assert phe.decrypt(c) == m
+cs = LightPHE(algorithm_name = algorithms[0])
 ```
 
 # Homomorphic Operations
 
-Once you have the ciphertext, you will be able to perform homomorphic operations on encrypted data without holding private key. For instance, Paillier is homomorphic with respect to the addition. In other words, decryption of the addition of two ciphertexts is equivalent to addition of plaintexts.
-
-### On-Prem Encryption
-
-This code snippet illustrates how to generate a random public-private key pair using the Paillier and encrypt a plaintext pair. The resulting ciphertext pair, c1 and c2, along with the public key, is then sent from the on-premises environment to the cloud.
+The following example demonstrates a simple workflow using LightPHE with an additively homomorphic cryptosystem (e.g. Paillier). First, we build the cryptosystem on-premises and define two plaintext values. Next, we encrypt the plaintexts, which can be done either on-premises or in the cloud, and does not require the private key. Homomorphic operations, such as addition and scalar multiplication, can then be performed on the ciphertexts—these operations can be offloaded to the cloud, leveraging its computational power without revealing the private key or the plaintext. Finally, the results are decrypted on-premises using the private key, verifying that the homomorphic operations on encrypted data produce the expected plaintext results.
 
 ```python
-def on_premise() -> Tuple[int, int, dict]:
-    """
-    Executes on-premise operations: initializes a cryptosystem by generating 
-    a random public-private key pair, then encrypts two plaintext values.
-
-    Returns:
-       result (tuple): A tuple containing:
-       - c1 (int): The first ciphertext
-       - c2 (int): The second ciphertext
-       - public_key (dict): The public key for the cryptosystem
-    """
-    # generate a random private-public key pair
-    phe = LightPHE(algorithm_name = "Paillier")
-
-    # define plaintexts
-    m1 = 10000 # base salary in usd
-    m2 = 500 # wage increase in usd
-
-    # calculate ciphertexts
-    c1 = phe.encrypt(m1).value
-    c2 = phe.encrypt(m2).value
-
-    return (c1, c2, phe.cs.public_key)
-```
-
-### Homomorphic Operations on Cloud
+# build an additively homomorphic cryptosystem
+cs = LightPHE(algorithm_name = "Paillier")
 
-This code snippet demonstrates how to perform homomorphic addition on the cloud side without using the private key. However, the cloud is unable to decrypt c3 itself, even though it is the one that calculated it.
+# define plaintexts
+m1 = 10000 # base salary in usd
+m2 = 500 # wage increase in usd
 
-```python
-def cloud(c1: int, c2: int, public_key: dict) -> int:
-    """
-    Performs cloud-side operations: reconstructs a cryptosystem using the 
-    provided public key and executes a homomorphic addition on two ciphertexts.
-
-    Args:
-       c1 (int): The first ciphertext
-       c2 (int): The second ciphertext
-       public_key (dict): The public key of an existing cryptosystem
-    Retunrs:
-       c3 (int): The resulting ciphertext after homomorphic addition
-    """
-    # restore cryptosystem with just the public key
-    phe = LightPHE(algorithm_name = "Paillier", keys = public_key)
-
-    # cast c1 and c2 to ciphertext objects
-    c1 = phe.create_ciphertext_obj(c1)
-    c2 = phe.create_ciphertext_obj(c2)
-
-    # confirm that cloud cannot decrypt c1
-    with pytest.raises(ValueError, match="You must have private key"):
-      phe.decrypt(c1)
-
-    # confirm that cloud cannot decrypt c2
-    with pytest.raises(ValueError, match="You must have private key"):
-      phe.decrypt(c2)
-
-    # perform homomorphic addition
-    c3 = c1 + c2
-
-    # confirm that cloud cannot decrypt c3
-    with pytest.raises(ValueError, match="You must have private key"):
-      phe.decrypt(c3)
-    
-    return c3.value
-```
+# encrypt plaintexts - private key is not required.
+c1 = cs.encrypt(m1)
+c2 = cs.encrypt(m2)
 
-### On-Prem Decryption And Proof of Work
+# homomorphic addition - private key is not required
+c3 = c1 + c2
 
-This code snippet demonstrates the proof of work. Even though c3 was calculated in the cloud by adding c1 and c2, on-premises can validate that its decryption must be equal to the addition of plaintexts m1 and m2.
+# homomorphic scalar multiplication - private key is not required
+k = 1.05 # increase something 5%
+c4 = k * c1
 
-```python
-# proof of work - private key required
-assert phe.decrypt(c3) == m1 + m2
+# decryption - private key is required
+assert cs.decrypt(c3) == m1 + m2
+assert cs.decrypt(c4) == k * m1
 ```
 
-In this homomorphic pipeline, the cloud's computational power was utilized to calculate c3, but it can only be decrypted by the on-premises side. Additionally, while we performed the encryption on the on-premises side, this is not strictly necessary; only the public key is required for encryption. Therefore, encryption can also be performed on the non-premises side. This approach is particularly convenient when collecting data from multiple edge devices and storing all of it in the cloud simultaneously.
+On the other hand, if you adopt a multiplicatively homomorphic cryptosyste (e.g. RSA or ElGamal), you can multiply ciphertexts without revealing the private key or the plaintext.
 
-### Scalar Multiplication
+```python
+# build a multiplicatively homomorphic cryptosystem
+cs = LightPHE(algorithm_name = "RSA")
 
-Besides, Paillier is supporting multiplying ciphertexts by a known plain constant. This code snippet demonstrates how to perform scalar multiplication on encrypted data using Paillier homomorphic encryption with the LightPHE library.
+# define plaintexts
+m1 = 17
+m2 = 21
 
-```python
-# increasing something 5%
-k = 1.05
+# encrypt plaintexts - private key is not required.
+c1 = cs.encrypt(m1)
+c2 = cs.encrypt(m2)
 
-# scalar multiplication - cloud (private key is not required)
-c4 = k * c1
+# homomorphic multiplication
+c3 = c1 * c2
 
-# proof of work on-prem - private key is required
-assert phe.decrypt(c4) == k * m1
+# decryption - private key is required
+assert cs.decrypt(c3) == m1 * m2
 ```
 
 ### Ciphertext Regeneration
@@ -223,28 +155,12 @@ assert phe.decrypt(c4) == k * m1
 Similar to the most of additively homomorphic algorithms, Paillier lets you to regenerate ciphertext while you are not breaking its plaintext restoration. You may consider to do this re-generation many times to have stronger ciphertexts.
 
 ```python
-c1_prime = phe.regenerate_ciphertext(c1)
+c1_prime = cs.regenerate_ciphertext(c1)
 assert c1_prime.value != c1.value
-assert phe.decrypt(c1_prime) == m1
-assert phe.decrypt(c1) == m1
+assert cs.decrypt(c1_prime) == m1
+assert cs.decrypt(c1) == m1
 ```
 
-### Unsupported Operations
-
-Finally, if you try to perform an operation that algorithm does not support, then an exception will be thrown. For instance, Paillier is not homomorphic with respect to the multiplication or xor. To put it simply, you cannot multiply two ciphertexts. If you enforce this calculation, you will have an exception.
-
-```python
-# pailier is not multiplicatively homomorphic
-with pytest.raises(ValueError, match="Paillier is not homomorphic with respect to the multiplication"):
-  c1 * c2
-
-# pailier is not exclusively homomorphic
-with pytest.raises(ValueError, match="Paillier is not homomorphic with respect to the exclusive or"):
-  c1 ^ c2
-```
-
-However, if you tried to multiply ciphertexts with RSA, or xor ciphertexts with Goldwasser-Micali, these will be succeeded because those cryptosystems support those homomorphic operations.
-
 ### Elliptic Curve Cryptography
 
 ECC is a powerful public-key cryptosystem based on the algebraic structure of elliptic curves over finite fields. The library supports 3 elliptic curve forms (weierstrass, edwards and koblitz) and 100+ standard elliptic curve configurations.
@@ -252,9 +168,10 @@ ECC is a powerful public-key cryptosystem based on the algebraic structure of el
 In LightPHE, the [Elliptic Curve ElGamal](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/) scheme is implemented, offering a secure and efficient homomorphic encryption option.
 
 ```python
+forms = ["weierstrass", "edwards", "koblitz"]
 phe = LightPHE(
     algorithm_name="EllipticCurve-ElGamal",
-    form="edwards", # or weierstrass, koblitz
+    form=forms[1],
 )
 ```
 
@@ -264,48 +181,9 @@ Each curve in LightPHE has a specific order, which is carefully chosen to balanc
 
 See [`curves`](https://github.com/serengil/LightECC#supported-curves) page for a list of all supported forms, curves and their details.
 
-### Vector Embeddings and Tensors
+### Vector Embeddings
 
-LightPHE supports homomorphic encryption on vector embeddings and tensors. This is useful in privacy-preserving machine learning, secure aggregation, and confidential data processing.
-
-```python
-# build a cryptosystem
-cs = LightPHE(algorithm_name="Paillier")
-
-# define plain embedding
-tensor = [1.005, 2.05, 3.005, 4.005, -5.05, 6, 7.003, 7.002]
-
-# encrypt vector embedding
-encrypted_tensors = cs.encrypt(tensor)
-
-# restore embedding
-decrypted_tensors = cs.decrypt(encrypted_tensors)
-
-# proof of work
-assert all(abs(original - decrypted) < 1e-2 for original, decrypted in zip(tensor, decrypted_tensors))
-```
-
-Encrypted embeddings retain their homomorphic properties, enabling secure computations on encrypted data without decryption. For example, two embeddings encrypted using a multiplicatively homomorphic algorithm can be multiplied element-wise.
-
-```python
-# build a multiplicatively homomorphic cryptosystem (e.g. RSA)
-cs = LightPHE("RSA")
-
-# define plain embeddings
-t1 = [1.005, 2.05, -3.5, 3.1, -4]
-t2 = [5, 6.2, -7.002, -7.1, 8.02]
-
-# encrypt embeddings
-c1, c2 = cs.encrypt(t1), cs.encrypt(t2)
-
-# perform element-wise homomorphic multiplication
-c3 = c1 * c2
-
-# proof of work
-assert np.allclose(cs.decrypt(c3), [a * b for a, b in zip(t1, t2)], rtol=1e-2)
-```
-
-Similarly, two embeddings encrypted with an additively homomorphic algorithm can be added. Additionally, an encrypted embedding can be multiplied by a constant or a plain embedding.
+LightPHE supports homomorphic encryption on vector embeddings. This is useful in privacy-preserving machine learning, secure aggregation, and confidential data processing.
 
 ```python
 # build an additively homomorphic cryptosystem (e.g. Paillier)
@@ -334,57 +212,6 @@ assert np.allclose(cs.decrypt(c5), [a * 3 for a in t1], rtol=1e-2)
 assert np.allclose(cs.decrypt(c6), [a * b for a, b in zip(t1, t3)], rtol=1e-2)
 ```
 
-### Vector Similarity Search with PHE
-
-Many machine learning models rely on a two-tower architecture, including facial recognition, reverse image search, recommendation engines, large language models, and more. In this setup, user and item inputs are separately mapped to vector embeddings.
-
-For example, suppose all facial embeddings in your database are encrypted on-prem in advance. When verifying an identity, the attempted facial embedding is generated on an edge device or in the cloud. You can compute the encrypted similarity by performing a dot product between the encrypted vector and the plain vector, ensuring secure comparison without decrypting sensitive data. Only additively homomorphic cryptosystems offer encrypted similarity calculation.
-
-```python
-# define a plain vectors for source and target
-alpha = [7.1, 5.2, 5.3, 2.4, 3.5, 4.6]  # On-prem vector (user tower)
-beta = [5.6, 3.7, 2.8, 4, 0, 5.9]  # Cloud vector (item tower)
-expected_similarity = sum(x * y for x, y in zip(alpha, beta))
-
-# build an additively homomorphic cryptosystem (e.g. Paillier) on-prem
-cs = LightPHE(algorithm_name = "Paillier", precision = 19)
-
-# export keys
-cs.export_keys("secret.txt")
-cs.export_keys("public.txt", public=True)
-
-# encrypt source embedding
-encrypted_alpha = cs.encrypt(alpha)
-
-# remove cryptosystem and plain alpha not to be leaked in cloud
-del cs, alpha
-
-# restore the cryptosystem in cloud with only public key
-cloud_cs = LightPHE(algorithm_name = "Paillier", precision = 19, key_file = "public.txt")
-
-# dot product of encrypted and plain embedding pair
-encrypted_cosine_similarity = encrypted_alpha @ beta
-
-# computed by the cloud but cloud cannot decrypt it
-with pytest.raises(ValueError, match="must have private key"):
-    cloud_cs.decrypt(encrypted_cosine_similarity)
-
-# restore the cryptosystem on-prem with secret key
-cs = LightPHE(algorithm_name = "Paillier", precision = 19, key_file = "secret.txt")
-
-# decrypt similarity (on prem)
-calculated_similarity = cs.decrypt(encrypted_cosine_similarity)[0]
-
-# proof of work
-assert abs(calculated_similarity - expected_similarity) < 1e-2
-```
-
-## Security Concerns and Considerations
-
-While LightPHE enables encryption using public keys and supports homomorphic operations on encrypted data, it's important to understand a subtle but critical security implication of this approach. Since the it is homomorphic, the cloud (or any third-party processor) can perform computations without knowing the plaintext. However, a malicious actor can still encrypt arbitrary values and craft valid ciphertexts because encryption depends on your public key and it is publicly known. For example, even if a salary is encrypted, an attacker could encrypt 500 USD using your public key and update the encrypted salary with this forged ciphertext — without needing to know the original value.
-
-To mitigate this, we recommend combining LightPHE with digital signature schemes. By keeping a signed audit trail of update operations in a separate log table, you can detect and reject unauthorized changes, and even restore the original data in case of tampering. We suggest checking out [`LightDSA`](https://github.com/serengil/LightDSA), which provides a lightweight cryptographic interface similar to LightPHE and supports popular digital signature algorithms like RSA, DSA, ECDSA, and EdDSA.
-
 # Contributing
 
 All PRs are more than welcome! If you are planning to contribute a large patch, please create an issue first to get any upfront questions or design decisions out of the way first.

{lightphe-0.0.16 → lightphe-0.0.17}/README.md

@@ -51,7 +51,7 @@ from lightphe import LightPHE
 
 In summary, LightPHE is covering following algorithms and these are partially homomorphic with respect to the operations mentioned in the following table.
 
-| Algorithm | Multiplicatively<br>Homomorphic | Additively<br>Homomorphic | Multiplication with a Plain Constant | Exclusively<br>Homomorphic | Regeneration<br>of Ciphertext |
+| Algorithm | Multiplicatively<br>Homomorphic | Additively<br>Homomorphic | Scalar Multiplication | Exclusively<br>Homomorphic | Regeneration<br>of Ciphertext |
 | --- | --- | --- | --- | --- | --- |
 | RSA | ✅ | ❌ | ❌ | ❌ | ❌ |
 | ElGamal | ✅ | ❌ | ❌ | ❌ | ✅ |
@@ -82,124 +82,56 @@ algorithms = [
   "EllipticCurve-ElGamal"
 ]
 
-phe = LightPHE(algorithm_name = algorithms[0])
-```
-
-# Encryption & Decryption
-
-Once you built your cryptosystem, you will be able to encrypt and decrypt messages with the built cryptosystem.
-
-```python
-# define plaintext
-m = 17
-
-# calculate ciphertext
-c = phe.encrypt(m)
-
-# proof of work
-assert phe.decrypt(c) == m
+cs = LightPHE(algorithm_name = algorithms[0])
 ```
 
 # Homomorphic Operations
 
-Once you have the ciphertext, you will be able to perform homomorphic operations on encrypted data without holding private key. For instance, Paillier is homomorphic with respect to the addition. In other words, decryption of the addition of two ciphertexts is equivalent to addition of plaintexts.
-
-### On-Prem Encryption
-
-This code snippet illustrates how to generate a random public-private key pair using the Paillier and encrypt a plaintext pair. The resulting ciphertext pair, c1 and c2, along with the public key, is then sent from the on-premises environment to the cloud.
+The following example demonstrates a simple workflow using LightPHE with an additively homomorphic cryptosystem (e.g. Paillier). First, we build the cryptosystem on-premises and define two plaintext values. Next, we encrypt the plaintexts, which can be done either on-premises or in the cloud, and does not require the private key. Homomorphic operations, such as addition and scalar multiplication, can then be performed on the ciphertexts—these operations can be offloaded to the cloud, leveraging its computational power without revealing the private key or the plaintext. Finally, the results are decrypted on-premises using the private key, verifying that the homomorphic operations on encrypted data produce the expected plaintext results.
 
 ```python
-def on_premise() -> Tuple[int, int, dict]:
-    """
-    Executes on-premise operations: initializes a cryptosystem by generating 
-    a random public-private key pair, then encrypts two plaintext values.
-
-    Returns:
-       result (tuple): A tuple containing:
-       - c1 (int): The first ciphertext
-       - c2 (int): The second ciphertext
-       - public_key (dict): The public key for the cryptosystem
-    """
-    # generate a random private-public key pair
-    phe = LightPHE(algorithm_name = "Paillier")
-
-    # define plaintexts
-    m1 = 10000 # base salary in usd
-    m2 = 500 # wage increase in usd
-
-    # calculate ciphertexts
-    c1 = phe.encrypt(m1).value
-    c2 = phe.encrypt(m2).value
-
-    return (c1, c2, phe.cs.public_key)
-```
-
-### Homomorphic Operations on Cloud
+# build an additively homomorphic cryptosystem
+cs = LightPHE(algorithm_name = "Paillier")
 
-This code snippet demonstrates how to perform homomorphic addition on the cloud side without using the private key. However, the cloud is unable to decrypt c3 itself, even though it is the one that calculated it.
+# define plaintexts
+m1 = 10000 # base salary in usd
+m2 = 500 # wage increase in usd
 
-```python
-def cloud(c1: int, c2: int, public_key: dict) -> int:
-    """
-    Performs cloud-side operations: reconstructs a cryptosystem using the 
-    provided public key and executes a homomorphic addition on two ciphertexts.
-
-    Args:
-       c1 (int): The first ciphertext
-       c2 (int): The second ciphertext
-       public_key (dict): The public key of an existing cryptosystem
-    Retunrs:
-       c3 (int): The resulting ciphertext after homomorphic addition
-    """
-    # restore cryptosystem with just the public key
-    phe = LightPHE(algorithm_name = "Paillier", keys = public_key)
-
-    # cast c1 and c2 to ciphertext objects
-    c1 = phe.create_ciphertext_obj(c1)
-    c2 = phe.create_ciphertext_obj(c2)
-
-    # confirm that cloud cannot decrypt c1
-    with pytest.raises(ValueError, match="You must have private key"):
-      phe.decrypt(c1)
-
-    # confirm that cloud cannot decrypt c2
-    with pytest.raises(ValueError, match="You must have private key"):
-      phe.decrypt(c2)
-
-    # perform homomorphic addition
-    c3 = c1 + c2
-
-    # confirm that cloud cannot decrypt c3
-    with pytest.raises(ValueError, match="You must have private key"):
-      phe.decrypt(c3)
-    
-    return c3.value
-```
+# encrypt plaintexts - private key is not required.
+c1 = cs.encrypt(m1)
+c2 = cs.encrypt(m2)
 
-### On-Prem Decryption And Proof of Work
+# homomorphic addition - private key is not required
+c3 = c1 + c2
 
-This code snippet demonstrates the proof of work. Even though c3 was calculated in the cloud by adding c1 and c2, on-premises can validate that its decryption must be equal to the addition of plaintexts m1 and m2.
+# homomorphic scalar multiplication - private key is not required
+k = 1.05 # increase something 5%
+c4 = k * c1
 
-```python
-# proof of work - private key required
-assert phe.decrypt(c3) == m1 + m2
+# decryption - private key is required
+assert cs.decrypt(c3) == m1 + m2
+assert cs.decrypt(c4) == k * m1
 ```
 
-In this homomorphic pipeline, the cloud's computational power was utilized to calculate c3, but it can only be decrypted by the on-premises side. Additionally, while we performed the encryption on the on-premises side, this is not strictly necessary; only the public key is required for encryption. Therefore, encryption can also be performed on the non-premises side. This approach is particularly convenient when collecting data from multiple edge devices and storing all of it in the cloud simultaneously.
+On the other hand, if you adopt a multiplicatively homomorphic cryptosyste (e.g. RSA or ElGamal), you can multiply ciphertexts without revealing the private key or the plaintext.
 
-### Scalar Multiplication
+```python
+# build a multiplicatively homomorphic cryptosystem
+cs = LightPHE(algorithm_name = "RSA")
 
-Besides, Paillier is supporting multiplying ciphertexts by a known plain constant. This code snippet demonstrates how to perform scalar multiplication on encrypted data using Paillier homomorphic encryption with the LightPHE library.
+# define plaintexts
+m1 = 17
+m2 = 21
 
-```python
-# increasing something 5%
-k = 1.05
+# encrypt plaintexts - private key is not required.
+c1 = cs.encrypt(m1)
+c2 = cs.encrypt(m2)
 
-# scalar multiplication - cloud (private key is not required)
-c4 = k * c1
+# homomorphic multiplication
+c3 = c1 * c2
 
-# proof of work on-prem - private key is required
-assert phe.decrypt(c4) == k * m1
+# decryption - private key is required
+assert cs.decrypt(c3) == m1 * m2
 ```
 
 ### Ciphertext Regeneration
@@ -207,28 +139,12 @@ assert phe.decrypt(c4) == k * m1
 Similar to the most of additively homomorphic algorithms, Paillier lets you to regenerate ciphertext while you are not breaking its plaintext restoration. You may consider to do this re-generation many times to have stronger ciphertexts.
 
 ```python
-c1_prime = phe.regenerate_ciphertext(c1)
+c1_prime = cs.regenerate_ciphertext(c1)
 assert c1_prime.value != c1.value
-assert phe.decrypt(c1_prime) == m1
-assert phe.decrypt(c1) == m1
+assert cs.decrypt(c1_prime) == m1
+assert cs.decrypt(c1) == m1
 ```
 
-### Unsupported Operations
-
-Finally, if you try to perform an operation that algorithm does not support, then an exception will be thrown. For instance, Paillier is not homomorphic with respect to the multiplication or xor. To put it simply, you cannot multiply two ciphertexts. If you enforce this calculation, you will have an exception.
-
-```python
-# pailier is not multiplicatively homomorphic
-with pytest.raises(ValueError, match="Paillier is not homomorphic with respect to the multiplication"):
-  c1 * c2
-
-# pailier is not exclusively homomorphic
-with pytest.raises(ValueError, match="Paillier is not homomorphic with respect to the exclusive or"):
-  c1 ^ c2
-```
-
-However, if you tried to multiply ciphertexts with RSA, or xor ciphertexts with Goldwasser-Micali, these will be succeeded because those cryptosystems support those homomorphic operations.
-
 ### Elliptic Curve Cryptography
 
 ECC is a powerful public-key cryptosystem based on the algebraic structure of elliptic curves over finite fields. The library supports 3 elliptic curve forms (weierstrass, edwards and koblitz) and 100+ standard elliptic curve configurations.
@@ -236,9 +152,10 @@ ECC is a powerful public-key cryptosystem based on the algebraic structure of el
 In LightPHE, the [Elliptic Curve ElGamal](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/) scheme is implemented, offering a secure and efficient homomorphic encryption option.
 
 ```python
+forms = ["weierstrass", "edwards", "koblitz"]
 phe = LightPHE(
     algorithm_name="EllipticCurve-ElGamal",
-    form="edwards", # or weierstrass, koblitz
+    form=forms[1],
 )
 ```
 
@@ -248,48 +165,9 @@ Each curve in LightPHE has a specific order, which is carefully chosen to balanc
 
 See [`curves`](https://github.com/serengil/LightECC#supported-curves) page for a list of all supported forms, curves and their details.
 
-### Vector Embeddings and Tensors
+### Vector Embeddings
 
-LightPHE supports homomorphic encryption on vector embeddings and tensors. This is useful in privacy-preserving machine learning, secure aggregation, and confidential data processing.
-
-```python
-# build a cryptosystem
-cs = LightPHE(algorithm_name="Paillier")
-
-# define plain embedding
-tensor = [1.005, 2.05, 3.005, 4.005, -5.05, 6, 7.003, 7.002]
-
-# encrypt vector embedding
-encrypted_tensors = cs.encrypt(tensor)
-
-# restore embedding
-decrypted_tensors = cs.decrypt(encrypted_tensors)
-
-# proof of work
-assert all(abs(original - decrypted) < 1e-2 for original, decrypted in zip(tensor, decrypted_tensors))
-```
-
-Encrypted embeddings retain their homomorphic properties, enabling secure computations on encrypted data without decryption. For example, two embeddings encrypted using a multiplicatively homomorphic algorithm can be multiplied element-wise.
-
-```python
-# build a multiplicatively homomorphic cryptosystem (e.g. RSA)
-cs = LightPHE("RSA")
-
-# define plain embeddings
-t1 = [1.005, 2.05, -3.5, 3.1, -4]
-t2 = [5, 6.2, -7.002, -7.1, 8.02]
-
-# encrypt embeddings
-c1, c2 = cs.encrypt(t1), cs.encrypt(t2)
-
-# perform element-wise homomorphic multiplication
-c3 = c1 * c2
-
-# proof of work
-assert np.allclose(cs.decrypt(c3), [a * b for a, b in zip(t1, t2)], rtol=1e-2)
-```
-
-Similarly, two embeddings encrypted with an additively homomorphic algorithm can be added. Additionally, an encrypted embedding can be multiplied by a constant or a plain embedding.
+LightPHE supports homomorphic encryption on vector embeddings. This is useful in privacy-preserving machine learning, secure aggregation, and confidential data processing.
 
 ```python
 # build an additively homomorphic cryptosystem (e.g. Paillier)
@@ -318,57 +196,6 @@ assert np.allclose(cs.decrypt(c5), [a * 3 for a in t1], rtol=1e-2)
 assert np.allclose(cs.decrypt(c6), [a * b for a, b in zip(t1, t3)], rtol=1e-2)
 ```
 
-### Vector Similarity Search with PHE
-
-Many machine learning models rely on a two-tower architecture, including facial recognition, reverse image search, recommendation engines, large language models, and more. In this setup, user and item inputs are separately mapped to vector embeddings.
-
-For example, suppose all facial embeddings in your database are encrypted on-prem in advance. When verifying an identity, the attempted facial embedding is generated on an edge device or in the cloud. You can compute the encrypted similarity by performing a dot product between the encrypted vector and the plain vector, ensuring secure comparison without decrypting sensitive data. Only additively homomorphic cryptosystems offer encrypted similarity calculation.
-
-```python
-# define a plain vectors for source and target
-alpha = [7.1, 5.2, 5.3, 2.4, 3.5, 4.6]  # On-prem vector (user tower)
-beta = [5.6, 3.7, 2.8, 4, 0, 5.9]  # Cloud vector (item tower)
-expected_similarity = sum(x * y for x, y in zip(alpha, beta))
-
-# build an additively homomorphic cryptosystem (e.g. Paillier) on-prem
-cs = LightPHE(algorithm_name = "Paillier", precision = 19)
-
-# export keys
-cs.export_keys("secret.txt")
-cs.export_keys("public.txt", public=True)
-
-# encrypt source embedding
-encrypted_alpha = cs.encrypt(alpha)
-
-# remove cryptosystem and plain alpha not to be leaked in cloud
-del cs, alpha
-
-# restore the cryptosystem in cloud with only public key
-cloud_cs = LightPHE(algorithm_name = "Paillier", precision = 19, key_file = "public.txt")
-
-# dot product of encrypted and plain embedding pair
-encrypted_cosine_similarity = encrypted_alpha @ beta
-
-# computed by the cloud but cloud cannot decrypt it
-with pytest.raises(ValueError, match="must have private key"):
-    cloud_cs.decrypt(encrypted_cosine_similarity)
-
-# restore the cryptosystem on-prem with secret key
-cs = LightPHE(algorithm_name = "Paillier", precision = 19, key_file = "secret.txt")
-
-# decrypt similarity (on prem)
-calculated_similarity = cs.decrypt(encrypted_cosine_similarity)[0]
-
-# proof of work
-assert abs(calculated_similarity - expected_similarity) < 1e-2
-```
-
-## Security Concerns and Considerations
-
-While LightPHE enables encryption using public keys and supports homomorphic operations on encrypted data, it's important to understand a subtle but critical security implication of this approach. Since the it is homomorphic, the cloud (or any third-party processor) can perform computations without knowing the plaintext. However, a malicious actor can still encrypt arbitrary values and craft valid ciphertexts because encryption depends on your public key and it is publicly known. For example, even if a salary is encrypted, an attacker could encrypt 500 USD using your public key and update the encrypted salary with this forged ciphertext — without needing to know the original value.
-
-To mitigate this, we recommend combining LightPHE with digital signature schemes. By keeping a signed audit trail of update operations in a separate log table, you can detect and reject unauthorized changes, and even restore the original data in case of tampering. We suggest checking out [`LightDSA`](https://github.com/serengil/LightDSA), which provides a lightweight cryptographic interface similar to LightPHE and supports popular digital signature algorithms like RSA, DSA, ECDSA, and EdDSA.
-
 # Contributing
 
 All PRs are more than welcome! If you are planning to contribute a large patch, please create an issue first to get any upfront questions or design decisions out of the way first.

{lightphe-0.0.16 → lightphe-0.0.17}/lightphe/__init__.py

@@ -38,7 +38,7 @@ from lightphe.cryptosystems.EllipticCurveElGamal import EllipticCurveElGamal
 
 logger = Logger(module="lightphe/__init__.py")
 
-VERSION = "0.0.16"
+VERSION = "0.0.17"
 
 
 class LightPHE: