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 Enclaves CLI
You can install the Enclaves CLI by running the following command in your terminal:
The Enclaves CLI is currently separate to the main Evervault CLI.
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.
| PCR | Measures | Explanation |
|---|---|---|
| PCR0 | Enclave Image File | A measure of the Image that will be run within the Enclave. |
| 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 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 enableEnclaves function. This function will install an attestation listener to your process, which validates 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.