View mode

Develop

One of the advantages of using Cosmian Enclave to protect your application and data in the cloud, is that if you have already developped a Python web application then it does not need to be modified. Just write a configuration TOML file and run the deploy subcommand.

In the following sections, we give good practices and some security considerations you need to know before deploying your application in production.

Requirements

It’s recommended to use Ubuntu 22.04 or 22.04 with at least python 3.10 on the host.

Using a third-party service with secrets¶

Before sending the Python code of your microservice, each file is encrypted except: requirements.txt.

This code is supposed to be sharable to any user, as your convenience, in order to check the trustworthiness of your app. As a matter of fact, do not write any secret into your code. For example: passwords or keys to connect to a third-party service like a remote storage or a database.

If you need such secrets to run your code, write them in a secrets.json file. Please see the example below. This file will be sent to the enclave after the latter has been verified during the app deployment. Note that this file is not encrypted and can be read by the SGX operator. Your application will then be able to read it to retrieve the secrets it needs.

Example of a secrets.json file:

{
  "login": "username",
  "password": "azerty"
}

Which is used by this application code example:

import os
import json

from pathlib import Path
from flask import Flask

app = Flask(__name__)


@app.route('/whoami')
def whoami():
    """A simple example manipulating secrets."""
    secrets = json.loads(Path(os.getenv("SECRETS_PATH")).read_text())
    return secrets["login"]

Encrypting some secrets

If your application requires some secrets to be hidden from the SGX operator, write those secrets in another file, for example secrets_to_seal.json. Then you can seal this secrets_to_seal.json file with the cenclave seal command. This command encrypts the secrets.json file using the trusted RA-TLS certificate. This certificate embeds the public key of the enclave, ensuring that only the enclave is able to decrypt the sealed secrets.json file.

Specific filepath available in Cosmian Enclave¶

Find below a small example to show how to use paths in your Cosmian Enclave:

import os

from http import HTTPStatus
from pathlib import Path
from datetime import datetime
from flask import Flask, Response

app = Flask(__name__)

# define a global variable from env variables
WORKFILE: Path = Path(os.getenv("HOME")) / "date.txt"


@app.post('/')
def write_date():
    """A simple example of file writing."""
    # transparently encrypt the file which can't be read on the host
    WORKFILE.write_text(str(datetime.now()))
    return Response(status=HTTPStatus.OK)


@app.route('/')
def read_date():
    """A simple example of file reading."""
    if not WORKFILE.exists():
        return Response(response="You should write before read",
                        status=HTTPStatus.NOT_FOUND)

    # transparently decrypt the file with a key specific to your Cosmian Enclave
    txt = WORKFILE.read_text()
    WORKFILE.unlink()
    return txt

Your application owns a dedicated storage up to 10GB. The following directories are all encrypted on the host and can only be decrypted by your Cosmian Enclave:

Env	Path	Encrypted (1)	Persistent (2)	Comments
`$HOME`	`/root`	✔️	✖️	home directory to save anything such as cache or configuration files
`$SECRETS_PATH`	`$HOME/.cache/cenclave/secrets.json`	✔️	✖️	application secrets file for infrastructure credentials (database, or network access, then known by the SGX operator)
`$SEALED_SECRETS_PATH`	`$HOME/.cache/cenclave/sealed_secrets.json`	✔️	✖️	application secrets sealed for your specific enclave (content only readable in your enclave)
`$TMP_PATH`	`/tmp`	✔️	✖️	temporary folder for your application (only readable in your enclave)
`$MODULE_PATH`	`/app`	✔️	✖️	folder with the decrypted application code (only readable in your enclave)

Note that writing operations in $HOME are about 2.5 times slower than in a $TMP_PATH. However the max file size you can allocate in $TMP_PATH is hardware_memory / 4 and the number of files has no limit as long as the sum of their size is lower than the size still available. Choose wisely the file location based on your own application constraints.

(1) Only the enclave containing this version of your code can decrypt this directory. Another enclave or even another version of your application won’t be able to read it

(2) The content will be removed when the application is stopped

`.cenclaveignore` file¶

You can edit .cenclaveignore file in your code directory. This file is read by the CLI when deploying an app and avoid packaging some files if not needed. The syntax is the same as .gitignore.

A default .cenclaveignore is generated by the cenclave scaffold command.

Memory size¶

When you declare the memory size through the field hardware in config.toml, note that a part of this memory is used by the system itself.

All the libraries needed to run your application will be loaded in the enclave memory. Therefore, the effective memory size available for your application is approximately: hardware_memory - libraries_size.

When running the Docker container locally, you can use the option --memory to estimate the memory size of your application. See GitHub repository cenclave-image-base for more details.

Limitations¶

Please find below limitations that you need to consider to be able to run smoothly your application in Cosmian Enclave:

Fork are not allowed for performance issues to avoid bad user experience, creating new enclaves is slow.
Some application are using a lot of memory and when working with enclaves the memory is limited and must be used with care. Consider using a confortable amount of EPC memory and RAM regarding your application.