140 lines
4.5 KiB
Markdown
140 lines
4.5 KiB
Markdown
# DeTEE library for using SGX features, such as remote attestation, raTLS and sealing
|
|
|
|
## Requirements to run
|
|
|
|
* The library is intended to be used from within an enclave
|
|
* The library depends on the extension present in /dev/sgx
|
|
* The library must run on top of the occlum libos
|
|
|
|
## Prerequisites
|
|
|
|
To run the project in **Docker**, you need to install the docker first.
|
|
On Ubuntu, you can use the following commands:
|
|
|
|
```bash
|
|
# Add docker official GPG key
|
|
sudo apt update
|
|
sudo apt install ca-certificates curl
|
|
sudo install -m 0755 -d /etc/apt/keyrings
|
|
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
|
|
sudo chmod a+r /etc/apt/keyrings/docker.asc
|
|
|
|
# Add docker repository to apt sources
|
|
echo \
|
|
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
|
|
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
|
|
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
|
sudo apt update
|
|
|
|
# Install docker packages
|
|
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
|
|
|
# Add your user to the docker group
|
|
sudo groupadd docker
|
|
sudo usermod -aG docker $USER
|
|
newgrp docker
|
|
```
|
|
|
|
## The flow
|
|
|
|
The MRSIGNER of the `example/signing_key.pem` is hardcoded in the enclave code:
|
|
|
|
```
|
|
83E8A0C3ED045D9747ADE06C3BFC70FCA661A4A65FF79A800223621162A88B76
|
|
```
|
|
|
|
You can generate your own signing key. Just use the following command:
|
|
|
|
```
|
|
openssl genrsa -3 -out signing_key.pem 3072
|
|
```
|
|
|
|
To get the MRSIGNER of the key, compile [this project](https://github.com/intel/sgx-ra-sample)
|
|
and use the following command:
|
|
|
|
```
|
|
./mrsigner signing_key.pem
|
|
# For the example/signing_key.pem the output is:
|
|
6871A831CED408CD99F0ED31587CC2B5C728C99D4A0A1ADF2F0C5574EBBB00DC
|
|
# FIXME: Which is different from the real MRSIGNER by Occlum:
|
|
83E8A0C3ED045D9747ADE06C3BFC70FCA661A4A65FF79A800223621162A88B76
|
|
```
|
|
|
|
## Run using Occlum docker
|
|
|
|
### On the build host (without SGX)
|
|
|
|
Run the occlum image in the docker environment:
|
|
|
|
```bash
|
|
# Notice that there is no SGX device mounted
|
|
docker run --rm -it -v /path/to/detee-sgx:/root/detee-sgx occlum/occlum:latest-ubuntu20.04
|
|
# Inside the docker container do env preparation to build the image
|
|
rustup install stable-x86_64-unknown-linux-gnu
|
|
rustup default stable
|
|
rustup target add x86_64-unknown-linux-musl
|
|
|
|
# Build the server and the client
|
|
cd detee-sgx
|
|
./build_server.sh grpcs
|
|
./build_client.sh grpcs
|
|
```
|
|
|
|
This will produce 2 signed bundles, `server_instance/server.tar.gz` and `client_instance/client.tar.gz`.
|
|
|
|
### On the run host (with SGX)
|
|
|
|
```bash
|
|
docker run --rm -it --device /dev/sgx/enclave --device /dev/sgx/provision -v /path/to/tars:/root/run occlum/occlum:latest-ubuntu20.04
|
|
# IMPORTANT, edit /etc/sgx_default_qcnl.conf, so that the PCCS URL is set correctly
|
|
# "pccs_url": "https://api.trustedservices.intel.com/sgx/certification/v4/"
|
|
|
|
# Unpack the server and the client
|
|
cd run
|
|
tar -xzvf server.tar.gz
|
|
tar -xzvf client.tar.gz
|
|
|
|
# Run the server and the client (in two different terminals)
|
|
cd server && occlum run /bin/mratls_grpcs_server
|
|
cd client && occlum run /bin/mratls_grpcs_client
|
|
```
|
|
|
|
## Run locally
|
|
|
|
Before running make sure you have installed Occlum and the SGX driver, see
|
|
[this cheatsheet](INSTALL_SGX.md) for more details. You should also have the
|
|
Occlum Rust toolchain installed to get `occlum-cargo`. To test the project
|
|
just run client and server scripts in different terminals:
|
|
|
|
```
|
|
|
|
./build_server.sh grpcs --run
|
|
./build_client.sh grpcs --run
|
|
|
|
```
|
|
|
|
## Mutual RATLS examples
|
|
|
|
Examples show how to use the mRATLS (Mutual Remote Attestation TLS) in different situations:
|
|
|
|
* The first example shows how to create mRATLS HTTPS server and client
|
|
* The second example shows how to create mRATLS GRPCs server and client
|
|
|
|
Both the server and the client must be running inside the enclave.
|
|
So during the remote attestation peers, acquire their RA certificates.
|
|
And during the TLS handshake, they verify each other's RA certificates.
|
|
The config allows to whitelist MRENCLAVE, MRSIGNER, PRODID, SVN of the peer.
|
|
|
|
## RATLS examples
|
|
|
|
Example shows how to create RATLS HTTPS server and client.
|
|
The server must be running inside the enclave.
|
|
The client can be running anywhere.
|
|
The server config allows to whitelist the public ec25519 key of the client.
|
|
The client config allows to whitelist MRENCLAVE, MRSIGNER, PRODID, SVN of the server.
|
|
|
|
## Sealing example
|
|
|
|
Example shows how to seal and unseal data using the enclave.
|
|
The data is stored in the hostfs (`/host` folder inside the enclave).
|