diff --git a/README.md b/README.md index 6e790f6..7b5847c 100644 --- a/README.md +++ b/README.md @@ -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, @@ -27,18 +27,17 @@ 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 @@ -46,14 +45,14 @@ 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 @@ -61,78 +60,31 @@ If you want to use a language other than Python, you can modify the Dockerfile t ## 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 USER_EMAIL=user123@gmail.com \ -my-proof + --rm \ + --volume $(pwd)/input:/input \ + --volume $(pwd)/output:/output \ + --env USER_EMAIL=user123@gmail.com \ + 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 USER_EMAIL=user123@gmail.com \ -gsc-my-proof + --rm \ + --volume /path/to/input:/input \ + --volume /path/to/output:/output \ + --env USER_EMAIL=user123@gmail.com \ + my-proof ``` Remember to populate the `/input` directory with the files you want to process. @@ -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