Crate quartz_enclave_core

Crate quartz_enclave_core 

Source
Expand description

§Quartz Core Enclave

This crate provides a framework for writing quartz application enclaves and implements the core enclave logic for the quartz handshake protocol. Quartz enforces all user <> enclave communication to happen via a blockchain for replay protection.

At a high level, the code here implements:

  • The quartz enclave framework which includes various components that enable app devs to write secure enclaves with replay protection. This includes trait definitions and default implementations.
  • Core enclave logic for the quartz handshake. This includes -
    • Event handlers for handling core events.
    • Request handlers for handling core requests.
    • gRPC service implementation for the request handlers.

§Framework Design

The framework separates trusted and untrusted code by defining two abstractions - the host and the enclave, each represented by a separate trait.

§Host vs. Enclave Separation

The host (untrusted) code is responsible for:

  • Identifying which chain events the application wants to handle.
  • Collecting all necessary on-chain data for each event to form a provable request to the enclave (e.g., by fetching on-chain state, light client proofs, merkle proofs, etc.).
  • Calling the enclave with the created request.
  • Sending transactions to the blockchain on behalf of the enclave (AKA the response).

The enclave (trusted) code is responsible for:

  • Determining which requests these events correspond to.
  • Verifying request data integrity (via light client proofs and merkle proofs).
  • Handling each request securely inside the TEE.
  • (Optionally) generating responses to be posted to the chain.
  • Attesting to the responses using remote-attestation (to be verified on-chain).

Through this layered approach:

  • Host code (generally) runs outside the TEE, bridging the blockchain and the enclave.
  • Enclave code runs inside a Gramine-based TEE, protecting private data and cryptographic operations.

§Lifecycle of a request

Below is a simplified lifecycle for a typical user <> enclave interaction involving a quartz app enclave:

  1. User sends a request to the contract (on-chain).
  2. Contract triggers an event reflecting that new request.
  3. Host (untrusted) listens for relevant events from the chain.
  4. On seeing an event, the Host constructs an enclave request that encapsulates all the relevant data for handling the event.
  5. The Host then calls the enclave with that request.
  6. Enclave (trusted) handles the request, verifies the data, performs the necessary computations, and (optionally) returns an attested response.
  7. The Host sends the response back to the chain, e.g. via a transaction.

§Usage

See the app enclaves in the examples directory for usage examples.

§Quartz enclave

§Enclave usage

gramine-sgx-gen-private-key

CARGO_TARGET_DIR=./target cargo build --release

gramine-manifest  \
    -Dlog_level="error"  \
    -Dhome=${HOME}  \
    -Darch_libdir="/lib/$(gcc -dumpmachine)"  \
    -Dra_type="dcap" \
    -Dquartz_dir="$(pwd)"  \
    quartz.manifest.template quartz.manifest

gramine-sgx-sign --manifest quartz.manifest --output quartz.manifest.sgx
gramine-sgx ./quartz

§CLI usage

cargo run -- --chain-id testing \
    --trusted-height 1 \
    --trusted-hash "A1D115BA3A5E9FCC12ED68A9D8669159E9085F6F96EC26619F5C7CEB4EE02869"

Modules§

attestor
backup_restore
chain_client
event
grpc
gRPC service implementation for core enclave requests (handshake)
handler
host
key_manager
proof_of_publication
store
types
Core types used in the handshake

Structs§

DefaultBackup
DefaultEnclave
The default generic implementation of the Enclave trait for convenience. Includes a generic context for additional application-specific data or configuration.

Enums§

Notification
Notification the enclave may emit.

Traits§

Enclave
Represents the core functionality running inside a TEE.

Type Aliases§

DefaultSharedEnclave
A type alias for a default, thread-safe enclave.