Skip to content

Commit

Permalink
docs: improves API and decryption
Browse files Browse the repository at this point in the history
  • Loading branch information
@poppyseedDev
poppyseedDev committed Nov 22, 2024
1 parent ef7edf2 commit 425a339
Show file tree
Hide file tree
Showing 17 changed files with 1,176 additions and 505 deletions.
5 changes: 3 additions & 2 deletions docs/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,11 @@
- [Key concepts and features](getting_started/key_concepts.md)
- [Repositories](getting_started/repositories.md)
- [Whitepaper](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper.pdf)
- [Get started on Ethereum](getting_started/ethereum.md)
- [Get started](getting_started/ethereum.md)
- [Create a smart contract]()
- [Using Hardhat](getting_started/write_contract/hardhat.md)
- [Using Remix](getting_started/write_contract/remix.md)
- [Other development environment](getting_started/write_contract/others.md)
- [Installing packages](getting_started/write_contract/installation.md)

## Fundamentals

Expand All @@ -25,7 +24,9 @@
- [Operations on encrypted types](fundamentals/first_step/operations.md)
- [Encryption](fundamentals/first_step/inputs.md)
- [Decryption](fundamentals/first_step/decrypt.md)
- [Decryption in depth](fundamentals/first_step/decrypt_details.md)
- [Reencryption](fundamentals/first_step/reencryption.md)
- [ACL examples](fundamentals/first_step/acl_examples.md)

## Guides

Expand Down
158 changes: 40 additions & 118 deletions docs/fundamentals/acl.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,24 @@
# **Access Control List (ACL)**
# Access control list (ACL) overview

The Access Control List (ACL) system in fhEVM ensures that only authorized addresses can access or manipulate ciphertexts. This document outlines how ACLs work, their configuration options, and best practices for securing encrypted data in smart contracts.
This document describes the Access Control List (ACL) system in fhEVM, a core feature that governs access to encrypted data. The ACL ensures that only authorized accounts or contracts can interact with specific ciphertexts, preserving confidentiality while enabling composable smart contracts. This overview provides a high-level understanding of what the ACL is, why it's essential, and how it works.

---

## **How ACLs Work**
## What is the ACL?

The ACL is a permission management system designed to control who can access, compute on, or decrypt encrypted values in fhEVM. By defining and enforcing these permissions, the ACL ensures that encrypted data remains secure while still being usable within authorized contexts.

## Why is the ACL important?

Encrypted data in fhEVM is entirely confidential, meaning that without proper access control, even the contract holding the ciphertext cannot interact with it. The ACL enables:

The ACL system controls who can access or manipulate specific ciphertexts stored on the blockchain. It supports two types of allowances:
- **Granular Permissions**: Define specific access rules for individual accounts or contracts.
- **Secure Computations**: Ensure that only authorized entities can manipulate or decrypt encrypted data.
- **Gas Efficiency**: Optimize permissions using transient access for temporary needs, reducing storage and gas costs.


## How does the ACL work?

### Types of access

1. **Permanent Allowance**:
- Configured using `TFHE.allow(ciphertext, address)`.
Expand All @@ -19,133 +31,43 @@ The ACL system controls who can access or manipulate specific ciphertexts stored
- Stored in transient storage, reducing gas costs.
- Ideal for temporary operations like passing ciphertexts to external functions.

**Syntactic Sugar**:
**Syntactic sugar**:
- `TFHE.allowThis(ciphertext)` is shorthand for `TFHE.allow(ciphertext, address(this))`. It authorizes the current contract to reuse a ciphertext handle in future transactions.


## **Transient vs. Permanent Allowance**

