Products

Cages

Evervault Cages are the easiest way to build, deploy and scale Secure Enclaves.

Evervault Cages allow developers to easily deploy Docker containers in a Secure Enclave, powered by AWS Nitro Enclaves. Cages offer easy deployment, invocation and attestation of Secure Enclaves without the engineering overhead.

Cages are in private beta and only available on request. If you're interested in participating in the private beta, just send us a message.

Getting Started

Get up and running with Cages.

Install the Cages CLI

Once you have access to the private beta, you can install the Cages CLI by running the following command in your terminal:

shamir:~$
curl https://cage-build-assets.evervault.com/cli/install -sL | sh

While in beta, the Cages CLI is separate to the main Evervault CLI.

Clone Hello Cage repository

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

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

shamir:~$
git clone https://github.com/evervault/hello-cage

Authenticating with the Cages CLI

The Cages CLI currently only supports API Key authentication. To setup a session in your terminal, you will first need to get your App's API Key from the Evervault Dashboard.

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

shamir:~$
export EV_API_KEY=<API_KEY>

Initialize your Cage

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

For our first Cage, we’ll enable some features which help us see what’s happening inside the Secure Enclave, namely: debug mode and network egress. To do that, we need to run the following command:

shamir:~$
ev-cage init -f ./Dockerfile \
--name hello-cage \
--debug --egress

Configure your Cage

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

1
name = "hello-cage"
2
uuid = "<YOUR_CAGE_ID>"
3
app_uuid = "<APP_ID>"
4
team_uuid = "<TEAM_ID>"
5
debug = true
6
dockerfile = "Dockerfile"
7
8
[egress]
9
enabled = true
10
11
[signing]
12
certPath = "~/.ev/cages/cert.pem"
13
keyPath = "~/.ev/cages/key.pem"

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

Build your Cage

Now that we have our cage.toml, we can build our Cage. The build command will convert the service’s Dockerfile into a Cage-compatible Enclave Image File (.eif). A .eif file is a binary image that is used to initialize an AWS Nitro Enclave, and all attestation measures are based on the .eif binary.

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

shamir:~$
ev-cage build --write --output .

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

Because we have provided the --write flag, the CLI will append our latest Cage build's attestation measures to the cage.toml. This will help with tracking changes in attestation measures within source control.

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

1
[attestation]
2
HashAlgorithm = "Sha384 { ... }"
3
PCR0 = "8576aa759528d6dc82b6a35504edf491bcf245266acb5745f7f15801e15988a5abbc8c637af3edeb96efcbe8e8a433a1"
4
PCR1 = "bcdf05fefccaa8e55bf2c8d6dee9e79bbff31e34bf28a99aa19e6b29c37ee80b214a414b7607236edf26fcb78654e63f"
5
PCR2 = "4ffe3d8b0211341c9eac73abccfcfed63f694a4a84b7758e70d1941d0ac6c0a7091c7860aa1ff2e4d39bbdd2b220608f"
6
PCR8 = "9f357c7861268d124143701d30fbd0401f4f2854db7698851c51a08bc719abe9cc89645324d24cdbac1f216b482d6ad8"

These attestation measures are how we will verify the integrity of the code after we have deployed it. Attestation lets us trust a remote server before we share any sensitive data with it. You can read more about attestation for Cages here.

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

Deploy your Cage

To deploy your Cage using an existing .eif run:

shamir:~$
ev-cage deploy --eif-path $EIF_PATH

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

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

shamir:~$
Cage deployed successfully. Your Cage is now available at https://<cage_name>.<app_id>.cages.evervault.com

Invoke your Cage

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

shamir:~$
curl https://<cage_name>.<app_uuid>.cages.evervault.com/hello -H "API-Key: <API_KEY>" -k

You should now see an echo response from your Cage:

1
{ "response": "Hello! I'm writing to you from within an enclave" }

Reference

cage.toml

