Deploy a Hello, World! Enclave

Enclaves are an Evervault Primitive which allow teams to easily deploy existing Docker containers into Secure Enclaves, managed by Evervault.

Enclaves are built on top of AWS Nitro Enclaves, the AWS Trusted Execution Platform built on top of EC2. Nitro Enclaves offer all of the foundational properties of a Secure Enclave (as discussed in the Overview). Enclaves abstract away the complexity of building, deploying, and scaling Nitro Enclaves as well as supporting Attestation in every request.

This guide will walk you through deploying a basic Hello, World! example Node API to Enclave.

Prerequisites

Before you get started, you’ll need an Evervault account. You can sign up for one here. Once you sign up, you will have 2 weeks of trial access to Enclaves. During the trial period, you can deploy a single instance Enclave.

TL;DR

  • Install the CLI: curl https://cli.evervault.com/v4/install -sSL | sh
  • Clone the repo: git clone https://github.com/evervault/hello-enclave.git
  • Initialize your Enclave in the hello-enclave directory: ev enclave init -f ./Dockerfile --name hello-enclave --debug --egress --healthcheck /health
  • Deploy your Enclave: ev enclave deploy -v
  • Attest your Enclave: ev enclave attest
  • Invoke your Enclave: curl https://hello-enclave.<app_uuid>.enclave.evervault.com/hello

Install the CLI

To start, you’ll need to install the Enclaves CLI. This will let you manage your Enclaves, and deploy them from your machine or from CI.

You can verify that the installation was successful by running the ev enclave CLI command without any subcommand:

Initialize your Enclave

Once you have the CLI installed, you’ll need to clone the hello-enclave sample repo:

Then cd into the freshly cloned repo:

This repo contains a simple Node express app, and a simple Dockerfile which exposes the Node App on port 8008.

Before we use the CLI, we’ll need to get our environment prepped to authenticate with the API. The easiest way to do that is to run export your API Key in your shell:

Once that’s done, we’re ready to initialize your Enclave. We’ll run the ev enclave init command. The command takes a series of flags that are used to setup your Enclave’s config:

  • -f tells the Enclave CLI where to find the Dockerfile from our service. The CLI uses this Dockerfile as a base for all Enclave build and deployments
  • --name defines the name of our Enclave, which we will use later when sending requests to it
  • --egress bootstraps our Secure Enclave Environment with the ability to send network requests to the public internet. When this flag is not set the Secure Enclave has no ability to send requests anywhere, it can only respond to requests that it receives.
    • We can further scope our egress permissions within the Enclave using the --egress-ports to define the ports we want to send traffic on (defaults to 443), and --egress-destinations to restrict the allowed hostnames.
  • --healthcheck defines the path in our service that should be used as the Enclave healthcheck.

This is not an exhaustive list of the options supported in the init command. You can find out more by running ev enclave init --help.

You can see the complete config that was generated for your Enclave by looking at the enclave.toml file. It should look something like this:

Once we’re happy with the Enclave config, we can move on to building and deploying our Enclave.

Build your Enclave

While the services to run in Enclaves are built using Dockerfiles, the file used during deployment is an EIF. An EIF is an Enclave Image File. When we run the build command, we will generate an EIF which we can then use to deploy the Enclave.

Deployments don’t require an explicit build step. You can deploy a Enclave without running the build command first using ev enclave deploy. However, it is useful to see the files generated during our build step.

To build the Enclave, we can run:

To build the Enclave, the CLI updates the provided Dockerfile and embeds an Evervault maintained runtime. This runtime abstracts away the complexities of the Secure Enclave from our service, allowing us to continue writing our Node app as normal. The runtime also provides some useful features such as provisioning a trusted certificate for terminating TLS, tracking the requests to the Enclave, and, optionally, allowing our Secure Enclave to speak to specific hosts on the public internet.

This build may take a while, as the Enclave CLI has to build multiple Docker images (this is to support building an EIF across a wider range of hosts).

Once the build is finished, we should see that an EIF file was generated in our current directory. We will use this file to deploy the Enclave in our next step.

Looking at our enclave.toml, there should be a new attestation section which contains the measurements of our image that we can use as an integrity check at runtime:

These PCR values each correspond to a measurement of a specific part of the image being deployed:

PCRMeasuresExplanation
PCR0Enclave Image FileA measure of the Image that will be run within the Enclave
PCR1Linux Kernel and BootstrapA measure of the kernel and boot ramfs data
PCR2User ApplicationA measure of the User Application without boot ramfs
PCR8Signing CertificateA measure of the certificate used to sign the Enclave Image File

Deploy your Enclave

To deploy the Enclave from the EIF generated from the build command, we can run:

The CLI will track the progress of your deployment and update you as it moves through the deployment process. When the deployment is complete, the CLI will log a message that includes the domain of the Enclave:

Attest your Enclave

Now that your Enclave is running, you can attest it using the CLI:

This will verify that the measurements taken from the ./enclave.eif file match those of the Enclave running in AWS, and that the Enclave is in fact running in a Secure Enclave.

When interacting with a Enclave from a production client, the Evervault SDKs will handle the attestation process for you on each request.

Invoke your Enclave

We can verify that the Enclave is reachable by cURLing the domain given by the deploy command:

You should see the enclave respond with:

Summary

This guide walked through the process of taking a basic Node.js Express app and deploying it into a Secure Enclave. With our Express app deployed into the Secure Enclave, we were able to verify the integrity of our service and still cURL it as normal.