Enclaves CLI

For Documentation on using the Enclave CLI Commands, see the Evervault CLI Reference. The Evervault CLI is the primary interface for building and deploying Enclaves.

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.

{ "foo": "bar" }

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

Decrypt

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

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

{ "foo": "bar" }

Attestation Document

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

{ "challenge": "abc", "nonce": "123" }

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:

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

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

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: