lightphe 0.0.8__tar.gz → 0.0.10__tar.gz

{lightphe-0.0.8 → lightphe-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lightphe
-Version: 0.0.8
+Version: 0.0.10
 Summary: A Lightweight Partially Homomorphic Encryption Library for Python
 Home-page: https://github.com/serengil/LightPHE
 Author: Sefik Ilkin Serengil
@@ -36,7 +36,7 @@ License-File: LICENSE
 
 <p align="center"><img src="https://raw.githubusercontent.com/serengil/LightPHE/master/icons/phi.png" width="200" height="240"></p>
 
-LightPHE is a lightweight partially homomorphic encryption library for python. It is a hybrid homomoprhic encryption library wrapping many schemes such as [`RSA`](https://sefiks.com/2023/03/06/a-step-by-step-partially-homomorphic-encryption-example-with-rsa-in-python/), [`ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Exponential ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Elliptic Curve ElGamal`](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/), [`Paillier`](https://sefiks.com/2023/04/03/a-step-by-step-partially-homomorphic-encryption-example-with-paillier-in-python/), [`Damgard-Jurik`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-damgard-jurik-in-python/), [`Okamoto–Uchiyama`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-okamoto-uchiyama-in-python/), [`Benaloh`](https://sefiks.com/2023/10/06/a-step-by-step-partially-homomorphic-encryption-example-with-benaloh-in-python-from-scratch/), [`Naccache–Stern`](https://sefiks.com/2023/10/26/a-step-by-step-partially-homomorphic-encryption-example-with-naccache-stern-in-python/), [`Goldwasser–Micali`](https://sefiks.com/2023/10/27/a-step-by-step-partially-homomorphic-encryption-example-with-goldwasser-micali-in-python/).
+LightPHE is a lightweight partially homomorphic encryption library for python. It is a hybrid homomoprhic encryption library wrapping many schemes such as [`RSA`](https://sefiks.com/2023/03/06/a-step-by-step-partially-homomorphic-encryption-example-with-rsa-in-python/), [`ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Exponential ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Elliptic Curve ElGamal`](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/) ([`Weierstrass`](https://sefiks.com/2016/03/13/the-math-behind-elliptic-curve-cryptography/), [`Koblitz`](sefiks.com/2016/03/13/the-math-behind-elliptic-curves-over-binary-field/) and [`Edwards`](https://sefiks.com/2018/12/19/a-gentle-introduction-to-edwards-curves/) forms), [`Paillier`](https://sefiks.com/2023/04/03/a-step-by-step-partially-homomorphic-encryption-example-with-paillier-in-python/), [`Damgard-Jurik`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-damgard-jurik-in-python/), [`Okamoto–Uchiyama`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-okamoto-uchiyama-in-python/), [`Benaloh`](https://sefiks.com/2023/10/06/a-step-by-step-partially-homomorphic-encryption-example-with-benaloh-in-python-from-scratch/), [`Naccache–Stern`](https://sefiks.com/2023/10/26/a-step-by-step-partially-homomorphic-encryption-example-with-naccache-stern-in-python/), [`Goldwasser–Micali`](https://sefiks.com/2023/10/27/a-step-by-step-partially-homomorphic-encryption-example-with-goldwasser-micali-in-python/).
 
 # Partially vs Fully Homomorphic Encryption
 
@@ -98,7 +98,7 @@ algorithms = [
   "EllipticCurve-ElGamal"
 ]
 
-cs = LightPHE(algorithm_name = algorithms[0])
+phe = LightPHE(algorithm_name = algorithms[0])
 ```
 
 # Encryption & Decryption
@@ -110,10 +110,10 @@ Once you built your cryptosystem, you will be able to encrypt and decrypt messag
 m = 17
 
 # calculate ciphertext
-c = cs.encrypt(m)
+c = phe.encrypt(m)
 
 # proof of work
-assert cs.decrypt(c) == m
+assert phe.decrypt(c) == m
 ```
 
 # Homomorphic Operations
@@ -122,76 +122,90 @@ Once you have the ciphertext, you will be able to perform homomorphic operations
 
 ### On-Prem Encryption
 
-This Python code snippet demonstrates how to generate a private-public key pair using the Paillier cryptosystem via the LightPHE library. First, an instance of the LightPHE class is created with the Paillier algorithm. Then, the public key is exported and saved to a file named "public.txt" to build the same cryptosystem with only public key in the cloud side later. The code defines two plaintext values, m1 and m2, respectively. These plaintext values are encrypted to generate ciphertexts c1 and c2 using the public key. Finally, the ciphertexts c1 and c2 are prepared to be sent to a cloud system for secure processing or storage.
+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.
 
 ```python
-# generate private-public key pair
-cs = LightPHE(algorithm_name = "Paillier")
-
-# export public key to build same cryptosystem with only public key in the cloud
-cs.export_keys(target_file = "public.txt", public = True)
-
-# export private key to build same cryptosystem on-prem later
-cs.export_keys(target_file = "private.txt", public = False)
-
-# define plaintexts
-m1 = 17
-m2 = 23
-
-# calculate ciphertexts
-c1 = cs.encrypt(m1).value
-c2 = cs.encrypt(m2).value
-
-# send c1 and c2 pair to a cloud system
+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
 
-This Python code snippet illustrates how to handle encrypted data on the cloud side using the Paillier cryptosystem with the LightPHE library. Upon receiving the encrypted values c1 and c2, the cloud system initializes the cryptosystem using the exported public key stored in public.txt. To ensure the security of the data, a test is performed to confirm that the cloud system cannot decrypt c1 and c2 without the private key. This is done using the pytest library, which raises a ValueError if decryption is attempted, verifying that decryption is not possible without the private key. Finally, the code demonstrates homomorphic addition by adding the two ciphertexts, resulting in a new ciphertext c3 that represents the encrypted sum of the original plaintext values.
+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.
 
 ```python
-# cloud side receives encrypted c1 and c2
-
-# restore cryptosystem with the exported public key
-cs = LightPHE(algorithm_name = "Paillier", key_file = "public.txt")
-
-# convert c1 and c2 to ciphertext objects
-c1 = cs.create_ciphertext_obj(c1)
-c2 = cs.create_ciphertext_obj(c2)
-
-# confirm that cloud cannot decrypt c1
-with pytest.raises(ValueError, match="You must have private key to perform decryption"):
-  cs.decrypt(c1)
-
-# confirm that cloud cannot decrypt c2
-with pytest.raises(ValueError, match="You must have private key to perform decryption"):
-  cs.decrypt(c2)
-
-# homomorphic addition - private key not required
-c3 = c1 + c2
-
-# confirm that cloud cannot decrypt c3
-with pytest.raises(ValueError, match="You must have private key to perform decryption"):
-  cs.decrypt(c3)
+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
 ```
 
-### On-Prem Decryption
+### On-Prem Decryption And Proof of Work
 
-This Python code snippet demonstrates the final step in a secure computation process using homomorphic encryption with the LightPHE library. After receiving the ciphertext c3 from the cloud, which is the result of homomorphic addition of two ciphertexts c1 and c2, the on-premises system (which has the private key) decrypts c3 to verify the result. The decrypted value is then asserted to be equal to the sum of the original plaintext values m1 and m2. This step ensures the correctness of the homomorphic computation performed by the cloud.
+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.
 
 ```python
-# on-prem side receives c3 from cloud
-
-# restore cryptosystem with the exported private key
-cs = LightPHE(algorithm_name = "Paillier", key_file = "private.txt")
-
 # proof of work - private key required
-assert cs.decrypt(c3) == m1 + m2
+assert phe.decrypt(c3) == m1 + m2
 ```
 
+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.
+
 ### Scalar Multiplication
 
-Besides, Paillier is supporting multiplying ciphertexts by a known plain constant. This Python code snippet demonstrates how to perform scalar multiplication on encrypted data using homomorphic encryption with the LightPHE library. The factor k is set to 1.05, representing a 5% increase. On the cloud side, this factor is used to multiply the ciphertext c1, resulting in a new ciphertext c4. When the on-premises system, which holds the private key, receives c4, it decrypts it and verifies that the decrypted value matches the original plaintext m1 scaled by k (i.e., 1.05 * m1). This ensures that the homomorphic scalar multiplication was performed correctly on the encrypted data.
+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.
 
 ```python
 # increasing something 5%
@@ -201,7 +215,7 @@ k = 1.05
 c4 = k * c1
 
 # proof of work on-prem - private key is required
-assert cs.decrypt(c4) == k * m1
+assert phe.decrypt(c4) == k * m1
 ```
 
 ### Ciphertext Regeneration
@@ -209,10 +223,10 @@ assert cs.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 = cs.regenerate_ciphertext(c1)
+c1_prime = phe.regenerate_ciphertext(c1)
 assert c1_prime.value != c1.value
-assert cs.decrypt(c1_prime) == m1
-assert cs.decrypt(c1) == m1
+assert phe.decrypt(c1_prime) == m1
+assert phe.decrypt(c1) == m1
 ```
 
 ### Unsupported Operations
@@ -231,50 +245,31 @@ with pytest.raises(ValueError, match="Paillier is not homomorphic with respect t
 
 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.
 
-# Working with vectors
+### Elliptic Curve Cryptography
 
-You can encrypt the output vectors of machine learning models with LightPHE. These encrypted tensors come with homomorphic operation support including homomorphic addition, element-wise multiplication and scalar multiplication.
+ECC is a powerful public-key cryptosystem based on the algebraic structure of elliptic curves over finite fields. 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. The library supports 100+ standard elliptic curves.
 
 ```python
-# build an additively homomorphic cryptosystem
-cs = LightPHE(algorithm_name="Paillier")
-
-# define plain tensors
-t1 = [1.005, 2.05, 3.5, 4]
-t2 = [5, 6.2, 7.002, 8.02]
-
-# encrypt tensors
-c1 = cs.encrypt(t1)
-c2 = cs.encrypt(t2)
-
-# perform homomorphic addition
-c3 = c1 + c2
-
-# perform homomorphic element-wise multiplication
-c4 = c1 * c2
-
-# perform homomorphic scalar multiplication
-k = 5
-c5 = k * c1
+some_curves = [
+    {"form": "weierstrass", "curve": "secp256k1"},
+    {"form": "edwards", "curve": "ed25519"},
+    {"form": "koblitz", "curve": "k163"}
+]
 
-# decrypt the addition tensor
-t3 = cs.decrypt(c3)
+curve = some_curves[1]
 
-# decrypt the element-wise multiplied tensor
-t4 = cs.decrypt(c4)
+phe = LightPHE(
+    algorithm_name="EllipticCurve-ElGamal",
+    form=curve["form"],
+    curve=curve["curve"],
+)
+```
 
-# decrypt the scalar multiplied tensor
-t5 = cs.decrypt(c5)
+One of the crucial factors that define the security level of an elliptic curve cryptosystem is the order of the curve. The order of a curve is the number of points on the curve, and it directly influences the strength of the encryption. A higher order typically corresponds to a stronger cryptosystem, making it more resistant to cryptographic attacks.
 
-# data validations
-threshold = 0.5
-for i in range(0, len(t1)):
-   assert abs((t1[i] + t2[i]) - t3[i]) < threshold
-   assert abs((t1[i] * t2[i]) - t4[i]) < threshold
-   assert abs((t1[i] * k) - t5[i]) < threshold
-```
+Each curve in LightPHE has a specific order, which is carefully chosen to balance performance and security. By selecting an elliptic curve with a larger order, you increase the security of your cryptographic system, but this may come with a trade-off in computational efficiency. Therefore, choosing the appropriate curve order is a crucial decision based on your application’s security and performance requirements.
 
-Unfortunately, vector multiplication (dot product) requires both homomorphic addition and homomorphic multiplication and this cannot be done with partially homomorphic encryption algorithms.
+See [`Curves`](https://github.com/serengil/LightPHE/tree/master/lightphe/elliptic_curve_forms) page for more details.
 
 # Contributing
 

{lightphe-0.0.8 → lightphe-0.0.10}/README.md

@@ -20,7 +20,7 @@
 
 <p align="center"><img src="https://raw.githubusercontent.com/serengil/LightPHE/master/icons/phi.png" width="200" height="240"></p>
 
-LightPHE is a lightweight partially homomorphic encryption library for python. It is a hybrid homomoprhic encryption library wrapping many schemes such as [`RSA`](https://sefiks.com/2023/03/06/a-step-by-step-partially-homomorphic-encryption-example-with-rsa-in-python/), [`ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Exponential ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Elliptic Curve ElGamal`](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/), [`Paillier`](https://sefiks.com/2023/04/03/a-step-by-step-partially-homomorphic-encryption-example-with-paillier-in-python/), [`Damgard-Jurik`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-damgard-jurik-in-python/), [`Okamoto–Uchiyama`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-okamoto-uchiyama-in-python/), [`Benaloh`](https://sefiks.com/2023/10/06/a-step-by-step-partially-homomorphic-encryption-example-with-benaloh-in-python-from-scratch/), [`Naccache–Stern`](https://sefiks.com/2023/10/26/a-step-by-step-partially-homomorphic-encryption-example-with-naccache-stern-in-python/), [`Goldwasser–Micali`](https://sefiks.com/2023/10/27/a-step-by-step-partially-homomorphic-encryption-example-with-goldwasser-micali-in-python/).
+LightPHE is a lightweight partially homomorphic encryption library for python. It is a hybrid homomoprhic encryption library wrapping many schemes such as [`RSA`](https://sefiks.com/2023/03/06/a-step-by-step-partially-homomorphic-encryption-example-with-rsa-in-python/), [`ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Exponential ElGamal`](https://sefiks.com/2023/03/27/a-step-by-step-partially-homomorphic-encryption-example-with-elgamal-in-python/), [`Elliptic Curve ElGamal`](https://sefiks.com/2018/08/21/elliptic-curve-elgamal-encryption/) ([`Weierstrass`](https://sefiks.com/2016/03/13/the-math-behind-elliptic-curve-cryptography/), [`Koblitz`](sefiks.com/2016/03/13/the-math-behind-elliptic-curves-over-binary-field/) and [`Edwards`](https://sefiks.com/2018/12/19/a-gentle-introduction-to-edwards-curves/) forms), [`Paillier`](https://sefiks.com/2023/04/03/a-step-by-step-partially-homomorphic-encryption-example-with-paillier-in-python/), [`Damgard-Jurik`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-damgard-jurik-in-python/), [`Okamoto–Uchiyama`](https://sefiks.com/2023/10/20/a-step-by-step-partially-homomorphic-encryption-example-with-okamoto-uchiyama-in-python/), [`Benaloh`](https://sefiks.com/2023/10/06/a-step-by-step-partially-homomorphic-encryption-example-with-benaloh-in-python-from-scratch/), [`Naccache–Stern`](https://sefiks.com/2023/10/26/a-step-by-step-partially-homomorphic-encryption-example-with-naccache-stern-in-python/), [`Goldwasser–Micali`](https://sefiks.com/2023/10/27/a-step-by-step-partially-homomorphic-encryption-example-with-goldwasser-micali-in-python/).
 
 # Partially vs Fully Homomorphic Encryption
 
@@ -82,7 +82,7 @@ algorithms = [
   "EllipticCurve-ElGamal"
 ]
 
-cs = LightPHE(algorithm_name = algorithms[0])
+phe = LightPHE(algorithm_name = algorithms[0])
 ```
 
 # Encryption & Decryption
@@ -94,10 +94,10 @@ Once you built your cryptosystem, you will be able to encrypt and decrypt messag
 m = 17
 
 # calculate ciphertext
-c = cs.encrypt(m)
+c = phe.encrypt(m)
 
 # proof of work
-assert cs.decrypt(c) == m
+assert phe.decrypt(c) == m
 ```
 
 # Homomorphic Operations
@@ -106,76 +106,90 @@ Once you have the ciphertext, you will be able to perform homomorphic operations
 
 ### On-Prem Encryption
 
-This Python code snippet demonstrates how to generate a private-public key pair using the Paillier cryptosystem via the LightPHE library. First, an instance of the LightPHE class is created with the Paillier algorithm. Then, the public key is exported and saved to a file named "public.txt" to build the same cryptosystem with only public key in the cloud side later. The code defines two plaintext values, m1 and m2, respectively. These plaintext values are encrypted to generate ciphertexts c1 and c2 using the public key. Finally, the ciphertexts c1 and c2 are prepared to be sent to a cloud system for secure processing or storage.
+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.
 
 ```python
-# generate private-public key pair
-cs = LightPHE(algorithm_name = "Paillier")
-
-# export public key to build same cryptosystem with only public key in the cloud
-cs.export_keys(target_file = "public.txt", public = True)
-
-# export private key to build same cryptosystem on-prem later
-cs.export_keys(target_file = "private.txt", public = False)
-
-# define plaintexts
-m1 = 17
-m2 = 23
-
-# calculate ciphertexts
-c1 = cs.encrypt(m1).value
-c2 = cs.encrypt(m2).value
-
-# send c1 and c2 pair to a cloud system
+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
 
-This Python code snippet illustrates how to handle encrypted data on the cloud side using the Paillier cryptosystem with the LightPHE library. Upon receiving the encrypted values c1 and c2, the cloud system initializes the cryptosystem using the exported public key stored in public.txt. To ensure the security of the data, a test is performed to confirm that the cloud system cannot decrypt c1 and c2 without the private key. This is done using the pytest library, which raises a ValueError if decryption is attempted, verifying that decryption is not possible without the private key. Finally, the code demonstrates homomorphic addition by adding the two ciphertexts, resulting in a new ciphertext c3 that represents the encrypted sum of the original plaintext values.
+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.
 
 ```python
-# cloud side receives encrypted c1 and c2
-
-# restore cryptosystem with the exported public key
-cs = LightPHE(algorithm_name = "Paillier", key_file = "public.txt")
-
-# convert c1 and c2 to ciphertext objects
-c1 = cs.create_ciphertext_obj(c1)
-c2 = cs.create_ciphertext_obj(c2)
-
-# confirm that cloud cannot decrypt c1
-with pytest.raises(ValueError, match="You must have private key to perform decryption"):
-  cs.decrypt(c1)
-
-# confirm that cloud cannot decrypt c2
-with pytest.raises(ValueError, match="You must have private key to perform decryption"):
-  cs.decrypt(c2)
-
-# homomorphic addition - private key not required
-c3 = c1 + c2
-
-# confirm that cloud cannot decrypt c3
-with pytest.raises(ValueError, match="You must have private key to perform decryption"):
-  cs.decrypt(c3)
+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
 ```
 
-### On-Prem Decryption
+### On-Prem Decryption And Proof of Work
 
-This Python code snippet demonstrates the final step in a secure computation process using homomorphic encryption with the LightPHE library. After receiving the ciphertext c3 from the cloud, which is the result of homomorphic addition of two ciphertexts c1 and c2, the on-premises system (which has the private key) decrypts c3 to verify the result. The decrypted value is then asserted to be equal to the sum of the original plaintext values m1 and m2. This step ensures the correctness of the homomorphic computation performed by the cloud.
+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.
 
 ```python
-# on-prem side receives c3 from cloud
-
-# restore cryptosystem with the exported private key
-cs = LightPHE(algorithm_name = "Paillier", key_file = "private.txt")
-
 # proof of work - private key required
-assert cs.decrypt(c3) == m1 + m2
+assert phe.decrypt(c3) == m1 + m2
 ```
 
+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.
+
 ### Scalar Multiplication
 
-Besides, Paillier is supporting multiplying ciphertexts by a known plain constant. This Python code snippet demonstrates how to perform scalar multiplication on encrypted data using homomorphic encryption with the LightPHE library. The factor k is set to 1.05, representing a 5% increase. On the cloud side, this factor is used to multiply the ciphertext c1, resulting in a new ciphertext c4. When the on-premises system, which holds the private key, receives c4, it decrypts it and verifies that the decrypted value matches the original plaintext m1 scaled by k (i.e., 1.05 * m1). This ensures that the homomorphic scalar multiplication was performed correctly on the encrypted data.
+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.
 
 ```python
 # increasing something 5%
@@ -185,7 +199,7 @@ k = 1.05
 c4 = k * c1
 
 # proof of work on-prem - private key is required
-assert cs.decrypt(c4) == k * m1
+assert phe.decrypt(c4) == k * m1
 ```
 
 ### Ciphertext Regeneration
@@ -193,10 +207,10 @@ assert cs.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 = cs.regenerate_ciphertext(c1)
+c1_prime = phe.regenerate_ciphertext(c1)
 assert c1_prime.value != c1.value
-assert cs.decrypt(c1_prime) == m1
-assert cs.decrypt(c1) == m1
+assert phe.decrypt(c1_prime) == m1
+assert phe.decrypt(c1) == m1
 ```
 
 ### Unsupported Operations
@@ -215,50 +229,31 @@ with pytest.raises(ValueError, match="Paillier is not homomorphic with respect t
 
 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.
 
-# Working with vectors
+### Elliptic Curve Cryptography
 
-You can encrypt the output vectors of machine learning models with LightPHE. These encrypted tensors come with homomorphic operation support including homomorphic addition, element-wise multiplication and scalar multiplication.
+ECC is a powerful public-key cryptosystem based on the algebraic structure of elliptic curves over finite fields. 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. The library supports 100+ standard elliptic curves.
 
 ```python
-# build an additively homomorphic cryptosystem
-cs = LightPHE(algorithm_name="Paillier")
-
-# define plain tensors
-t1 = [1.005, 2.05, 3.5, 4]
-t2 = [5, 6.2, 7.002, 8.02]
-
-# encrypt tensors
-c1 = cs.encrypt(t1)
-c2 = cs.encrypt(t2)
-
-# perform homomorphic addition
-c3 = c1 + c2
-
-# perform homomorphic element-wise multiplication
-c4 = c1 * c2
-
-# perform homomorphic scalar multiplication
-k = 5
-c5 = k * c1
+some_curves = [
+    {"form": "weierstrass", "curve": "secp256k1"},
+    {"form": "edwards", "curve": "ed25519"},
+    {"form": "koblitz", "curve": "k163"}
+]
 
-# decrypt the addition tensor
-t3 = cs.decrypt(c3)
+curve = some_curves[1]
 
-# decrypt the element-wise multiplied tensor
-t4 = cs.decrypt(c4)
+phe = LightPHE(
+    algorithm_name="EllipticCurve-ElGamal",
+    form=curve["form"],
+    curve=curve["curve"],
+)
+```
 
-# decrypt the scalar multiplied tensor
-t5 = cs.decrypt(c5)
+One of the crucial factors that define the security level of an elliptic curve cryptosystem is the order of the curve. The order of a curve is the number of points on the curve, and it directly influences the strength of the encryption. A higher order typically corresponds to a stronger cryptosystem, making it more resistant to cryptographic attacks.
 
-# data validations
-threshold = 0.5
-for i in range(0, len(t1)):
-   assert abs((t1[i] + t2[i]) - t3[i]) < threshold
-   assert abs((t1[i] * t2[i]) - t4[i]) < threshold
-   assert abs((t1[i] * k) - t5[i]) < threshold
-```
+Each curve in LightPHE has a specific order, which is carefully chosen to balance performance and security. By selecting an elliptic curve with a larger order, you increase the security of your cryptographic system, but this may come with a trade-off in computational efficiency. Therefore, choosing the appropriate curve order is a crucial decision based on your application’s security and performance requirements.
 
-Unfortunately, vector multiplication (dot product) requires both homomorphic addition and homomorphic multiplication and this cannot be done with partially homomorphic encryption algorithms.
+See [`Curves`](https://github.com/serengil/LightPHE/tree/master/lightphe/elliptic_curve_forms) page for more details.
 
 # Contributing