anjuna-nitro-cli build-enclave

anjuna-nitro-cli build-enclave --docker-uri <docker-uri> --output-file <output-file> [OPTIONS...]

Builds an enclave image from a Docker image and saves it to a file.

Launching an AWS Nitro Enclave requires an Enclave Image File (EIF). The anjuna-nitro-cli build-enclave tool creates an EIF from a Docker container and provides the enclave’s measurements.

Private Docker images

When building an EIF from a private Docker image located in a remote registry, you must ensure that the environment has the right credentials to pull the image.

anjuna-nitro-cli will search for registry credentials at well-known locations in the system, such as ${XDG_RUNTIME_DIR}/containers/auth.json, ~/.containers/auth.json, or ~/.docker/config.json. For more information, refer to the official containers-auth.json reference.

Enclave configuration file

When building the enclave, you can specify an enclave configuration file (using the --enclave-config-file command-line option) and override some of the attributes defined in the Docker image without updating the Docker image itself:

  • Environment variables

  • Startup command specified in the container (CMD/ENTRYPOINT)

  • Configuration files

  • Default user

In the enclave configuration file, you can also specify the S3 bucket that contains the encrypted secrets for the enclave. See Anjuna Nitro Enclave configuration for a complete description of the file format used to specify the enclave configuration.

Size limitation

Each file in the container image must be smaller than 4 GiB (4,294,967,296 bytes), the largest file size the cpio format of a Linux initrd can hold. If any file is 4 GiB or larger, build-enclave fails with an error like:

cpio: entry rootfs/data/model.bin: size 5368709120 does not fit the newc format

To include large data files in the enclave, split them into files smaller than 4 GiB, or mount them into the enclave using another method.

Starting an enclave requires at least 4 times the EIF size in memory, so a large EIF needs a correspondingly large --memory value and enough memory reserved for enclaves on the host.

Options

Usage

anjuna-nitro-cli build-enclave --docker-uri <docker-uri> --output-file <output-file> [OPTIONS...]

--docker-uri

(Required) URI pointing to an existing Docker image

The Docker image can be specified by:

  • A Docker URI to any container registry you have access to (for example, 1122334455.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest)

  • A local URI in the Docker image cache (for example, hello-world:latest)

Local images must be available in the Docker image cache.

Only Docker images with the platform linux/amd64 are supported. If you are using an Apple Silicon Mac or other ARM-based platform, you must explicitly specify --platform=linux/amd64 in your docker build command.

--docker-image-dir

Local path to an OCI Image Layout directory with a container image, which will be used for building an enclave image

The required --docker-uri parameter must also be specified, and should be set to the name of the image to use within this directory, as denoted by the org.opencontainers.image.ref.name annotation.

--docker-image-dir can be used to independently pull a container image before calling anjuna-nitro-cli build-enclave to build an enclave image. This provides greater flexibility when integrating with private container registries, especially those requiring specific authentication mechanisms, such as IAM credentials.

Tools that can be used to pull container images into an OCI Image Layout directory for use with this option include skopeo and crane.

--enclave-config-file

Local path to an enclave configuration file

Configuration files should be less than 560 MB in size in order to successfully build the enclave.

--name

Name for enclave image

--version

Version of the enclave image

--metadata

Path to the JSON file containing the custom metadata provided by the user

--output-file

(Required) Location where the enclave image should be saved

--private-key

Local path to developer’s Elliptic Curve private key

--signing-certificate

Local path to developer’s X509 signing certificate

If you choose to sign the EIF using your signing certificate, you need to monitor the signing certificate expiration. AWS Nitro Enclaves CLI performs validation on the signing certificate when the enclave starts, whether or not PCR8 is used for attestation. If the signing certificate has expired, it will prevent building the EIF and prevent the enclave from starting.

Global options

The following options are available for all commands.

Global options

-h, --help

Prints the help information for the command

-v, --version

Prints version information

Exit status

  • 0 on success

  • 1 on error

Example

The following command converts the Nginx Docker image (from Docker Hub) to an EIF named nginx.eif.

$ anjuna-nitro-cli build-enclave --docker-uri docker.io/library/nginx:latest --output-file nginx.eif

which produces output similar to this:

Enclave Image successfully created.
{
  "Measurements": {
    "HashAlgorithm": "Sha384 { ... }",
    "PCR0": "....",
    "PCR1": "....",
    "PCR2": "...."
  }
}