Getting Started
Welcome to Cosmian Enclave deployment tutorial
To launch your first Cosmian Enclave, follow this tutorial in your favorite terminal. Note that you first need to setup your Intel SGX machine based on the Server Installation section.
Install the Cosmian Enclave CLI¶
The Cosmian Enclave CLI requires at least Python 3.8 and OpenSSL 1.1.1 series. It is recommended to use pyenv to manage different Python interpreters if needed.
$ pip3 install cenclave
$ cenclave --help
usage: cenclave [-h] [--version]
{encrypt,decrypt,evidence,scaffold,list,logs,package,restart,run,status,seal,unseal,spawn,stop,test,localtest,verify}
...
Cosmian Enclave CLI - 1.0.0
options:
-h, --help show this help message and exit
--version version of cenclave CLI
commands:
{encrypt,decrypt,evidence,scaffold,list,logs,package,restart,run,status,seal,unseal,spawn,stop,test,localtest,verify}
encrypt encrypt a file using Fernet symmetric encryption
decrypt decrypt a file using Fernet symmetric encryption
evidence collect the evidences to verify on offline mode the application and the enclave
scaffold create a new boilerplate web application
list list the running containers
logs print container logs
package generate a package containing the container image and the code to run with
Cosmian Enclave
restart restart a web application
run finalise the configuration of the application docker and run the application
code
status print the container status
seal seal file using NaCl's Seal Box.Recipient is either raw X25519 public key or
extracted from RA-TLS certificate with enclave's public key in REPORT_DATA field
of SGX quote
unseal unseal file using NaCl's Seal Box
spawn spawn container with specified web app
stop stop and optionally remove a running container
test Test a deployed web app
localtest test locally a web app without SGX
verify verify the trustworthiness of a running Cosmian Enclave web application and get
the RA-TLS certificate
Docker configuration
Before deploying the app, verify that Docker service is up and your current user is part of docker group.
See Manage Docker as a non-root user.
Scaffold your app¶
User
This command is for the Code Provider role
$ cenclave scaffold example
$ tree -a example
example
├── Dockerfile
├── README.md
├── config.toml
├── secrets.json
├── secrets_to_seal.json
├── src
│ ├── .cenclaveignore
│ └── app.py
└── tests
├── conftest.py
└── test_app.py
3 directories, 9 files
The Dockerfile should be based on cenclave-image-base image and include all the dependencies required to run your application.
The file app.py is a basic Hello World Flask application.
Adapt by addind your own Python code in this boilerplate.
from http import HTTPStatus
from flask import Flask, Response
app = Flask(__name__)
@app.get("/health")
def health_check():
"""Health check of the application."""
return Response(response="OK", status=HTTPStatus.OK)
@app.route('/')
def hello():
"""Get a simple example."""
return "Hello world"
# other endpoints
# ...
The configuration to run your application is done in a TOML file config.toml which will be used by the CLI:
name = "example"
python_application = "app:app"
healthcheck_endpoint = "/health"
tests_cmd = "pytest"
tests_requirements = [
"intel-sgx-ra",
"pytest",
]
The project tree also contains a test directory to test your application locally and remotely. It might help to debug and detect runtime errors before running your code in a Cosmian Enclave.
Compatibility with WSGI/ASGI
To be compliant with Cosmian Enclave your Python application must use a compatible web framework based on ASGI or WSGI. Flask and FastAPI are the most popular Python web frameworks. It’s not possible to deploy a standalone Python program.
Examples
See Cosmian Enclave examples for proof-of-concept of confidential web applications.
Test your app, your docker and your configuration¶
User
This command is for the code provider role
$ cenclave localtest --code example/src/ \
--dockerfile example/Dockerfile \
--config example/config.toml \
--test example/tests/
or more concisely with default arguments:
Testing your code before sending it to the SGX operator is recommended. Note that any error will require to restart the deployment flow from scratch.
Create the application package with the code and the docker image¶
User
This command is for the code provider role
This command generates a tarball named package_<app_name>_<timestamp>.tar which can be send to to the SGX operator:
$ cenclave package --code example/src/ \
--dockerfile example/Dockerfile \
--config example/config.toml \
--test example/tests/ \
--output code_provider/
or more concisely with default arguments:
Add --encrypt argument if you want to encrypt your code.
Spawn the application docker image¶
User
This command is for the SGX operator role
The spawn command will run a new Cosmian enclave with your code loaded but it will stay in an intermediate state called the configuration server.
Configuration server is waiting additional information such as the decryption key of the code or any other secrets needed by your application.
$ cenclave spawn --host 0.0.0.0 \
--port 9999 \
--size 4096 \
--package code_provider/package_<app_name>_<timestamp>.tar \
--output sgx_operator/ \
--san <EXTERNAL_IP_ADDR | DOMAIN_NAME | localhost>
app_name
host: usually 127.0.0.1 or 0.0.0.0port: port used by your applicationsize: memory size (in MB) of the enclave to spawn (must be a power of 2 greater than 1024)package: the application package containing the Docker images and the codeoutput: directory to write the evidence JSON filesan: Subject Alternative Name to use for routing with SSL pass-through (either domain name, external IP address or localhost)
The output file sgx_operator/evidence.json contains cryptographic proofs related to the enclave and be shared with anyone to interact with your enclave.
It will be used by the code provider to verify the running app.
Collect the evidences to verify the application¶
User
This command is for the SGX operator role
This command collects cryptographic proofs related to the enclave and serialize them in a JSON file evidence.json.
You can choose another PCCS by specifying the --pccs parameter, by default it will determine the PCCS URL by parsing the aesmd service configuration
file: /etc/sgx_default_qcnl.conf.
The file sgx_operator/evidence.json can be shared to any user of your application to allow them to do the remote attestation of your service.
Check the trustworthiness of the application¶
User
This command is for the SGX operator role
The trustworthiness is established by using 2 inputs:
- the full code package (tarball file)
- evidences captured from the running enclave (JSON file)
$ cenclave verify --package code_provider/package_<app_name>_<timestamp>.tar \
--evidence sgx_operator/evidence.json \
--output /tmp
If the verification succeeds, the RA-TLS certificate is written as a file named ratls.pem, and you can now seal the
code’s secret key to share it with the SGX operator.
Seal your secrets for your Cosmian Enclave¶
User
This command is for the code provider role
Using the unique enclave’s public key tied to your code, it’s possible to seal secrets which can only be decrypted by a specific Cosmian Enclave.
The output of seal command is an encrypted file which can be sent to the SGX operator to start your application.
$ cenclave seal --input example/secrets_to_seal.json \
--receiver-enclave /tmp/ratls.pem \
--output code_provider/secrets_to_seal.json.seal
Finalize the configuration and run the application¶
User
This command is for the SGX operator role
$ cenclave run --sealed-secrets code_provider/secrets_to_seal.json.seal \
--secrets example/secrets.json \
app_name
If the command is successful, your application now running normally using a RA-TLS certificate.
Test the deployed application¶
User
This command is for the SGX operator role
This command helps to check that the application is executed properly as the code provider expects.
Example of encryption on the application side¶
User
These commands are for the code provider role
If your are using the example from cenclave scaffold command, there are endpoints to show how to encrypt the body of an HTTP response with a key provided with sealed secrets at the start of your application.
Sealed secrets
The JSON file secrets_to_seal.json has been sent sealed to the enclave at step seal secrets.
The JSON value corresponding to JSON key result_sk inserted in secrets_to_seal.json will be used to encrypt the response.
Remember that seal secrets can only be decrypted by the specific Cosmian Enclave used as receiver.
First collect the encrypted result:
and decrypt the result with key.bin which contains the raw bytes of result_sk key (not encoded in Base64 such as in secrets_to_seal.json):
$ cenclave decrypt --input result.enc
--key key.bin \
--output code_provider/result.plain
$ cat code_provider/result.plain
message using result_sk from SEALED_SECRETS
The decrypt command only supports Fernet algorithm.
This is a toy example and we advise to use proper encryption methods such as AES256-GCM or XChacha20-Poly1305.