| **Allowance Type** | **Purpose** | **Storage Type** | **Use Case** |
|-----------------------|---------------------------------------------------------|-----------------------------|-------------------------------------------------------------------------------|
| **Transient** | Temporary access during a transaction. | [Transient storage](https://eips.ethereum.org/EIPS/eip-1153) (EIP-1153) | Calling external functions or computations with ciphertexts. Use when wanting to save on gas costs. |
| **Permanent** | Long-term access across multiple transactions. | Dedicated contract storage | Persistent ciphertexts for contracts or users requiring ongoing access. |

---


### Example: Function Interaction Using ACLs


Here’s an example illustrating how transient and permanent allowances work in a multi-contract setup:

```solidity
import "fhevm/lib/TFHE.sol";
contract SecretGiver {
SecretStore public secretStore;
### Transient vs. permanent allowance

constructor() {
secretStore = new SecretStore();
}
| **Allowance Type** | **Purpose** | **Storage Type** | **Use Case** |
| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Transient** | Temporary access during a transaction. | [Transient storage](https://eips.ethereum.org/EIPS/eip-1153) (EIP-1153) | Calling external functions or computations with ciphertexts. Use when wanting to save on gas costs. |
| **Permanent** | Long-term access across multiple transactions. | Dedicated contract storage | Persistent ciphertexts for contracts or users requiring ongoing access. |

function giveMySecret() public {
// Create my secret - asEuint16 gives automatically transient allowance for the resulting handle (note: an onchain trivial encryption is not secret)
euint16 mySecret = TFHE.asEuint16(42);

// Allow temporarily the SecretStore contract to manipulate `mySecret`
TFHE.allowTransient(mySecret, address(secretStore));
## Granting and verifying access

// Call `secretStore` with `mySecret`
secretStore.storeSecret(mySecret);
}
}
### Granting access

contract SecretStore {
euint16 public secretResult;
Developers can use functions like `allow`, `allowThis`, and `allowTransient` to grant permissions:

function storeSecret(euint16 callerSecret) public {
// Verify that the caller has also access to this ciphertext
require(TFHE.isSenderAllowed(callerSecret), "The caller is not authorized to access this secret.");
- **`allow`**: Grants permanent access to an address.
- **`allowThis`**: Grants the current contract access to manipulate the ciphertext.
- **`allowTransient`**: Grants temporary access to an address for the current transaction.

// do some FHE computation (result is automatically put in the ACL transient storage)
euint16 computationResult = TFHE.add(callerSecret, 3);
### Verifying access

// then store the resulting ciphertext handle in the contract storage
secretResult = computationResult;
To check if an entity has permission to access a ciphertext, use functions like `isAllowed` or `isSenderAllowed`:

// Make the temporary allowance for this ciphertext permanent to let the contract able to reuse it at a later stage or request a decryption of it
TFHE.allowThis(secretResult); // this is strictly equivalent to `TFHE.allow(secretResult, address(this));``
}
}
```
- **`isAllowed`**: Verifies if a specific address has permission.
- **`isSenderAllowed`**: Simplifies checks for the current transaction sender.

## **Automatic Transient Allowance**

Certain functions automatically grant transient allowances to the calling contract, eliminating the need for manual configuration. These include:

- **Type Conversion Functions**:
- `TFHE.asEuintXX()`, `TFHE.asEaddress()`, `TFHE.asEbool()`.
- **Random Number Generation**:
- `TFHE.randXX()`.
- **Computation Results**:
- Operations such as `TFHE.add()`, `TFHE.select()`.

### Example: Random Value Generation with Transient Allowance

```solidity
function randomize() public {
// Generate a random encrypted value with transient allowance
euint64 random = TFHE.randEuint64();
// Convert the transient allowance into a permanent one
TFHE.allowThis(random);
}
```

## Security Best Practices: Verifying Access with `isSenderAllowed()`

When a function receives a ciphertext (such as `ebool`, `euint8`, `eaddress`, ...), it needs to verify that the sender also has access to this ciphertext. This verification is crucial for security.

Without this check, a contract could send any ciphertext authorized for the contract and potentially exploit the function to retrieve the value. For example, an attacker could transfer someone's balance as an encrypted amount.

If the function does not include `require(TFHE.isSenderAllowed(encryptedAmount))`, an attacker who doesn't have access to this balance could determine the value by transferring the balance between two well-funded accounts.

### Example: Secure Verification
```solidity
function transfer(address to, euint64 encryptedAmount, bytes calldata inputProof) public {
// Ensure the sender is authorized to access the encrypted amount
require(TFHE.isSenderAllowed(encryptedAmount), "Unauthorized access to encrypted amount.");
// Proceed with further logic
euint64 amount = TFHE.asEuint64(encryptedAmount);
...
}
```

## ACL for reencryption

If a ciphertext must be reencrypted by a user, then explicit access must be granted to them. If this authorization is not given, the user will be unable to request a reencryption of this ciphertext.

Due to the reencryption mechanism, a user signs a public key associated with a specific contract; therefore, the ciphertext also needs to be allowed for the contract.
---

## Practical uses of the acl

### Example: Secure Transfer in Encrypted ERC-20
```solidity
function transfer(address to, euint64 encryptedAmount) public {
require(TFHE.isSenderAllowed(encryptedAmount), "The caller is not authorized to access this encrypted amount.");
euint64 amount = TFHE.asEuint64(encryptedAmount);
ebool canTransfer = TFHE.le(amount, balances[msg.sender]);
- **Confidential Parameters**: Pass encrypted values securely between contracts, ensuring only authorized entities can access them.
- **Secure Stte Management**: Store encrypted state variables while controlling who can modify or read them.
- **Privacy-Preserving Computations**: Enable computations on encrypted data with confidence that permissions are enforced.

euint64 newBalanceTo = TFHE.add(balances[to], TFHE.select(canTransfer, amount, TFHE.asEuint64(0)));
balances[to] = newBalanceTo;
// Allow this new balance for both the contract and the owner.
TFHE.allowThis(newBalanceTo);
TFHE.allow(newBalanceTo, to);
---

euint64 newBalanceFrom = TFHE.sub(balances[from], TFHE.select(canTransfer, amount, TFHE.asEuint64(0)));
balances[from] = newBalanceFrom;
// Allow this new balance for both the contract and the owner.
TFHE.allowThis(newBalanceFrom);
TFHE.allow(newBalanceFrom, from);
}
```
For a detailed explanation of the ACL's functionality, including code examples and advanced configurations, see [working with the acl](acl-usage.md).
34 changes: 16 additions & 18 deletions docs/fundamentals/architecture_overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,19 +46,17 @@ However, integrating a standalone FHE library like TFHE-rs into a blockchain env
### **2.2 Challenges in blockchain integration**
Integrating FHE into blockchain systems posed several challenges that needed to be addressed to achieve the goals of confidentiality, composability, and scalability:

1. **Transparency and Privacy**: Blockchains are inherently transparent, where all on-chain data is publicly visible. FHE solves this by keeping all sensitive data encrypted, ensuring privacy without sacrificing usability.
2. **Public Verifiability**: On-chain computations need to be verifiable by all participants. This required a mechanism to confirm the correctness of encrypted computations without revealing their inputs or outputs.
1. **Transparency and privacy**: Blockchains are inherently transparent, where all on-chain data is publicly visible. FHE solves this by keeping all sensitive data encrypted, ensuring privacy without sacrificing usability.
2. **Public verifiability**: On-chain computations need to be verifiable by all participants. This required a mechanism to confirm the correctness of encrypted computations without revealing their inputs or outputs.
3. **Composability**: Smart contracts needed to interact seamlessly with each other, even when operating on encrypted data.
4. **Performance and Scalability**: FHE computations are resource-intensive, and blockchain systems require high throughput to remain practical.
4. **Performance and scalability**: FHE computations are resource-intensive, and blockchain systems require high throughput to remain practical.


To overcome these challenges, Zama introduced a hybrid architecture for fhEVM that combines:

- **On-chain** functionality for managing state and enforcing access controls.
- **Off-chain** processing via a coprocessor to execute resource-intensive FHE computations.



## **3 fhEVM components overview**

The fhEVM architecture is built around four primary components, each contributing to the system's functionality and performance. These components work together to enable the development and execution of private, composable smart contracts on EVM-compatible blockchains. Below is an overview of these components and their responsibilities:
Expand All @@ -79,10 +77,10 @@ The fhEVM architecture is built around four primary components, each contributin

As a developer working with fhEVM, your workflow typically involves two key elements:

1. **Frontend Development**:
1. **Frontend development**:
You create a frontend interface for users to interact with your confidential application. This includes encrypting inputs using the public FHE key and submitting them to the blockchain.

2. **Smart Contract Development**:
2. **Smart contract development**:
You write Solidity contracts deployed on the same blockchain as the fhEVM smart contracts. These contracts leverage the `TFHE.sol` library to perform operations on encrypted data. Below, we explore the major components involved.

---
Expand Down Expand Up @@ -113,7 +111,7 @@ The coprocessor is the backbone for handling computationally intensive FHE tasks

#### **Key functions**:
1. **Execution**: Performs operations such as addition, multiplication, and comparison on encrypted data.
2. **Ciphertext Management**: Stores encrypted inputs, states, and outputs securely, either off-chain or in a dedicated on-chain database.
2. **Ciphertext management**: Stores encrypted inputs, states, and outputs securely, either off-chain or in a dedicated on-chain database.

---

Expand All @@ -122,9 +120,9 @@ The coprocessor is the backbone for handling computationally intensive FHE tasks
The Gateway acts as the bridge between the blockchain, coprocessor, and KMS.

#### **Key functions**:
- **API for Developers**: Exposes endpoints for submitting encrypted inputs, retrieving outputs, and managing ciphertexts.
- **Proof Validation**: Forwards ZKPoKs to the KMS for verification.
- **Off-chain Coordination**: Relays encrypted data and computation results between on-chain and off-chain systems.
- **API for developers**: Exposes endpoints for submitting encrypted inputs, retrieving outputs, and managing ciphertexts.
- **Proof validation**: Forwards ZKPoKs to the KMS for verification.
- **Off-chain coordination**: Relays encrypted data and computation results between on-chain and off-chain systems.

The Gateway simplifies the development process by abstracting the complexity of cryptographic operations.

Expand All @@ -135,16 +133,16 @@ The Gateway simplifies the development process by abstracting the complexity of
The KMS securely manages the cryptographic backbone of fhEVM by maintaining and distributing the global FHE keys.

#### **Key functions**:
- **Threshold Decryption**: Uses Multi-Party Computation (MPC) to securely decrypt ciphertexts without exposing the private key to any single entity.
- **ZKPoK Validation**: Verifies proofs of plaintext knowledge to ensure that encrypted inputs are valid.
- **Key Distribution**: Maintains the global FHE keys, which include:
- **Public Key**: Used for encrypting data (accessible to the frontend and smart contracts).
- **Private Key**: Stored securely in the KMS and used for decryption.
- **Evaluation Key**: Used by the coprocessor to perform FHE computations.
- **Threshold decryption**: Uses Multi-Party Computation (MPC) to securely decrypt ciphertexts without exposing the private key to any single entity.
- **ZKPoK validation**: Verifies proofs of plaintext knowledge to ensure that encrypted inputs are valid.
- **Key distribution**: Maintains the global FHE keys, which include:
- **Public key**: Used for encrypting data (accessible to the frontend and smart contracts).
- **Private key**: Stored securely in the KMS and used for decryption.
- **Evaluation key**: Used by the coprocessor to perform FHE computations.

The KMS ensures robust cryptographic security, preventing single points of failure and maintaining public verifiability.


---

In the next section, we will dive deeper into encryption, re-encryption, and decryption processes, including how they interact with the KMS and Gateway services. For more details, see [Decrypt and re-encrypt](decrypt.md).
In the next section, we will dive deeper into encryption, re-encryption, and decryption processes, including how they interact with the KMS and Gateway services. For more details, see [Decrypt and re-encrypt](./d_re_ecrypt_compute.md).
Loading

0 comments on commit 425a339

Please sign in to comment.