docs: how it works and building apps (#213)
This commit is contained in:
Ethan Buchman
GitHub
parent
5464e83ac9
commit
cb42873410
3 changed files with 171 additions and 28 deletions
10
README.md
10
README.md
|
|
@ -83,10 +83,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|||
TBD
|
||||
|
||||
[cycles]: https://cycles.money
|
||||
[getting_started]: ./docs/getting_started.md
|
||||
[how_it_works]: ./docs/how_it_works.md
|
||||
[building_apps]: ./docs/building_apps.md
|
||||
[tees]: ./docs/tees.md
|
||||
[future_work]: ./docs/roadmap.md
|
||||
[getting_started]: /docs/getting_started.md
|
||||
[how_it_works]: /docs/how_it_works.md
|
||||
[building_apps]: /docs/building_apps.md
|
||||
[tees]: /docs/tees.md
|
||||
[future_work]: /docs/roadmap.md
|
||||
[how_to_win_friends_talk]: https://www.youtube.com/watch?v=XwKIt5XYyqw
|
||||
[how_to_win_friends_thread]: https://x.com/buchmanster/status/1816084691784720887
|
||||
|
|
|
|||
|
|
@ -1,6 +1,24 @@
|
|||
# Building Applications
|
||||
|
||||
Quartz application developers need to write code for two kinds of environments: smart contracts and TEEs.
|
||||
Quartz is a framework for building private applications using TEEs.
|
||||
It allows app devs to establish secure communication with TEEs
|
||||
and to manage what codes run on what data, and when.
|
||||
|
||||
---
|
||||
WARNING:
|
||||
|
||||
Quartz provides utilities for secure communication with TEEs,
|
||||
but it DOES NOT specify a data model for applications. This gives application
|
||||
devs great power and flexibility, but with this power comes great
|
||||
responsibility. App devs must remain dilligent to ensure their data model does
|
||||
not leak private information (or leaks only what they are comfortable with).
|
||||
|
||||
The Quartz framework intends to provide better tools and patterns for securely
|
||||
working with private data, for instance via ORAM.
|
||||
|
||||
---
|
||||
|
||||
With Quartz, app devs write code for two kinds of environments: smart contracts and TEEs.
|
||||
|
||||
For now, smart contract code is written in CosmWasm Rust and deployed on Cosmos-SDK chains that support CosmWasm.
|
||||
TEE code is written in Rust and compiled via Gramine to run on Intel SGX enclaves.
|
||||
|
|
@ -8,35 +26,74 @@ TEE code is written in Rust and compiled via Gramine to run on Intel SGX enclave
|
|||
App devs need to design their smart contracts and their enclave code in tandem to work together.
|
||||
Note that enclave code is not restricted to be CosmWasm, but can be (practically) arbitrary Rust.
|
||||
|
||||
## Enclave Code
|
||||
See the [transfers app][transfers_app] for a very simplistic example of a quartz
|
||||
application.
|
||||
|
||||
...
|
||||
For background on basic TEE components and how Quartz works, see [How it
|
||||
Works][how_it_works].
|
||||
|
||||
## Smart Contract Code
|
||||
|
||||
The logic of a Quartz smart contract is divided roughly between the following domains:
|
||||
A Quartz smart contract must specify:
|
||||
|
||||
- public business logic - normal public business logic you would write if you weren't using Quartz, or for things that can't be done privately (eg. transfers from native non-private accounts)
|
||||
- private business logic - this is business logic that executes in the TEE on data that is encrypted on-chain.
|
||||
- public control logic - this is the logic that controls the enclave - who runs it, what code it runs, when it runs, etc.
|
||||
- how private requests are queued for TEE execution
|
||||
- how private state is managed
|
||||
- how TEE responses (both public and private) are executed
|
||||
- how TEE operators are managed and authorized
|
||||
|
||||
Each of these three logic written by application developers in the smart contract.
|
||||
Private requests should be encrypted to authorized TEE keys and queued for
|
||||
execution at some frequency by the TEE.
|
||||
|
||||
## Public Business Logic
|
||||
Private state should be managed in such a way that accessing/updating it does
|
||||
not unecessarily leak private information.
|
||||
|
||||
Certain parts of contract logic will always remain independent of Quartz and written as normal in the given smart contract environment.
|
||||
This might include certain deployment, ownership, or contract upgrade logic.
|
||||
It could be certain governance or administrative logic that is intended to be public regardless.
|
||||
Or it could be logic that cannot be handled via Quartz because it involves interaction with components of the blockchain that are already outside the Quartz environment.
|
||||
The most common example of this is existing transparent account balances, which can only be brought into a Quartz enabled smart contract
|
||||
in the first place via transparent on-chain logic. That said, these actions may trigger storage updates in the contract which are expected to be read by the enclave.
|
||||
Public responses can be executed directly on-chain (e.g. public balance
|
||||
changes), while private responses can be executed by verifying remote
|
||||
attestations and zero-knowledge proofs generated by the TEE. App devs must take
|
||||
care that execution of responses does not accidentally leak more information
|
||||
than they desire.
|
||||
|
||||
## Private Business Logic
|
||||
TEE operators and the code they run should be managed via some registration procedure.
|
||||
|
||||
This is the core business logic that must be executed privately. It comprises roughly 3 components:
|
||||
Like any CosmWasm application, a Quartz application defines a set of messages
|
||||
and handlers for them.
|
||||
|
||||
- on-chain queueing of private inputs
|
||||
- off-chain execution of code in an enclave
|
||||
- on-chain processing of results
|
||||
Quartz provides message types and handlers for the handshake messages to
|
||||
abstract them away from developers. It also provides types to specify that
|
||||
certain messages should include a remote attestation (RA) that must be verified.
|
||||
|
||||
## Public Control Logic
|
||||
As noted in [How it Works][how_it_works], RA depends on info about the Trusted Computing
|
||||
Base (TCB). This is implemented as a separate TCBInfo contract. The TCBInfo
|
||||
contract is a public good that can be used by many different instances of
|
||||
Quartz, and a production version is best instantiated and maintained on a
|
||||
central coordination blockchain (e.g. the Cosmos Hub).
|
||||
|
||||
DCAP verification is also implemented as its own independent contract, to reduce
|
||||
contract code size. Verification is thus performed by calling the DCAP contract.
|
||||
|
||||
## Enclave Code
|
||||
|
||||
A Quartz enclave must listen for events from the blockchain to act upon. Quartz
|
||||
provides a websocket handler for doing so. App devs can define what events to
|
||||
listen for and how to respond to them (this must be coordinated with the events
|
||||
emitted by their smart contract).
|
||||
|
||||
The enclave code must then specify what data is to be fetched from the
|
||||
blockchain for execution. This data must be verified via light client proofs.
|
||||
It is the app dev's responsibility to ensure these proofs are correctly fetched and
|
||||
verified. This ensures the enclave has permission from the contract to execute specific data. It can also ensure
|
||||
that the enclave operates on a full set of data (ie. no requests were
|
||||
excluded), providing censorship resistance.
|
||||
|
||||
The enclave code can then decrypt data and execute according to
|
||||
app-specific logic.
|
||||
|
||||
Enclaves can maintain their own local private state through SGX sealed files
|
||||
(TODO).
|
||||
|
||||
The enclave code can then produce a remote attestation of the result, and
|
||||
optionally a zero-knowledge proof (ZKP) of execution.
|
||||
|
||||
|
||||
[transfers_app]: /apps/transfers
|
||||
[how_it_works]: /docs/how_it_works.md
|
||||
|
|
|
|||
|
|
@ -1,5 +1,91 @@
|
|||
# How It Works
|
||||
|
||||
Describe security model.
|
||||
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.
|
||||
|
||||
Light clients, remote attestation, merkle proofs, ZKPs
|
||||
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 speciifc 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 encrpyted 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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue