Cosmian Enclave Command-Line Interface

Overview

Cosmian Enclave allows to easily run confidential Python web applications based on Intel® SGX and Gramine. Its features include the ability to encrypt the code and the construction of a RATLS channel with your enclave.

Read Cosmian Enclave documentation for more details.

Install

$ pip install cenclave

Usage

$ cenclave -h

Note: if you set the env variable BACKTRACE=full, a Python stacktrace will be printed in case of errors.

Scaffold your app

User: the code provider

$ cenclave scaffold example

Test your app before ceating the enclave

User: the code provider

$ cenclave localtest --project example/

Create the Cosmian Enclave package with the code and the docker image

User: the code provider

$ cenclave package --project example/ \
                   --output workspace/code_provider 

The generated package can now be sent to the sgx operator.

Spawn the Cosmian Enclave docker

User: the SGX operator

$ cenclave spawn --host 127.0.0.1 \
                 --port 9999 \
                 --size 4096 \
                 --package workspace/code_provider/package_cenclave_src_1683276327723953661.tar \
                 --output workspace/sgx_operator/ \
                 app_name

At this moment, evidences have been automatically collected and the web application is up.

Evidences are essential for the code provider to verify the trustworthiness of the running application.

The file workspace/sgx_operator/evidence.json can now be shared with the other participants.

Check the trustworthiness of the application

User: the code provider

The trustworthiness is established based on multiple information:

• the full code package (tarball)
• the arguments used to spawn the web app
• evidences captured from the enclave

Verification of the enclave information:

$ cenclave verify --package workspace/code_provider/package_cenclave_src_1683276327723953661.tar \
                  --evidence output/evidence.json \
                  --output /tmp

If the verification succeeds, you get the RA-TLS certificate (written as a file named ratls.pem) and you can now seal the code key to share it with the SGX operator.

Seal your secrets

User: the code provider

$ cenclave seal --secrets example/secrets_to_seal.json \
                --cert /tmp/ratls.pem \
                --output workspace/code_provider/

Finalize the configuration and run the application

User: the SGX operator

$ cenclave run --sealed-secrets workspace/code_provider/secrets_to_seal.json.sealed \
               app_name

Test the deployed application

User: the SGX operator

$ cenclave test --test workspace/sgx_operator/tests/ \
                --config workspace/sgx_operator/config.toml \
                app_name

Decrypt the result

User: the code provider

Assume the SGX operator gets a result as follows: curl https://localhost:7788/result --cacert /tmp/ratls.pem > result.enc

Then, the code provider can decrypt the result as follows:

$ cenclave decrypt --key key.txt \
                   --output workspace/code_provider/result.plain \
                   result.enc
$ cat workspace/code_provider/result.plain

Manage Cosmian Enclave's containers

User: the SGX operator

You can stop and remove the container as follows:

$ cenclave stop [--remove] <app_name>

You can restart a stopped and not removed containers as follows:

$ cenclave restart <app_name>

You can get the Cosmian Enclave container logs as follows:

$ cenclave logs <app_name>

You can get the Cosmian Enclave docker status as follows:

$ cenclave status <app_name>

You can get the list of running Cosmian Enclave containers:

$ cenclave list