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.
If you haven’t already — join the beta waitlist here. Once your account is approved and added to the beta, you’ll receive an email from our team with next steps.
Cages Beta
How long is the beta program?
Starting from the day you deploy your first Cage, you will have full access to the Evervault Platform (free plan) and Cages for 14 days, so you can try building and deploying Cages. After that period, you’ll have the option to sign up for heavily discounted monthly pricing to continue testing.
If you’re unsure how long you have — you can always check the countdown timer in your Evervault Dashboard to see how much time is left in the allotment. If you need to adjust the timing or have any questions regarding the program, feel free to reach out to our team.
How many Cages can I create?
During the 14 day beta period — A team can run up to two Cages. In order to manage our costs, Cages will run as a single instance which may cause downtime for deployments, however this is only for your beta testing period.
Following initial beta — If you upgrade to a paid plan when the beta ends and start using Cages in production, we will provide multiple instances with high availability and zero downtime deployments.
What happens during the beta?
Try it out! Start here if you’re not sure where to get started.
You’ll hear from us a few times to check-in. We’ll also notify you when the period is coming to an end, to ensure you’re getting the most of out it.
While we’re not enforcing any specific feedback structure, we would love to know more about the use cases you are building for, any errors or bugs you encounter, and any feedback you have.
- Reach out to cages-beta@evervault.com
- Join our Discord server
What happens after the beta?
At the end of the 14-day period, we’ll notify you that your beta access has ended, and any active Cages will be deactivated.
Once deactivated, you will be able to access your Cage in your free account, but no instances will be running. If at any time you’d like to continue using Cages, you can easily upgrade to a paid plan with discounted beta pricing, and we will restart your Cage instances.
Upgrading to the paid plan will give you access to all of the Evervault Pro features and allow you to run multiple Cage instances with high availability and zero downtime deployments.
Interested in locking in limited beta pricing for Cages? Email cages-beta@evervault.com.
Other questions?
If anything comes up during the beta, please send us an email at cages-beta@evervault.com, and we’ll get back to you as soon as possible.
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:
While in beta, the Cages CLI is separate to the main Evervault CLI.
Install Docker
The Cages CLI needs to perform Docker builds using the Docker CLI. Docker must be installed on your system.
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:
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 create an App API Key in the Evervault Dashboard.
Once you have your API Key you can create the session by running:
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:
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:
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:
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 the 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:
These four PCR values are the attestation measurements that we will use to trust the remote server (the Cage) before we share any sensitive data with it. The four measurements reflect various aspects of the image you are running in the enclave.
PCR | Measures | Explanation |
---|---|---|
PCR0 | Enclave Image File | A measure of the Image that will be run within the Cage. |
PCR1 | Linux Kernel and Bootstrap | A measure of the kernel and boot ramfs data. |
PCR2 | User Application | A measure of the User Application without the boot ramfs |
PCR8 | Signing Certificate | A measure of the certificate used to sign the Enclave Image File. |
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:
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:
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:
You should now see an echo response from your Cage:
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:
TLS Termination
TLS termination is enabled by default on your Cage. When enabled, any requests into your Cage will terminate TLS within the enclave using a cert signed by the Evervault Root CA. With TLS termination enabled, you will have access to features like automatic field decryption, authentication using your Evervault API Key, and transaction logging. You can disable TLS termination by setting disable_tls_termination=true
in your cage.toml
configuration file. If you disable TLS termination, you will need to handle it within your process.
Automatic Decryption
When TLS termination is enabled on your Cage, any Evervault-encrypted strings will be decrypted automatically before being sent to your process. The fields can then be treated as plaintext within your Cage.
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
.
Decrypt
To decrypt data you can make another request to /decrypt
.
Attestation Document
To fetch the attestation document for the cage, you can make a request to /attestation-doc
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:
Port | Reason | Corresponding Feature |
---|---|---|
9999 | Used by the Encryption API | — |
53 | Used to proxy egress DNS calls | egress — can be disabled in the cage.toml |
443 | Used to proxy egress TCP traffic | egress — 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. When you create or modify an Environment Variable for your cage, it will only take effect once you redeploy the cage.
Add a secret value
Add a non secret value
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.
Egress
By default there is no networking out of a Cage. If you wish to make requests out of the Cage, turn on egress by including --egress
on Cage init or update the cage.toml. The default egress port is on port 443 to support typical HTTPS traffic, if you are making requests to hosts on different ports you will need to specify them in the cage.toml or with --egress-ports 443,465,5432
You can also configure the allowed domains that requests out of the Cage should be allowed to with --egress-destinations
. The list will be enforced in both the data plane and the control plane, requests to domains that are not explicity allowed will fail at the beginning of the TLS handshake. You can specify exact domains or wildcards to allow all subdomains, for example cages.evervault.com
or *.evervault.com
. The default behaviour is to allow requests to any domain but we recommend restricting them in production environments.
Egress will only work out of the enclave if the connection uses TLS.
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.
New Certificate
Create a new Cage signing certificate and private key.
Path to the directory where the credentials will be saved. Defaults to the current directory.
Upload Certificate Metadata
Upload a signing certificate's metadata to the Evervault API. This cert can then be used specified for locking deployments.
Path to directory where the signing cert is. Defaults to the path specified in ./cage.toml
Lock Certificates
Interactive prompt to lock Cage deployment to specific signing certificates. A Cage deployment will fail if the signing certificate used is not in specified locked certs. If no certificates are locked to a Cage, it can be deployed with any certificate.
Delete
Delete the Cage defined in a given cage.toml
.
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.
Path to Dockerfile
for Cage. Will override any Dockerfile
specified in the cage.toml
file
Describe
Get the PCRs of an existing EIF.
Init
Create a Cage and initialize a cage.toml
in the current directory.
Debug setting for the Cage. When debug is enabled, you can access logs from within the Enclave.
Flag to enable cert generation during initialization. This will use the default certificate.
List Cages
List your Cages
List Deployments
List the deployments for your Cage.
Add Environment Variable
Add environment variable to be used in a Cage.
Delete Environment Variable
Permanently delete a environment variable from the Cage environment.
Get Environment Variables
Get the environment variables in json format.
Encrypt String
Encrypt a string that can be decrypted in your Cage.
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.