Anjuna Nitro Enclave Configuration

The Anjuna Nitro Enclave Configuration file contains information that the Anjuna Nitro Runtime needs to set up the application’s environment and start the application in an AWS Nitro Enclave.

You can specify the Anjuna Nitro Enclave Configuration file when building the Enclave Image File (EIF) with the anjuna-nitro-cli build-enclave command.

anjuna-nitro-cli build-enclave --docker-uri nginx:latest --output-file nginx.eif --enclave-config-file config.yaml

The Anjuna Nitro Enclave Configuration file allows you to configure the application running in the enclave (without changing the Docker image used to create the EIF):

  • Setting up new environment variables (or overriding existing ones).

  • Adding files to the application’s file system.

  • Setting the hostname of the enclave.

  • Selecting ports to expose.

  • Changing the command that starts the application in the enclave.

  • Specifying the S3 bucket that contains secrets for the application running in the enclave.

Anjuna Nitro Enclave Configuration Entries

The Anjuna Nitro Enclave Configuration should be a valid YAML file.

Version

The Anjuna Nitro Enclave Configuration must contain a version entry:

version: 1.7

The Anjuna Nitro Runtime v1.33.0002 supports AWS Nitro Enclave Configuration v1.7 and below.

Environment variables

The environment entry contains an array of strings, where each string represents an environment variable and its value. The string should have the following format:

name=value

For example:

environment:
  - NGINX_HOST=foobar.com
  - NGINX_PORT=80

The variables defined in this section override the ones that were defined in the Docker container.

The value for an environment variable must be a literal (i.e. references to other environment variables are not supported).

Configuration files

The files entry contains an array of files with the following attributes:

  • path (required): The path where the file will be created. The Anjuna Nitro Runtime will create the intermediate directories if they don’t exist.

  • mode (optional): The permissions on the file (in octal notation). The default value is 0644 (which maps to [-rw-r—​r--] in symbolic notation).

  • owner (optional): The owner (user) of the file. The default value is root.

  • group (optional): The owner (group) of the file. The default value is the user owner.

  • content (optional): The content of the file (if not provided, an empty file will be created).

files:
- path:  "/my-application/etc/config.toml"
  mode:  0644
  owner: root
  group: root
  content: |
    [database]
    server = "192.168.1.1"
    ports = [ 8000, 8001, 8002 ]
    connection_max = 5000
    enabled = true

This example defines the file /my-application/etc/config.toml with the following content:

[database]
server = "192.168.1.1"
ports = [ 8000, 8001, 8002 ]
connection_max = 5000
enabled = true

Exposed Ports

Use the exposedPorts: entry to specify one or more ports to expose from the AWS Nitro Enclave.

If the exposedPorts: entry is not added, then all ports will be exposed.

When using the exposedPorts: entry without specifying any ports, then all ports will be exposed.

Example for exposing ports 443 and 80:

exposedPorts:
  - 443
  - 80

Docker overrides

The Anjuna Nitro Enclave Configuration can be used to override Dockerfile entries at runtime, without modifying the Dockerfile itself.

Entrypoint

The Anjuna Nitro Runtime executes the command specified by the ENTRYPOINT and CMD entries from the original Dockerfile. If you want to override this value, you can specify the entrypoint and its command-line arguments.

entrypoint: [program, 1st_arg, 2nd_arg, ...]

Note that the syntax above can alternatively be written like this for the same result:

entrypoint:
  - program
  - 1st_arg
  - 2nd_arg
  - ...

Command

The Anjuna Nitro Runtime executes the command specified by the ENTRYPOINT and CMD entries from the original Dockerfile. If you want to override this value, you can specify the CMD command and its command-line arguments.

command: [program, 1st_arg, 2nd_arg, ...]

Note that the syntax above can alternatively be written like this for the same result:

command:
  - program
  - 1st_arg
  - 2nd_arg
  - ...

User and group

The Anjuna Nitro Runtime executes the Container Command with the system user and group specified by the USER entry from the original Dockerfile. If you want to override this value, you can specify the new user and optionally, group.

The format of this string is a valid username or a decimal user ID (UID). This can be followed by an optional valid group name or a decimal group ID (GID) separated by a colon :.

User and group IDs do not necessarily need to exist in /etc/passwd or /etc/group. If the group is not specified, it defaults to the user’s default group. If that cannot be determined then the root (UID=0) group is used.

