cycles-quartz/docs/how_it_works.md

# How It Works

Quartz establishes a secure light-client based session between a smart
contract and a TEE via a handshake protocol. This registers the TEE with the
contract and the contract with the TEE. Data can then be encrypted to the TEE and 
submitted to the contract, and the contract can control when the TEE runs and on
what data. All communication with the TEE is done via 
a light-client based round-trip with the blockchain. 

The main goal is to prevent grinding or replay attacks on the TEE - the ability
for an operator to re-run execution many times on the same data, in an effort to
leak information. The basic idea is that all execution on the
TEE is gated by verifying light client proofs from the blockchain that give the
enclave permission to execute.

To do this, the contract must be able to verify that specific code is running on the TEE,
that a specific TEE instance is running (with that code), and that that TEE instance
generated a specific decryption key. This is all achieved by the Quartz
Handshake. 

Following the handshake, app-specific execution can proceed in the enclave in a
controlled manner.

First, some basic concepts.

## Basic Concepts

In SGX land, the hash of the code that will run on the enclave is called
`mr_enclave` (for enclave "measurement")

Verifying that the code with a given `mr_encalve` executed on an SGX device is
called `remote attestation` (RA).

Intel's latest standard for remote attestation is called DCAP (Data Center
Attestation Primitives)

DCAP verification is basically verification of an x509 certificate
chain of signatures from Intel and from the given SGX device.

Secure DCAP verification depends on an up-to-date index of SGX versions (microcode and software)
and their security status (i.e. whether they are out-dated or need a security
update). This index is called the Trusted Computing Base (TCB). A valid DCAP signature must be generated by 
an SGX version that is up-to-date according to the TCB info.

To establish a secure session between a smart contract and a TEE, Quartz
performs a handshake where the smart contract
verifies remote attestations from the TEE, and the TEE verifies light client proofs from the smart contract.

## Handshake

The goal of the handshake is to establish:

- specific code is running on the TEE (given by an `mr_enclave`)
- a specific TEE is running (given by a `nonce`)
- the TEE has a specific decryption key (given by a `pubkey`)

This is done in three corresponding steps:

- Instantiate
- SessionCreate
- SessionSetPubKey

In `Instantiate`, the smart contract is configured with a given `mr_enclave` and with the
light client parameters for verification (ie. weak subjectivity initialization).
This is a trusted initialization phase that requires off chain social consensus
to align on valid code to run and on legitimate light client initialization. The
`mr_enclave` should correspond to audited code with reproducible builds.

In SessionCreate, a nonce is generated on the TEE and remote attests to it. The smart
contract verifies the RA and that it was produced from the correct `mr_encalve`,
and stores the nonce.

In SessionPubKey, the TEE verifies a light client proof that the nonce was
stored in the contract, generates an encryption key pair, and remote attests to
the nonce and pubkey. The smart contract verifies the RA and that the nonce is the same and stores the pubkey.

The TEE is now ready to process requests encrypted to the pubkey.

## Execution

After the handshake, encrypted requests can be submitted to the smart contract,
encrypted to the TEE's now registered pubkey. At whatever cadence defined by the
contract, the TEE can fetch the encrypted requests, verify a light client proof of the requests and
the contracts authorization for the TEE to process them, decrypt the requests, and perform
some computation. 

The TEE can then remote attest to the results, and optionally produce a
zero-knowledge proof (ZKP) of the whole execution.

The smart contract can then verify the RA and the ZKP. The ZKP provides
additional guarantees of the correctness of the execution performed by the TEE.