PVRA Template

About The Project

PVRA (Publically Verifiable Remote Attestation) aims to provide a framework for developers to bootstrap a range of auditting capabilities and security properties for their enclave based applications that are otherwise vulnerable.

The goal of this template is to provide a clean interface with PVRA framework components and an intuitive means of writing these applications. We have four example applications to showcase: VirtualStatusCard, HeatMap, EVoting, and SecureDataTransfer. To browse the trace of a PVRA application refer to ./applications/. VSC is currently at 229 LoC and HeatMap at 205 LoC.

Quick Start

Run an existing application in docker without CCF in SGX simulation mode

• set Environment variables

export PROJECT_ROOT=$(pwd)
export CCF_ENABLE=0
export SGX_SPID=None
export IAS_PRIMARY_KEY=None
export APP_NAME=<sdt or heatmap or vsc>
export SGX_MODE=SW

• Set NUM_USERS

  • sdt functionality tests requires 5 users: export NUM_USERS=5
  • heatmap expects 4 users export NUM_USERS=4
  • vsc expects 8 users: export NUM_USERS=8

• build and run docker image

cd $PROJECT_ROOT
./setup.sh -a $APP_NAME
cd $PROJECT_ROOT/docker
./build.sh
./run.sh

Getting Started

How to write a PVRA application:

There are three application-specific files that need to be modified for implementing an application.

1. appPVRA.h This is the header file for the application; it defines the types of commands the enclave processes, the structure of command inputs/outputs, and the structure of application data.

2. appPVRA.c This is enclave executable application code. Every command should have an associated execution kernel. There are two auxillary functions that are required:

   • initES() initializes the application data structures
   • write application commands and set NUM_COMMANDS
     • must use function signature struct cResponse pvraCommandName(struct ES *enclave_state, struct cInputs *CI, uint32_t uidx)
     • optional: add admin specific commands by defining NUM_ADMIN_COMMANDS in appPVRA.h and initializing them to the end of function list
   • initFP() which associates functions to enumerated commands (COMMAND₀-COMMAND_{NUM_COMMANDS+NUM_ADMIN_COMMANDS});
   • optional: user accounts auditing with merkle tree by setting #define MERKLE_TREE in appPVRA.h
     • get_user_leaf generate a list of leaf nodes structs for each user account. Each leaf node should contain uidx field cooresponding to the uidx input into PVRA commands.

3. application.py This is a python file that specifies generates user input data and admin input data for deploying the application

   • get_test_data Returns data for testing application functionality
   • get_test_data_omission Returns data for testing data omission scenarios
   • format_command convert test data to serialized C struct private_command.
   • print_cResponse convert serialized C struct cResponse to a printable python string
   • optional: user accounts auditing with merkle tree by setting constants.MERKLE(True) in application.py
     • print_leaf convert serialized C struct generated by get_user_leaf to a printable python string
     • get_leaf convert serialized C struct generated by get_user_leaf to a python dictionary (with uidx field)

How to compile and run a PVRA application:

Prerequisites

• Environment variables

export PROJECT_ROOT=$(pwd)
export CCF_ENABLE=<0 or 1>
export SGX_SPID=<SGX_SPID>
export IAS_PRIMARY_KEY=<IAS_PRIMARY_KEY>	
export NUM_USERS=<NUM_USERS>
export APP_NAME=<APP_NAME>
export SGX_MODE=<HW or SW>
export CCF_PATH=<optional> #todo how to run CCF

• CCF public key is hardcoded in the enclave image as a root of trust and must be updated in enclave/initPVRA.c. In order to run the demo without SCS protection, one can export CCF_ENABLE=0._

• In order to run an existing application pass the APP_NAME to ./setup.sh script.

  • setup.sh takes as arguments -a <APP_NAME> the name of the directory in $PROJECT_ROOT/application and -c <CCF_PATH> the directory that contains the credentials for communicating with the running CCF network. If no arguments are passed it uses the VSC application. --clean undoes the effects of the script._

./setup.sh -a $APP_NAME -c $CCF_PATH

Running

Use Docker & Docker-Compose

• For more than 9 users change value after "--accounts" to desired number of users + 1 (extra account is admin) in docker/docker-compose.yml
• Hardware mode

export SGX_MODE=HW
cd $PROJECT_ROOT/docker
docker-compose build enclave
docker-compose run --rm enclave bash

• Simulation mode

export SGX_MODE=SW
cd $PROJECT_ROOT/docker
docker-compose build enclave-sim
docker-compose run --rm enclave-sim bash

Build Locally

• python 3, sgxsdk, and docker required

pip install -r requirements.txt
export SGX_SDK=/opt/sgxsdk #or your local sgx sdk path
export LD_LIBRARY_PATH=$SGX_SDK/sdk_libs:$LD_LIBRARY_PATH
export SGX_MODE=<HW or SW>
cd $PROJECT_ROOT/scripts
./build.sh
./run_BB.sh
export BILLBOARD_URL="http://$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' billboard):8545"

Run python scripts

• run demo with get_test_data output

  python demo.py demo <optional: NUM_USERS>

• run test with get_test_data output (checks the expected responses and leaf nodes for correctness)

  python demo.py test <optional: NUM_USERS> <optional: test case name>

  • see vsc/application.py for example with test case names
• run data omission demo with get_test_data_omission output

  python demo.py data_omission_demo <optional: NUM_USERS>

Cleanup

cd $PROJECT_ROOT
make clean

Stop docker containers

• Docker deployment

cd $PROJECT_ROOT/docker
docker-compose down

• Local deployment

cd $PROJECT_ROOT/scripts
./stop_BB.sh

Useful scripts

• setup.sh : setup application specific files

• scripts/build.sh copy relevant application files and build the enclave and untrusted host (works for building locally and in docker container)

• scripts/copy.sh copy relevant application files

• scripts/run_BB.sh start a truffle/ganache bulletin board instance for local (non docker-compose) deployments

• scripts/stop_BB.sh stop a truffle/ganache bulletin board instance for local (non docker-compose) deployments

• docker/build.sh : build docker images

  • build a simulation/hardware enclave based on SGX_MODE environment variable (default is HW)

• docker/run.sh : run docker containers

  • runs a simulation/hardware enclave based on SGX_MODE environment variable (default is HW)
  • docker/run.sh <cmd> runs with the docker container
    • ex: ./run.sh bash opens bash terminal in enclave docker container
    • ex: ./run.sh "python demo.py test" runs test in enclave docker container

Sample VSC Run: TODO update