Subcommands of the Enclave CLI - Elastic Compute Service

Build, run, inspect, debug, and terminate enclaves on ECS instances with the Enclave CLI.

After installing the Enclave CLI, run these commands to view subcommands and usage:

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

build-enclave

Builds an enclave image file (.eif) from a Docker image. Specify a local Dockerfile directory or a Docker repository image name.

The output includes baseline measurements of the enclave image. During remote attestation, these measurements are compared with runtime values to verify enclave integrity.

Note

In Alibaba Cloud virtualization enclaves, measurements (Platform Configuration Registers, or PCRs) are generated by a vTPM at runtime and comply with TPM 2.0.

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

Parameters

Parameter	Required	Type	Description
`--docker-uri`	Yes	String	The Docker image URI in `<repository>:<tag>` format. If `--docker-dir` is also specified, a local Docker image is built with the URI from `--docker-uri` and used to generate the enclave image.
`--docker-dir`	No	String	The path to a local directory containing a Dockerfile. Used to build the Docker image for enclave image generation.
`--output-file`	Yes	String	The output filename for the enclave image.
`--private-key`	No	String	The PEM-format private key file for signing the enclave image. Requires `--signing-certificate`. The CLI generates a signed enclave image and outputs an additional `PCR12` value — the baseline measurement of the signing certificate, used in remote attestation to verify the image builder.
`--signing-certificate`	No	String	The PEM-format certificate file for signing the enclave image. Must be used with `--private-key`.

Example

Build an enclave image sample.eif from the Docker image sample:latest:

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

Output

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

Output fields

Parameter	Description
Measurements	Baseline measurements of the enclave image in JSON format.
HashAlgorithm	The hash algorithm for generating measurements.
PCR8	The enclave image measurement.
PCR9	The kernel and bootloader measurement.
PCR11	The application measurement.

run-enclave

Launches an enclave from an image file with 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, 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
}

Parameters

Parameter	Required	Type	Description
`--config`	No	String	Path to a JSON configuration file with enclave startup parameters. If specified, do not use other parameters. All parameters must be defined in this file in JSON format.
`--cpu-count`	No	int	The number of vCPUs to assign to the enclave. Must be less than the total vCPUs on the instance. Whether this parameter is required depends on whether you specify `--cpu-ids`: If you do not specify `--cpu-ids`, `--cpu-count` is required. If you specify `--cpu-ids`, do not specify `--cpu-count`. Note If hyper-threading is disabled, the enclave can use 1 vCPU. If hyper-threading is enabled (default), the enclave requires an even number of vCPUs (minimum 2), so the instance must have at least 4 vCPUs. Run `lscpu` and check that `Thread(s) per core` is 2 to verify hyper-threading.
`--cpu-ids`	No	int	A list of vCPU IDs to assign to the enclave. The count must be less than the total vCPUs on the instance. If hyper-threading is enabled, the vCPU count must be even. See `--cpu-count` for details. Whether this parameter is required depends on whether you specify `--cpu-count`: If you do not specify `--cpu-count`, `--cpu-ids` is required. If you specify `--cpu-count`, do not specify `--cpu-ids`.
`--memory`	Yes	int	Memory size for the enclave in MiB. Valid values: 64 MiB to less than the instance total memory. Must also meet the minimum enclave runtime requirement.
`--eif-path`	Yes	String	Path to the `.eif` enclave image file.
`--enclave-cid`	No	int	The vsock CID for the enclave. Must be at least 4. If omitted, the system assigns an available CID.
`--debug-mode`	No	String	Enables debug mode. Omit to run in normal mode. In debug mode, use `enclave-cli console` to view runtime output. All attestation measurements are zero in debug mode and cannot pass remote attestation.

Example: Launch with inline parameters

Launch an enclave from sample.eif with 2 vCPUs, 1,024 MiB memory, and CID 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 enclave ID.
ProcessID	The PID of the enclave management process.
EnclaveCID	The enclave CID.
NumberOfCPUs	The vCPU count.
CPUIDs	The vCPU IDs.
MemoryMiB	The memory allocated in MiB.

describe-enclaves

Returns information about the enclave on the current instance.

Syntax

enclave-cli describe-enclaves

Example

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 enclave ID.
ProcessID	The enclave management process PID.
EnclaveCID	The enclave CID.
NumberOfCPUs	The vCPU count.
CPUIDs	The vCPU IDs.
MemoryMiB	The memory allocated in MiB.
State	The enclave state. Valid values: `RUNNING`, `TERMINATING`.
Flags	The debug mode flag. Valid values: `DEBUG_MODE`, `NONE`.

console

Reads runtime output of a running enclave for troubleshooting, including kernel startup logs and application output.

Note

Requires the enclave to be started with --debug-mode.

Syntax

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

Parameters

Parameter	Required	Type	Description
`--enclave-id`	Yes	String	The enclave ID. Obtain from `run-enclave` or `describe-enclaves` output.

Example

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

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

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 and releases its resources.

Syntax

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

Parameters

Parameter	Required	Type	Description
`--enclave-id`	Yes	String	The enclave ID. Obtain from `run-enclave` or `describe-enclaves` output.

Example

Terminate enclave 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 terminated enclave ID.
Terminated	Whether the enclave was terminated. Valid values: `true`, `false`.

References

Enclave CLI subcommands may return error codes.