Automatic Decryption

When TLS termination is enabled on your Enclave, any Evervault-encrypted strings will be decrypted automatically before being sent to your process. The fields can then be treated as plaintext within your Enclave.

TLS Termination

TLS termination is enabled by default on your Enclave. When enabled, any requests to your Enclave will terminate TLS within the enclave using a cert signed by a Trusted 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 tls_termination=false in your enclave.toml configuration file. If you disable TLS termination, you will need to handle it within your process.

Encryption API

Evervault exposes a simple encryption API within the enclave which allows you to encrypt and decrypt Evervault-encrypted strings. It also allows you to manually retrieve an 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 /decrypt.

POST/decrypt

200Ok

{ "foo": "ev:encrypted_string..." }

Response

{ "foo": "bar" }

Attestation Document

To fetch the attestation document for the Enclave, 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 Enclave 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 Enclave.

Reserved Ports

Certain ports are reserved within Enclaves 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 `enclave.toml`
4444	Used to proxy egress TCP traffic	`egress` — can be disabled in the `enclave.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 Enclave environment in plaintext on startup. When you create or modify an Environment Variable for your Enclave, it will only take effect once you redeploy the Enclave. You can restart your Enclave's current deployment to redeploy your existing Enclave image without affecting it's PCRs.

Details on how to update your Enclave's environment variables are detailed in the CLI reference below.

HTTP Transaction Logging

When TLS Termination is enabled on your Enclave, 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 enclave.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-ctx. You can then search for this ID in the Activity Screen.

Trusted Headers

By default, your Enclave's transaction logs will obfuscate any non-standard HTTP headers. You can specify a list of headers to pass through using the trusted_headers key in the enclave.toml. This can be used to surface error codes or similar diagnostic information from your Enclave. For example:

Note: certain headers cannot be trusted to avoid accidentally leaking credentials. This currently includes: api-key, authorization, and proxy-authorization.

Debug Mode

If you want to test your Docker Image in a Enclave and see the output, you can run your Enclave in debug mode. Transaction Logs will be emitted and viewable through the Evervault Dashboard. Raw logs from your Enclave can be viewed using the ev-enclave logs command in the CLI.

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

Egress

By default there is no networking out of a Enclave. If you wish to make requests out of the Enclave, turn on egress by including --egress on Enclave init or update the enclave.toml.

You can also configure the allowed domains that requests out of the Enclave 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 during the DNS lookup. You can specify exact domains or wildcards to allow all subdomains, for example enclave.evervault.com or *.evervault.com. The default behaviour is to allow requests to any domain but we recommend restricting them in production environments.

Authentication

Enclaves expect an Evervault API key in the api-key request header by default. This can be disabled if you wish to implement your own form of authentication to the Enclave. This can be useful if your Enclave is exposed directly to your End-Users.

Healthchecks

By default, Enclaves will perform a shallow healthcheck. The communication between the host instance and the Enclave will be tested, and the in Enclave environment will be validated to ensure that the Enclave initialization completed successfully.

This healthcheck can be extended to include a GET to the service running in the Enclave. Every second, the Evervault-Healthcheck-Agent will send a GET request to your process. Your process will be regarded as healthy if it responds with a successful status code (i.e. 2XX).

Enclaves CLI

The Enclaves CLI is the primary interface for building and deploying Enclaves. The content below serves as a reference manual for the commands available.

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 enclave.toml to be available when creating an Enclave Image File. This can be generated using the ev-enclave init command.

Args

CONTEXT_PATH

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

Options

-c, --configDefaults to ./enclave.toml

Path to the enclave.toml file.

-f, --fileDefaults to ./Dockerfile

Path to the Dockerfile to use for the Enclave.

-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.

--build-arg

Build time arguments to provide to Docker.

--from-existing

Build from enclave.Dockerfile for build reproducibility

--reproducible

Build enclave with reproducible measures

--forward-proxy-protocol

Enabled forwarding proxy protocol when TLS Termination is disabled

--no-cache

Disables the use of cache during image builds

New Certificate

Create a new Enclave signing certificate and private key.

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 Enclave subject is given.

Upload Certificate Metadata

Upload a signing certificate's metadata to the Evervault API. This cert can then be used in the cert lock command.

Note: Certificate metadata is automatically uploaded to the Evervault API when you deploy an Enclave. This command is only necessary if you want to lock deployments to a certificate before the certificate has been used for a deployment. If you have already deployed with the certifcate, the metadata will be available in the cert lock prompt.

Options

-p, --cert_path

Path to directory where the signing cert is. Defaults to the path specified in ./enclave.toml

-c --config

Path to enclave.toml config file. Default: ./enclave.toml

Lock Certificates

Interactive prompt to lock Enclave deployments to specific signing certificates. An Enclave deployment will fail if the signing certificate used is not in specified locked certs. If no certificates are locked to an Enclave, it can be deployed with any certificate. If you want to lock a newly created certifcate, you must first upload it's metadata using the cert upload command. This certificate will then be available in the cert lock prompt.

Options

-c --config

Path to enclave.toml config file. Default: ./enclave.toml

Delete

Delete the Enclave defined in a given enclave.toml.

Options

-c, --configDefault to ./enclave.toml

Path to the enclave.toml config file.

--enclave-uuid

Uuid of the Enclave to delete

--background

Perform the Enclave deletion in the background

--force

Prevent confirmation dialogue and proceed with deletion. Use with caution.

Deploy

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

Args

CONTEXT_PATH

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

Options

-c, --configDefault: ./enclave.toml

Path to enclave.toml config file

--eif-path

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

-f, --fileDefault: ./Dockerfile

Path to Dockerfile for Enclave. Will override any Dockerfile specified in the enclave.toml file

--private-key

Private key used to sign the Enclave Image File.

--quiet

Disable verbose output

--signing-cert

Certificate used to sign the Enclave Image File.

--build-arg

Build time arguments to provide to Docker

--from-existing

Build from enclave.Dockerfile for build reproducibility

--reproducible

Build enclave with reproducible measures

--healthcheck

The endpoint to use for healthchecks. See healthchecks for more information.

--no-cache

Disables the use of cache during the image builds

Restart

Restart the Enclave defined in your enclave.toml file. This will redeploy the Enclave with the same image as your current Deployment, but with the latest environment variables and secrets. This won't affect your Enclave's PCRs

Options

-c, --configDefault to ./enclave.toml

Path to the enclave.toml config file.

--enclave-uuid

Uuid of the Enclave to restart

--background

Perform the Enclave restart in the background

Describe

Get the PCRs of an existing EIF.

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

--no-cache

Disables the use of cache during the image builds

Init

Create an Enclave and initialize an enclave.toml in the current directory.

Options

--debug

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

--egress

Flag to enable network egress from your Enclave, default egress port is 443

--egress-ports

Comma separated list of ports to allow egress on

--egress-destinations

Comma separated list of domains to allow egress to, default is all (*)

-f, --file

Dockerfile to build the Enclave

-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 Enclave to deploy

-o, --outputDefault: ./

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

--private-key

Path to the signing key to use for the Enclave.

--signing-cert

Path to the signing cert to use for the Enclave

-v, --verbose

Toggle verbose output

--disable-api-key-auth

Turn off API key authentication in the Enclave.

--trusted-headers

Trusted headers sent into the Enclave will be persisted without redaction in the Enclave's transaction logs.

List Enclaves

List your Enclaves

Options

-h, --help

Print help information

--json

Toggle JSON output for stdout

-v, --verbose

Toggle verbose output

List Deployments

List the deployments for your Enclave.

Options

--enclave-uuid

The uuid of the Enclave to get deployments for.

-h, --help

Print help information.

--json

Toggle JSON output for stdout.

-v, --verbose

Toggle verbose output.

Logs

View the logs for your Enclave. Only available for Enclaves in debug mode.

Options

--enclave-uuid

The uuid of the Enclave to get deployments for.

-c, --config

The local Enclave config.

--end-time

The end time in milliseconds since the unix epoch.

--start-time

The start time in milliseconds since the unix epoch.

-h, --help

Print help information.

Add Environment Variable

Add environment variable to be used in a Enclave.

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 Enclave environment.

Flags

--keyRequired

The name of the environment variable.

Get Environment Variables

Get the environment variables in json format.

Encrypt String

Encrypt a string that can be decrypted in your Enclave.

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)

--app-uuid

The UUID of the Evervault app to encrypt the data for

Enclave.toml

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

The enclave.toml can be used to configure rules such as network egress and debug mode. It also includes dynamic attestation measures so each time your Enclave 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 enclave.toml is as follows: