Reference guide for Enclave CLI subcommands - Elastic Compute Service

The Enclave CLI manages the full lifecycle of enclaves on ECS instances -- building enclave images, launching enclaves, inspecting their state, reading debug output, and terminating them.

After you install the Enclave CLI, run the following commands to view available subcommands and their usage:

enclave-cli --help                      # List all subcommands
enclave-cli <sub-command> --help        # Show usage for a specific subcommand

build-enclave: Build an enclave image

This subcommand transforms a Docker image into an enclave image file with the .eif extension. To specify the Docker image, provide a path to a local directory containing a Dockerfile or an image name from a Docker repository.

The subcommand returns the baseline measurements of the enclave image file. During remote attestation, these measurements are compared with the values generated by the enclave runtime. If the measurements match, the enclave is considered trusted.

Note

In Alibaba Cloud virtualization enclaves, measurements—also known as Platform Configuration Registers (PCRs)—are generated by a vTPM during runtime and fully comply with the TPM 2.0 standard.

Usage

enclave-cli build-enclave \
  --docker-uri <repository>:<tag> \
  --output-file <enclave-image-filename> \
  [ --docker-dir <path-to-dockerfile-directory> ] \
  [ --private-key <private-key> --signing-certificate <certificate> ]

Parameter descriptions

Parameter	Required	Type	Description
`--docker-uri`	Yes	String	The resource identifier of an existing Docker image in a Docker repository. The format is `<repository>:<tag>`. This image is used to generate the enclave image. If `--docker-dir` is also specified, a Docker image is created locally with the URI from `--docker-uri`. This local image is then used to generate the enclave image.
`--docker-dir`	No	String	The path to a local directory that contains a Dockerfile. This directory is used to create the Docker image that generates the enclave image.
`--output-file`	Yes	String	The filename for the generated enclave image.
`--private-key`	No	String	The private key file in PEM format used to sign the enclave image file. If this parameter is specified, the `--signing-certificate` parameter is also required. The Enclave command-line interface (CLI) then generates a signed enclave image file. The command output includes an additional `PCR12` value. This value is the baseline measurement of the signing certificate and can be used during remote attestation to authenticate the builder of the enclave image file.
`--signing-certificate`	No	String	The certificate file in PEM format used to sign the enclave image file. This parameter must be used with the `--private-key` parameter.

Example request

This example transforms the local Docker image sample:latest into an enclave image file named sample.eif.

enclave-cli build-enclave --docker-uri sample:latest --output-file sample.eif

Example response

Start building the Enclave Image...
Enclave Image successfully created.
{
  "Measurements": {
    "HashAlgorithm": "Sha256 { ... }",
    "PCR11": "dc5dcd841f87e2b6c0e65a11b46b25ebe2999a8a5f0318e10c0175b60000****",
    "PCR8": "2c6944f47864f1f8ab276000a9f057fcdf9f56a015c0bc5e2339f24b0000****",
    "PCR9": "8ef5fe53a7709cc1c1a0aa7b5149a55bcd524cccc9f43e7a3baf44ca0000****"
  }
}

Parameter descriptions

Parameter	Description
Measurements	Contains the baseline measurements of the enclave image file in JSON format.
HashAlgorithm	The hash algorithm used to generate the measurements.
PCR8	The measurement of the enclave image file.
PCR9	The measurement of the kernel and bootloader.
PCR11	The measurement of the application.

run-enclave

Starts a new enclave from an enclave image file, allocating the specified vCPUs and memory.

Note

Only one enclave can run on an ECS instance at a time.

Syntax

enclave-cli run-enclave \
  --cpu-count <vcpu-count> \
  --cpu-ids <list-of-vcpu-ids> \
  --memory <amount-of-memory-in-MiB> \
  --eif-path <enclave-image-file-path> \
  [ --enclave-cid <enclave-cid> ] \
  [ --debug-mode ] \
  [ --config <json-config-file> ]

Alternatively, you can specify all parameters in a JSON configuration file:

{
    "cpu_count": <vcpu-count>,
    "cpu_ids": <list-of-vcpu-ids>,
    "memory_mib": <amount-of-memory-in-MiB>,
    "eif_path": "<enclave-image-file-path>",
    "enclave_cid": <enclave-cid>,
    "debug_mode": true|false
}

Parameter description

