Skip to content

Getting started

Welcome to Microservice Encryption deployment tutorial

To launch your first confidential microservice, follow this tutorial in your favorite terminal.

Install

The CLI tool mse requires at least Python 3.8 and OpenSSL 1.1.1 series. It is recommended to use pyenv to manage different Python interpreters.

$ pip3 install mse-cli
$ mse --help     
usage: mse [-h] [--version]
               {context,deploy,init,list,login,logout,remove,scaffold,status,stop,test,verify} ...

Microservice Encryption CLI.

options:
  -h, --help            show this help message and exit
  --version             The version of the CLI

subcommands:
  {context,deploy,init,list,login,logout,remove,scaffold,status,stop,test,verify}
    context             Manage your MSE context files
    deploy              Deploy the application from the current directory into a MSE node
    init                Create a configuration file in the current directory.
    list                Print the list of apps from a project
    login               Sign up or login a user
    logout              Log out the current user
    remove              Stop and remove the MSE app from the project
    scaffold            Create a new empty app in the current directory
    status              Print the status of a MSE app
    stop                Stop a MSE app
    test                Test locally the application in the MSE docker
    verify              Verify the trustworthiness of an MSE app (no sign-in required)

Log in

$ mse login

It will open your browser to sign up and/or log in on console.cosmian.com.

If it’s the first time you are using Microservice Encryption (MSE), you need to use the sign-up tab. Don’t forget to confirm your email and complete the information of your account. You can skip the payment information by selecting a free plan.

The credential tokens are saved in ~/.config on Linux/MacOS and C:\Users\<username>\AppData on Windows.

Deploy your first web application

Let’s start with a simple Flask Hello World application:

$ mse scaffold helloworld
An example app has been generated in the current directory
You can configure your MSE application in: helloworld/mse.toml
You can now test it locally from 'helloworld/' directory using: `mse test` then `pytest`
Or deploy it from 'helloworld/' directory using: `mse deploy`
Refer to the 'helloworld/README.md' for more details.
$ tree helloworld/
helloworld/
├── mse_src
│   └── app.py
├── mse.toml
├── README.md
├── requirements-dev.txt
└── tests
    ├── conftest.py
    └── test_app.py

2 directories, 6 files

The mse_src is your application directory designed to be dispatched by mse-cli to the Microservice Encryption infrastructure. The other files or directories will stay on your own host.

The file app.py is a basic Flask application with no extra code. Adapt your own application to MSE does not require any modification to your Python code:

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(status=HTTPStatus.OK)


@app.route('/')
def hello():
    """Get a simple example."""
    return "Hello world"


if __name__ == "__main__":
    app.run(debug=True)

The configuration file is a TOML file:

name = "helloworld"
project = "default"
hardware = "4g-eu-001"

[code]
location = "mse_src"
docker = "ghcr.io/cosmian/mse-flask:20230228091325"
python_application = "app:app"
healthcheck_endpoint = "/health"

This project also contains a test directory enabling you to test this project locally without any MSE consideration. Please ensure flask is installed locally, before running the following tests:

$ cd helloworld
$ # Install dev requirements to run the tests
$ pip install -U -r requirements-dev.txt
$ # Run your application server
$ python3 mse_src/app.py
$ # From another terminal, query your server or start the unit tests
$ curl http://127.0.0.1:5000
$ pytest

Now let’s deploy it!

Free plan

Using a free plan is longer to deploy than non-free plans because the memory and CPU dedicated are limited. It should take around 60 seconds to deploy against a few seconds with non-free plans.

For your first deployment, to make things easier to understand and faster to run, we disable some security features. The --no-verify and --untrusted-ssl will be removed in the next sections. 

$ cd helloworld
$ mse deploy --no-verify --untrusted-ssl
⚠️ This app runs in untrusted-ssl mode with an operator certificate. The operator may access all communications with the app. See Documentation > Security Model for more details.
Temporary workspace is: /tmp/tmpzdvizsb5
Encrypting your source code...
Deploying your app...
App 04e9952c-981d-4601-a610-81152fe21315 creating for helloworld with 512M EPC memory and 0.38 CPU cores...
You can now run `mse logs 04e9952c-981d-4601-a610-81152fe21315` if necessary
✅ App created!
⚠️ App trustworthiness checking skipped. The app integrity has not been checked and shouldn't be used in production mode!
Sending secret key and decrypting the application code...
Waiting for application to be ready...
Your application is now fully deployed and started...
✅ It's now ready to be used on https://123456789abcdef.cosmian.dev until 2023-01-10 20:30:36.860596+01:00. The application will be automatically stopped after this date.
The context of this creation can be retrieved using `mse context --export 04e9952c-981d-4601-a610-81152fe21315`
You can now quickly test your application doing: `curl https://123456789abcdef.cosmian.dev/health`