Cages allows configuration to be embedded within the source code, so it is easily attestable and can't be tampered with. Simply include a cage.toml file in the root of your repository and Evervault will automatically include it at build time.

The cage.toml can be used to configure rules such as network egress and debug mode. It also includes dynamic attestation measures so each time your Cage is built, the PCR measures can be verified by comparing the result of the attestation with the measures included in Evervault's TLS attestation.

The format of your cage.toml is as follows:

1
# The name of your Cage
2
name = "hello-cage"
3
4
# The ID of your Cage
5
uuid = "<YOUR_CAGE_ID>"
6
7
# The ID of the Evervault App which is hosting the Cage
8
app_uuid = "<APP_ID>"
9
10
# The ID of the Evervault Team which owns the App
11
team_uuid = "<TEAM_ID>"
12
13
# Whether `debug` mode should be enabled.
14
# Logs are only available in `debug` mode.
15
debug = true
16
17
# Whether api key auth is enabled for the Cage
18
api_key_auth = true
19
20
# Whether transaction logging is enabled for the Cage.
21
# Note: Requires TLS Termination to be enabled
22
trx_logging = true
23
24
# Turn off TLS Termination with certs signed by Evervault Root CA.
25
# Note: you will have to handle TLS termination within your process.
26
disable_tls_termination = true
27
28
# The path to your Cage's `Dockerfile`
29
dockerfile = "Dockerfile"
30
31
# Whether or not to enable outbound network requests from your Cage
32
# If enabled, the networking layer will be bundled at build time
33
[egress]
34
enabled = true
35
36
# The path to the signing key and certificate for your Cage
37
[signing]
38
certPath = "~/.ev/cages/cert.pem"
39
keyPath = "~/.ev/cages/key.pem"

Encryption API

Evervault exposes a simple encryption API within Cages which allows you to encrypt and decrypt Evervault-encrypted strings. It also allows you to manually retrieve an AWS Nitro Enclaves Attestation Document if you wish to implement your own attestation protocol.

Encrypt data

To encrypt data, you can make a request to /encrypt.

POST/encrypt
200Ok
{ "foo": "bar" }
Response
{ "foo": "ev:encrypted_string..." }

Decrypt

To decrypt data you can make another request to /encrypt.

POST/encrypt
200Ok
{ "foo": "ev:encrypted_string..." }
Response
{ "foo": "bar" }

Attestation Document

To fetch the attestation document for the cage, you can make a request to /attestation-doc

POST/attestation-doc
200Ok
{ "challenge": "abc", "nonce": "123" }
Response
Attestation Document as Base64-encoded binary blob

Default port

By default, traffic within the Cage will be forwarded to port 8008 on loopback. This can be configured by supplying an EXPOSE directive in your Dockerfile.

Note that several ports are reserved within the Cage.

Reserved Ports

Certain ports are reserved within Cages for internal services. In certain cases, these ports are only reserved when a feature is enabled. The reserved ports are as follows:

PortReasonCorresponding Feature
9999Used by the Encryption API
53Used to proxy egress DNS callsegress — can be disabled in the cage.toml
443Used to proxy egress TCP trafficegress — can be disabled in the cage.toml

Environment Variables

Environment Variables can be configured using the UI or CLI. Secrets can be encrypted on creation and will be made available to your Cage environment in plaintext on startup.

Add a secret value

shamir:~$
ev-cage env add --key ACME_API_KEY --value secretvalue --secret

Add a non secret value

shamir:~$
ev-cage env add --key REGION --value europe

All Cages will have your Evervault API Key available as an environment variable EV_API_KEY

HTTP Transaction Logging

When TLS Termination is enabled on your cage, you can enable HTTP Transaction logging which will propagate request logs to the Evervault Activity Screen within the dashboard. These logs contain HTTP Status Codes, Methods, Timestamps etc. This can be configured within the cage toml by setting trx_logging = false (Default is true).

