Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A suggestion for this text: Update README.md #13

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

A suggestion for this text: Update README.md #13

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 27 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This template provides a basic structure for building proof tasks that:
"authenticity": 1.0, // A score between 0 and 1 to rate if the file has been tampered with
"ownership": 1.0, // A score between 0 and 1 to verify the ownership of the file
"quality": 0.6024096385542169, // A score between 0 and 1 to show the quality of the file
"uniqueness": 0, // A score between 0 and 1 to show unique the file is, compared to others in the DLP
"uniqueness": 0, // A score between 0 and 1 to show how unique the file is, compared to others in the DLP
"attributes": { // Custom attributes that can be added to the proof to provide extra context about the encrypted file
"total_score": 0.5,
"score_threshold": 0.83,
Expand All @@ -27,112 +27,64 @@ This template provides a basic structure for building proof tasks that:
}
```

The project is designed to work with [Gramine](https://gramine.readthedocs.io/en/latest/), a lightweight library OS that enables running unmodified applications in secure enclaves, such as Intel SGX (Software Guard Extensions). This allows the code to run in a trusted execution environment, ensuring confidentiality and integrity of the computation.
The project is designed to work with Intel TDX (Trust Domain Extensions), providing hardware-level isolation and security guarantees for confidential computing workloads.

## Project Structure

- `my_proof/`: Contains the main proof logic
- `proof.py`: Implements the proof generation logic
- `__main__.py`: Entry point for the proof execution
- `proof.py`: Implements the proof generation logic
- `__main__.py`: Entry point for the proof execution
- `models/`: Data models for the proof system
- `demo/`: Contains sample input and output for testing
- `.github/workflows/`: CI/CD pipeline for building and releasing
- `Dockerfile`: Defines the container image for the proof task
- `my-proof.manifest.template`: Gramine manifest template for running securely in an Intel SGX enclave
- `config.yaml`: Configuration file for Gramine Shielded Containers (GSC)
- `requirements.txt`: Python package dependencies

## Getting Started

To use this template:

1. Fork this repository
2. Modify the `my_proof/proof.py` file to implement your specific proof logic
3. Update the `my-proof.manifest.template` if you need to add any additional files or change the configuration
3. Update the project dependencies in `requirements.txt` if needed
4. Commit your changes and push to your repository

## Customizing the Proof Logic

The main proof logic is implemented in `my_proof/proof.py`. To customize it, update the `Proof.generate()` function to change how input files are processed.

The proof can be configured using environment variables. When running in an enclave, the environment variables must be defined in the `my-proof.manifest.template` file as well. The following environment variables are used for this demo proof:
The proof can be configured using environment variables:

- `USER_EMAIL`: The email address of the data contributor, to verify data ownership

If you want to use a language other than Python, you can modify the Dockerfile to install the necessary dependencies and build the proof task in the desired language.

## Local Development

To run the proof locally, without Gramine, you can use Docker:
To run the proof locally for testing, you can use Docker:

```
```bash
docker build -t my-proof .
docker run \
--rm \
--volume $(pwd)/demo/sealed:/sealed \
--volume $(pwd)/demo/input:/input \
--volume $(pwd)/demo/output:/output \
--env [email protected] \
my-proof
--rm \
--volume $(pwd)/input:/input \
--volume $(pwd)/output:/output \
--env [email protected] \
my-proof
```

## Building and Releasing

This template includes a GitHub Actions workflow that automatically:

1. Builds a Docker image with your code
2. Creates a Gramine-shielded container (GSC) image
3. Publishes the GSC image as a GitHub release

**Important:** To use this workflow, you must generate a signing key and add it to your GitHub secrets. Follow these steps:

1. Generate a signing key (see instructions below)
2. Add the key as a GitHub secret named `SIGNING_KEY`
3. Push your changes to the `main` branch or create a pull request

### Generating the Gramine Signing Key (Required)

Before building and signing your graminized Docker image, you must generate a signing key. This key is crucial for creating secure SGX enclaves. Here's how to generate it:

1. If you have Gramine installed:

```
gramine-sgx-gen-private-key enclave-key.pem
```

2. If you don't have Gramine, use OpenSSL:
## Running with Intel TDX

```
openssl genrsa -3 -out enclave-key.pem 3072
```
Intel TDX (Trust Domain Extensions) provides hardware-based memory encryption and integrity protection for virtual machines. To run this container in a TDX-enabled environment, follow your infrastructure provider's specific instructions for deploying confidential containers.

After generating the key:
Common volume mounts and environment variables:

1. Keep this key secure, as it will be used to sign your enclaves.
2. Add the contents of `enclave-key.pem` as a GitHub secret named `SIGNING_KEY`.

This key is essential for the `gsc sign-image` step in the GSC workflow.

## Running with SGX

Intel SGX (Software Guard Extensions) is a set of security-related instruction codes built into modern Intel CPUs. It allows parts of a program to be executed in a secure enclave, isolated from the rest of the system.

To load a released image with docker, copy the URL from the release and run:

```
curl -L https://address/of/gsc-my-proof.tar.gz | docker load
```

To run the image:

```
```bash
docker run \
--rm \
--volume /gsc-my-proof/input:/input \
--volume /gsc-my-proof/output:/output \
--device /dev/sgx_enclave:/dev/sgx_enclave \
--volume /var/run/aesmd:/var/run/aesmd \
--volume /mnt/gsc-my-proof/sealed:/sealed \
--env [email protected] \
gsc-my-proof
--rm \
--volume /path/to/input:/input \
--volume /path/to/output:/output \
--env [email protected] \
my-proof
```

Remember to populate the `/input` directory with the files you want to process.
Expand All @@ -141,10 +93,9 @@ Remember to populate the `/input` directory with the files you want to process.

This template leverages several security features:

1. **Secure Enclaves**: The proof runs inside an SGX enclave, isolating it from the rest of the system.
2. **Encrypted Storage**: The `/sealed` directory is automatically encrypted/decrypted by Gramine, providing secure storage for sensitive data.
3. **Input/Output Isolation**: Input and output directories are mounted separately, ensuring clear data flow boundaries.
4. **Minimal Attack Surface**: The Gramine manifest limits the files and resources accessible to the enclave, reducing potential vulnerabilities.
1. **Hardware-based Isolation**: The proof runs inside a TDX-protected environment, isolating it from the rest of the system
2. **Input/Output Isolation**: Input and output directories are mounted separately, ensuring clear data flow boundaries
3. **Minimal Container**: Uses a minimal Python base image to reduce attack surface

## Customization

Expand Down