Getting Started

All accounts are enrolled in an Enclaves Trial which starts when you deploy your first Enclave. The steps below will get you up and running with a simple Hello World service, and a client capable of attesting it.

Install the Evervault CLI

You can install the Evervault CLI by running the following command in your terminal:

Install Docker

The Enclaves CLI needs to perform Docker builds using the Docker CLI. Docker must be installed on your system.

Clone Hello Enclave repository

To create your first Enclave, you’ll need a server and a Dockerfile.

If you don’t have one already, then you can use our Hello, Enclave! repository (a simple Node.js Express server) as a starting point. You can clone it by running the following command:

Authenticating with the Enclaves CLI

The Enclaves CLI currently only supports API Key authentication. To setup a session in your terminal, you will first need to create a scoped App API Key in the Evervault Dashboard.

Once you have your API Key you can create the session by running:

Initialize your Enclave

Now we can initialize your Docker server as an Enclave. This will reserve the Enclave name within your Evervault App, so you can deploy your service.

For the "Hello, World!" Enclave, we'll enable egress so we can send network requests.

During development, you may want to enable debug mode to access the logs from the Enclave.

Configuration

This command will generate a enclave.toml file in your current directory containing the configuration for your Enclave. It should look something like this:

You can edit this .toml file whenever you want to reconfigure your Enclave.

Build an Enclave Image File

Now that we have our enclave.toml, we can build our Enclave. The build command will convert the service’s Dockerfile into an Enclave Image File (.eif). An .eif file is a binary image that we'll use to initialize an AWS Nitro Enclave. All attestation measures are based on the .eif binary.

Because our enclave.toml is in the current directory, we can run:

The first build will be slow (approximately 2 minutes) as the CLI has to build several Docker images. Subsequent builds should be faster once the images have been cached.

Once the Enclave has finished building, the Enclave PCRs will be written to the enclave.toml file. This will help with tracking changes in attestation measures within source control.

Our enclave.toml should have a section that looks something like this at the end of it:

These four PCR values are the attestation measurements that we will use to trust the remote server (the Enclave) before we share any sensitive data with it. The four measurements reflect various aspects of the image you are running in the enclave.

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 the boot ramfs
PCR8Signing CertificateA measure of the certificate used to sign the Enclave Image File.

You can read more about attestation for Enclaves here.

The build command will also create two files: enclave.eif and ev-user.Dockerfile. The enclave.eif file is the image that the Enclave will run in the AWS Nitro Enclave, and the ev-user.Dockerfile is the Dockerfile that was used to generate it.

Deploy your Enclave

To deploy your Enclave using an existing .eif run:

You can build a fresh .eif for a deployment by omitting the --eif-path argument. This means you can skip the ev enclave build step and deploy in one command.

The CLI will track your Enclave deployment. Once the deployment has stabilized, you should see a log which includes the domain for your Enclave:

Invoke your Enclave

You can now call your Enclave over the internet! If you deployed the Evervault Hello, Enclave! template, you can use the following cURL command to try it out:

You should now see an echo response from your Enclave:

Attest your Enclave

With your Enclave deployed and accessible, we can attest it to verify that its running the code we deployed. The example below uses the Evervault NodeJS SDK to attest the Enclave, but you can find examples for Python, and Go in the Best Practices section.

If your enclave is running in debug mode, the attestation measures will be all zeroes. We strongly advise against running in debug mode in a production setting.

To attest the enclave, we'll take the PCR values that we emitted during our deployment and supply them to the Node SDK's createEnclaveHttpsAgent function. This function returns a HTTP Agent which can be used to validate that any connections to your Enclave's hostname pass an attestation check before establishing a TLS connection. You can read about how this works in our Attestation in TLS section.

The Evervault Node, Python, Go, iOS and Android SDK includes support for attesting all connections to your Enclaves automatically.

Additionally, the internals of our attestation logic is an open-source rust library so you can even create your own client!