Parameter	Required	Type	Description
`--config`	No	String	Specify the path to the JSON configuration file that contains enclave startup parameters. If you specify this parameter, do not specify any other parameters. All parameters must be defined in this configuration file in JSON format.
`--cpu-count`	No	int	Specify the number of vCPUs to assign to the enclave. This number must be less than the total number of vCPUs on the instance to ensure that the instance retains available vCPUs. Whether this parameter is required depends on whether you specify `--cpu-ids`: If you do not specify `--cpu-ids`, then `--cpu-count` is required. If you specify `--cpu-ids`, do not specify `--cpu-count`. Note If hyper-threading is disabled on the instance, the enclave can use as few as 1 vCPU. If hyper-threading is enabled (default), the enclave must use an even number of vCPUs for security. The minimum is 2 vCPUs, so the instance must have at least 4 vCPUs. To check whether hyper-threading is enabled, run the `lscpu` command and verify that the value of `Thread(s) per core` is 2.
`--cpu-ids`	No	int	Specify a list of vCPU IDs to assign to the enclave. The number of IDs must be less than the total number of vCPUs on the instance to ensure that the instance retains available vCPUs. If hyper-threading is enabled, the number of vCPUs must be even. For details, see the description for `--cpu-count`. Whether this parameter is required depends on whether you specify `--cpu-count`: If you do not specify `--cpu-count`, then `--cpu-ids` is required. If you specify `--cpu-count`, do not specify `--cpu-ids`.
`--memory`	Yes	int	Specify the memory size to assign to the enclave, in MiB. Valid values: 64 MiB ≤ memory < total memory of the instance. The value must also meet the minimum memory requirement for enclave runtime.
`--eif-path`	Yes	String	Specify the path to the enclave image file in `.eif` format.
`--enclave-cid`	No	int	Specify the CID address for the enclave in vsock communication. The CID must be at least 4. If you do not specify this parameter, the system assigns an available CID to the enclave.
`--debug-mode`	No	String	Specify this parameter to run the enclave in debug mode. Do not specify it to run the enclave in normal mode. In debug mode only, you can use the `enclave-cli console` command to view the enclave's runtime output. In debug mode, all attestation measurements are zero and cannot pass remote attestation validation.

Example: Run an enclave with inline parameters

Launch an enclave from the sample.eif image file with 2 vCPUs, 1,024 MiB of memory, and a CID of 10:

enclave-cli run-enclave --cpu-count 2 --memory 1024 --eif-path sample.eif --enclave-cid 10

Output:

Start allocating memory...
Started enclave with enclave-cid: 10, memory: 1024 MiB, cpu-ids: [2, 3]
{
    "EnclaveID": "12345678-1234-5678-1234-123456781234-enc1",
    "ProcessID": 1234,
    "EnclaveCID": 10,
    "NumberOfCPUs": 2,
    "CPUIDs": [
        2,
        3
    ],
    "MemoryMiB": 1024
}

Output fields

Field	Description
EnclaveID	The unique ID of the enclave.
ProcessID	The process identifier (PID) of the process that manages enclave resources.
EnclaveCID	The CID assigned to the enclave.
NumberOfCPUs	The number of vCPUs allocated to the enclave.
CPUIDs	The IDs of the vCPUs allocated to the enclave.
MemoryMiB	The amount of memory allocated to the enclave, in MiB.

describe-enclaves

Returns information about the enclave running on the current instance.

Syntax

enclave-cli describe-enclaves

Example: Query enclave status

enclave-cli describe-enclaves

Output:

[
  {
    "EnclaveID": "12345678-1234-5678-1234-123456781234-enc1",
    "ProcessID": 1234,
    "EnclaveCID": 10,
    "NumberOfCPUs": 2,
    "CPUIDs": [
      2,
      3
    ],
    "MemoryMiB": 1024,
    "State": "RUNNING",
    "Flags": "DEBUG_MODE"
  }
]

Output fields

Field	Description
EnclaveID	The unique ID of the enclave.
ProcessID	The PID of the process that manages enclave resources.
EnclaveCID	The CID of the enclave.
NumberOfCPUs	The number of vCPUs allocated to the enclave.
CPUIDs	The IDs of the vCPUs allocated to the enclave.
MemoryMiB	The amount of memory allocated to the enclave, in MiB.
State	The enclave state. Valid values: `RUNNING`, `TERMINATING`.
Flags	Whether the enclave runs in debug mode. Valid values: `DEBUG_MODE`, `NONE`.

console

Reads the runtime output of a running enclave for troubleshooting. The output includes kernel startup logs and application output.

Note

This command requires the enclave to have been started with the --debug-mode flag.

Syntax

enclave-cli console --enclave-id <enclave-id>

Parameters

Parameter	Required	Type	Description
`--enclave-id`	Yes	String	Get the enclave ID from output.

Example: Read debug output

Read the output of a debug-mode enclave with the ID 12345678-1234-5678-1234-12345678****-enc1:

enclave-cli console --enclave-id 12345678-1234-5678-1234-12345678****-enc1

Output (kernel startup logs followed by application output):

[   1] Hello from the enclave side!
[   2] Hello from the enclave side!
[   3] Hello from the enclave side!
...

terminate-enclave

Terminates a running enclave.

Syntax

enclave-cli terminate-enclave --enclave-id <enclave-id>

Parameters

Parameter	Required	Type	Description
`--enclave-id`	Yes	String	Get the enclave ID from output.

Example: Terminate a running enclave

Terminate the enclave with the ID 12345678-1234-5678-1234-123456781234-enc1:

enclave-cli terminate-enclave --enclave-id 12345678-1234-5678-1234-123456781234-enc1

Output:

Successfully terminated enclave 12345678-1234-5678-1234-123456781234-enc1.
{
  "EnclaveID": "12345678-1234-5678-1234-123456781234-enc1",
  "Terminated": true
}

Output fields

Field	Description
EnclaveID	The unique ID of the terminated enclave.
Terminated	Whether the enclave was terminated. Valid values: `true`, `false`.

References

Error codes may be returned when running Enclave CLI subcommands. For details, see Error codes.