That’s it!

Your microservice is up at https://123456789abcdef.cosmian.app.

You can test your first app using curl:

$ export APP_DOMAIN_NAME="..." # your DN here
$ curl "https://$APP_DOMAIN_NAME"

At this point, you can write your own Flask application and deploy it into MSE.

Compatibility with WSGI/ASGI

To be compliant with MSE your Python application must be an ASGI or WSGI application. It is not possible to deploy a standalone Python program. In the next example, this documentation will describe how to deploy Flask applications. You also can use other ASGI applications, for instance: FastAPI.

Examples

Visit mse-app-examples to find MSE application examples.

Verify the trustworthiness of your app (remove --no-verify)

Pre-requisites

Before deploying the app, verify that docker service is up and your current user can use the docker client without privilege

In this step, we will redeploy your previous app but without the insecure argument --no-verify. When you deploy an app, you need to verify that the running app is indeed your code and is running inside an Intel SGX enclave signed by Cosmian. For more details, please refer to the security model.

$ cd helloworld
$ mse deploy -y --untrusted-ssl
An application with the same name in that project is already running...
Stopping the previous app (force mode enabled)...
⚠️ This app runs in untrusted-ssl mode with an operator certificate. The operator may access all communications with the app. See Documentation > Security Model for more details.
Temporary workspace is: /tmp/tmpucnl7zfd
Encrypting your source code...
Deploying your app...
App 74638f07-c85c-41d3-be82-238d0099e2d3 creating for helloworld with 8192M EPC memory and 6.00 CPU cores...
You can now run `mse logs 74638f07-c85c-41d3-be82-238d0099e2d3` if necessary
✅ App created!
Checking app trustworthiness...
The code fingerprint is 9bb0342fa8a09c2707632ed8556accc5fac168515bf2453bf88992c9fa84e849
Verification: success
Sending secret key and decrypting the application code...
Waiting for application to be ready...
Your application is now fully deployed and started...
✅ It's now ready to be used on https://74638f07-c85c-41d3-be82-238d0099e2d3.cosmian.dev until 2023-01-10 21:23:28.929299+01:00. The application will be automatically stopped after this date.
The context of this creation can be retrieved using `mse context --export 74638f07-c85c-41d3-be82-238d0099e2d3`
You can now quickly test your application doing: `curl https://74638f07-c85c-41d3-be82-238d0099e2d3.cosmian.dev/health`

As you can see, the warning message has been removed for the output of your previous command and the trustworthiness of the app has been checked.

Secure the SSL connection (remove --untrusted-ssl)

In this step, we will redeploy your previous app but without the insecure argument --untrusted-ssl. You need to use an end-to-end SSL connection from you to the application. That way, no one but the enclave can read the content of the queries. For more details, please refer to the app deployment flow and the app usage flow.

$ cd helloworld
$ mse deploy -y
An application with the same name in that project is already running...
Stopping the previous app (force mode enabled)...
Temporary workspace is: /tmp/tmp4u_gcjwk
Encrypting your source code...
Deploying your app...
App 248fce63-bc05-49a6-816a-4436b456fa27 creating for helloworld with 8192M EPC memory and 6.00 CPU cores...
You can now run `mse logs 248fce63-bc05-49a6-816a-4436b456fa27` if necessary
✅ App created!
Checking app trustworthiness...
The code fingerprint is ecd2ed83c65906bec65d5b8bc02e18d439c0d1401272e207fed254f7228eee7e
Verification: success
✅ The verified certificate has been saved at: /tmp/tmp4u_gcjwk/cert.conf.pem
Sending secret key and decrypting the application code...
Waiting for application to be ready...
Your application is now fully deployed and started...
✅ It's now ready to be used on https://123456789abcdef.cosmian.app until 2023-01-10 21:24:28.162324+01:00. The application will be automatically stopped after this date.
The context of this creation can be retrieved using `mse context --export 248fce63-bc05-49a6-816a-4436b456fa27`
You can now quickly test your application doing: `curl https://123456789abcdef.cosmian.app/health --cacert /tmp/tmp4u_gcjwk/cert.conf.pem`

Your microservice is up at https://123456789abcdef.cosmian.app.

You can test your app using curl:

$ # force curl CA bundle to be /tmp/tmpntxibdo6/cert.conf.pem
$ curl "https://123456789abcdef.cosmian.app" --cacert /tmp/tmpntxibdo6/cert.conf.pem

Production deployment

The previous fully secured deployment method without any insecure arguments is the preferred way to deploy your application in production

Going further

Read develop your own app to go further, such as:

  • Test your application
  • Use dependencies
  • Use secrets to query third party services
  • Use paths
  • Use mse-ignore
  • Understand memory size
  • Understand environment limitations
© Copyright 2018-2023 Cosmian. All rights reserved.