username: user_name_or_id[:group_name_or_id]

Working directory

The Anjuna Nitro Runtime executes the Container Command with the working directory specified by the WORKDIR entry from the original Dockerfile. If you want to override this value, you can specify the new working directory.

The working directory must be an absolute path.

workdir: /path/to/workdir

Environment variables

See Environment variables above.

Hostname

You can change the default hostname of the enclave to any value with the hostname field.

hostname: anjuna-enclave

The value of hostname is inserted automatically in the file /etc/hosts on the file system of the application running in the AWS Nitro Enclave.

Encrypted Configuration Files

The Anjuna Nitro Enclave Configuration file is inserted into the EIF in the same area as the application, and as such, it affects the PCR2 measurement.

However, this configuration file is not encrypted and you should not insert sensitive data (secrets) in this file. To securely provide secrets to your application, use the anjuna-nitro-encrypt tool to encrypt a configuration file with an AWS KMS key and upload it to an S3 bucket.

You can then add the location of the S3 bucket in the Anjuna Enclave Configuration, which allows the Anjuna Nitro Runtime to download and decrypt the encrypted secrets (as long as the AWS Nitro Enclave is allowed to decrypt data using the AWS KMS key).

To specify the location of the S3 bucket, add the key attestedConfURL to the Anjuna Nitro Enclave Configuration file.

environment:
  - NGINX_HOST=foobar.com
  - NGINX_PORT=80

attestedConfURL: s3://my-bucket.nitro.my-application/kms-encrypted-data.bin

The Encrypted Configuration file has the same format as the Anjuna Nitro Enclave Configuration file. Entries defined in the Encrypted Configuration file override entries defined in the Anjuna Nitro Enclave Configuration file.

Persistent Storage Mounts

The mounts entry contains an array of mounts with the following attributes:

  • type (required): The type of the mount; should be basic

  • name (required): The name of the volume mount

  • mountPath (required): The path to mount the volume to inside the enclave

  • forceMount (optional): NOTE: Please read Persistent Storage Security on the potential security implications of persistent storage and this option. The default behavior is to abort enclave startup if a conflicting resource is found at the volume mountPath. This option consists of a string of flag values separated by commas. Multiple flags can be specified, each flag enabling overwriting of different types of conflicting resources and that can be selected from the following list:

    • file: Enable overwriting existing file at mountPath

    • empty: Enable overwriting existing empty directory at mountPath

    • full: Enable overwriting existing directory with content at mountPath

    • all: Enables all of the above flags

mounts:
- type: basic
  name: example-volume
  mountPath: /shared/example-volume

Untrusted Configuration

The Anjuna Enclave Configuration provides the user a configuration that is trusted, either through the configuration file attached at enclave-build-time or through an encrypted configuration file. However, there are cases where one needs to provide data to the software running in an enclave that is not known in advance and does not need to be trusted. For example, the IP address of a logging server. For such needs, the Anjuna Nitro Runtime provides a way to set such untrusted configuration.

An Enclave can fetch values for environment variables that do not affect the Enclave’s measurements and do not need to be attested. The configuration entry untrustedConfig and its sub-entries, envVars and allow, contain an array of environment variables to pull from the parent EC2 instance or from a Kubernetes ConfigMap.

For detailed information about fetching information from a non-attested and non-measured configuration, refer to the Untrusted Configuration section. 
untrustedConfig:
  envVars:
    allow:
      - LOG_SERVER_ADDRESS
      - LOG_LEVEL

This example configuration allows the Enclave to fetch the environment variables LOG_SERVER_ADDRESS and LOG_LEVEL from the parent EC2 instance.

Example

Here is a complete example of an Anjuna Nitro Enclave Configuration:

version: 1.7

environment:
  - MY_APP_HOST=anjuna-enclave
  - MY_APP_CONFIG=/my-application/etc/config.toml

attestedConfURL: s3://my-bucket.nitro.my-application/kms-encrypted-data.bin

hostname: anjuna-enclave

command: [nginx-debug, '-g', 'daemon off;']

files:
- path:  "/my-application/etc/config.toml"
  mode:  0644
  owner: root
  group: root
  content: |
    [database]
    server = "192.168.1.1"
    ports = [ 8000, 8001, 8002 ]
    connection_max = 5000
    enabled = true

exposedPorts:
  - 8000
  - 8001
  - 8002

mounts:
- name: app-data
  type: basic
  mountPath: /shared/app-data