A unique ID is also appended to each request. This ID can be found in the response headers under x-evervault-cage-ctx. You can then search for this ID in the Activity Screen.

Debug Mode

If you want to test your Docker Image in a Cage and see the output, you can run your Cage in debug mode. Logs will be emitted and viewable through the Evervault Dashboard, or by using the ev-cage logs command in the CLI.

When running a Cage in debug mode, the attestation measure returned will consist entirely of zeroes. This means that a Cage in debug mode is not attestable.

Authentication

Cages expect an Evervault API key in an api-key request header by default. This can be disabled if you wish to implement your own form of authentication to the Cage.


Cages CLI Reference

Manage Cages from your terminal.

Build

The build command mirrors the docker build command but produces an Enclave Image File (EIF) as output instead of a Docker image. The build command requires a cage.toml to be available when creating an Enclave Image File. This can be generated using the ev-cage init command.

shamir:~$
ev-cage build [OPTIONS] [CONTEXT_PATH]
Args
CONTEXT_PATH

Path to use for Docker context, defaults to the current directory.

Options
c, --configDefaults to ./cage.toml

Path to the cage.toml file.

f, --fileDefaults to ./Dockerfile

Path to the Dockerfile to use for the Cage.

o, --output

Path to directory to save the processed Dockerfile and EIF.

--private-key

Private key to be used when signing the EIF.

--signing-cert

Certificate corresponding to the private key.

w, --write

Write the latest attestation information to the cage.toml.

--build-arg

Build time arguments to provide to Docker.

New Certificate

Create a new Cage signing certificate and private key.

shamir:~$
ev-cage cert new [OPTIONS]
Options
o, --output

Path to the directory where the credentials will be saved. Defaults to the current directory.

--subj

Defining the certificate’s distinguished name e.g. /CN=EV/C=IE/ST=LEI/L=DUB/O=Evervault/OU=Eng. If not given a generic Cage subject is given.

Delete

Delete the Cage defined in a given cage.toml.

shamir:~$
ev-cage delete [OPTIONS]
Options
c, --configDefault to ./cage.toml

Path to the cage.toml config file.

--cage-uuid

Uuid of the Cage to delete

--background

Perform the Cage deletion in the background

Deploy

Deploy the Cage defined in your cage.toml file. By default, the deploy command will ignore any prebuilt EIFs and begin a fresh Cage build. You can prevent this by providing a path to an existing EIF using the --eif-path option.

shamir:~$
ev-cage deploy [OPTIONS] [CONTEXT_PATH]
Args
CONTEXT_PATH

Path to use for the Docker context. Defaults to the current directory.

Options
c, --configDefault: ./cage.toml

Path to cage.toml config file

--eif-path

Path to EIF for the Cage. Will skip building if EIF is provided.

f, --fileDefault: ./Dockerfile

Path to Dockerfile for Cage. Will override any Dockerfile specified in the cage.toml file

--private-key

Private key used to sign the Enclave Image File.

--quite

Disable verbose output

--signing-cert

Certificate used to sign the Enclave Image File.

w, --write

Write latest attestation information to the cage.toml config file

--build-arg

Build time arguments to provide to Docker

Describe

Get the PCRs of an existing EIF.

shamir:~$
ev-cage describe [OPTIONS] [EIF_PATH]
Args
EIF_PATHDefault: ./enclave.eif

Path to the EIF to describe.

Options
h, --help

Print help information

--json

Toggle JSON output for stdout

v, --verbose

Toggle verbose output

Init

Create a Cage and initialize a cage.toml in the current directory.

shamir:~$
ev-cage init [OPTIONS] --name <CAGE_NAME>
Options
--debug

Debug setting for the Cage. When debug is enabled, you can access logs from within the Enclave.

--egress

Flag to enable network egress from your Cage

f, --file

Dockerfile to build the cage

-generate-signing

Flag to enable cert generation during initialization. This will use the default certificate.

h, --help

Print help information

--json

Toggle JSON output for stdout

--name

Name of Cage to deploy

o, --outputDefault: ./

Directory to write the cage.toml to. Defaults to the current directory.

--private-key

Path to the signing key to use for the Cage.

--signing-cert

Path to the signing cert to use for the Cage

v, --verbose

Toggle verbose output

--disable-api-key-auth

Turn off API key authentication in the Cage.

List Cages

List your Cages

shamir:~$
ev-cage list cages [OPTIONS]
Options
h, --help

Print help information

--json

Toggle JSON output for stdout

v, --verbose

Toggle verbose output

List Deployments

List the deployments for your Cage.

shamir:~$
ev-cage list deployments [OPTIONS] --cage-uuid <CAGE_ID>
Options
--cage-uuid

The Cage ID to get deployments for.

h, --help

Print help information.

--json

Toggle JSON output for stdout.

v, --verbose

Toggle verbose output.

Add Environment Variable

Add environment variable to be used in a Cage.

shamir:~$
ev-cage env add [OPTIONS] --key <ENV_KEY> --value <SECRET_VALUE>
Flags
--keyRequired

The name of the environment variable.

--valueRequired

The value for the environment variable.

Options
-h, --help

Print help information.

--secret

Encrypt the environment variable.

--curve

Curve to use for encryption. If none is provided the default is secp256r1.

  • secp256r1 (alias: nist)
  • secp256k1 (alias: koblitz)

Delete Environment Variable

Permanently delete a environment variable from the Cage environment.

shamir:~$
ev-cage env delete --key <ENV_KEY>
Flags
--keyRequired

The name of the environment variable.

Get Environment Variables

Get the environment variables in json format.

shamir:~$
ev-cage env get

Encrypt String

Encrypt a string that can be decrypted in your Cage.

shamir:~$
ev-cage encrypt [OPTIONS] <VALUE>
Flags
--valueRequired

The value to encrypt.

Options
-h, --help

Print help information.

--curve

Curve to use for encryption. If none is provided the default is secp256r1.

  • secp256r1 (alias: nist)
  • secp256k1 (alias: koblitz)

FAQ

How does attestation work with Cages?

Evervault Cages abstract away the complexity of implementing and verifying attestation with your Secure Enclaves. Cages embed the attestation flow in the TLS handshake, which is performed every time you invoke a Cage.

TLS Attestation

When you connect to a Cage, your client performs a standard TLS handshake with the enclave. Evervault automatically handles all load balancing between enclaves at the network layer.

Each Cage provisions its own self-signed TLS certificate, with the AWS Nitro Attestation Document embedded within the certificate.

When a client connects to the enclave, it can verify the attestation before completing the TLS handshake. By default, the Evervault server-side SDKs include functionality to verify your Cage's attestation out-of-the-box.

How large can a Cage be?

The current limit for Cages is 16 vCPUs and 64 gigabytes of RAM.

Enclaves use a RAM-based filesystem. This means that the memory allocated to your Cage is used for both storage and RAM.

Cages and Evervault Encryption

Evervault Cages allow you to process data encrypted using Evervault Encryption. By default, TLS termination is handled automatically within your Cage, and encrypted data is automatically decrypted before it is passed to your application.

Can I run a Cage on my own infrastructure?

Evervault Cages are managed and run by Evervault on our infrastructure. A major advantage of using Cages is that the burden of hosting and scaling all of the infrastructure necessary to run Secure Enclaves is handled by Evervault.

Evervault running your Cage doesn't weaken the security guarantees provided by Secure Enclaves, thanks to attestation. You are still provided with the attestation measure at build-time and can verify that these haven't been tampered with — all within the TLS handshake.

Can I run multiple instances of a Cage?

Yes! Cages are deployed on two separate EC2 instances split between two Availability Zones in a region for greater resiliency. The number of instances running, and the regions they run in will soon be made configurable.