Enclave CLI所有子命令的详细用法 - Elastic Compute Service

This topic describes the subcommands that are available in the Enclave CLI to help you understand and use the Enclave CLI.

After you install the Enclave CLI, you can run the following commands to view all Enclave CLI subcommands and the usage notes for each subcommand:

enclave-cli --help # Lists all Enclave CLI subcommands.
enclave-cli <sub-command> --help # Displays the usage notes for the specified command.

build-enclave

Converts a Docker image into an enclave image file in .eif format. To specify a Docker image, you can specify an on-premises directory that contains a Dockerfile or specify a Docker image in a Docker repository.

The subcommand returns a set of measurements of the enclave image file. The system compares these measurements with the measurements that are generated when the enclave runs. If the two sets of measurements match, the enclave is attested.

Note

In the Enclave CLI of Alibaba Cloud, these measurements are provided in the form of platform configuration registers (PCRs). These PCRs are generated by virtual Trusted Platform Modules (vTPMs) and comply with the TPM 2.0 standard.

Syntax

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 uniform resource identifier (URI) of a Docker image in a Docker repository. The URI is in the `<repository>:<tag>` format. If you specify the `--docker-dir` parameter, an on-premises Docker image is created by using the URI that is specified by the `--docker-uri` parameter to help generate an enclave image.
`--docker-dir`	No	String	The path of an on-premises directory that contains a Dockerfile. The path is used to create a Docker image based on which an enclave image is generated.
`--output-file`	Yes	String	The name of the enclave image file.
`--private-key`	No	String	The private key file in .pem format that you want to use to sign the enclave image file. If you specify this parameter, you must also specify the `--signing-certificate` parameter. If you specify these parameters, the command creates a signed enclave image file. The command output includes an additional `PCR12` value that you can use to attest the creator of the signed file during the attestation process. PCR12 is a measurement of the signing certificate specified for the signed file.
`--signing-certificate`	No	String	The key file in .pem format that you want to use to sign the enclave image file. If you specify this parameter, you must also specify the `--private-key` parameter.

Sample command

In this example, a Docker image whose URI is sample:latest is converted into an enclave image file named sample.eif.

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

Sample output

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

Parameters

Parameter	Description
Measurements	The measurements of the enclave image file in JSON format.
HashAlgorithm	The hashing algorithm that is used to generate the measurements.
PCR8	A measurement of the enclave image file.
PCR9	A measurement of the kernel and the boot loader.
PCR11	A measurement of the applications.

run-enclave

Starts a new enclave based on an enclave image file. In the process, the preserved vCPUs and memory are allocated to the new enclave.

Note

You can run only one enclave on an ECS instance.

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

The JSON configuration file of this subcommand is in the following format:

{
    "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	The path of the JSON configuration file that contains the startup parameters of the enclave. If you specify this parameter, no other parameters can be specified because all parameters are specified in the JSON configuration file.
`--cpu-count`	No	int	The number of vCPUs to allocate to the enclave. The number must be less than the total number of vCPUs of the instance. Otherwise, the instance cannot work as expected due to the lack of available vCPUs. If you do not specify the `--cpu-ids` parameter, you must specify the `--cpu-count` parameter. If you specify the `--cpu-ids` parameter, you cannot specify the `--cpu-count` parameter. Note If hyper-threading is disabled for the instance, you can allocate at least one vCPU to the enclave. If hyper-threading is enabled for the instance (default setting), the number of vCPUs must be an even number, which is at least two for the enclave and at least four for the instance. You can run the `lscpu` command and view the value of `Thread(s) per core` in the command output to check whether hyper-threading is enabled for an instance. If the value is 2, hyper-threading is enabled.
`--cpu-ids`	No	int	The IDs of the vCPUs to allocate to the enclave. The number of vCPUs must be less than the total number of vCPUs of the instance. Otherwise, the instance cannot work as expected due to the lack of available vCPUs. If hyper-threading is enabled for the instance, the number of vCPUs must be an even number. For more information, see the description of the `--cpu-count` parameter. If you do not specify the `--cpu-count` parameter, you must specify the `--cpu-ids` parameter. If you specify the `--cpu-count` parameter, you cannot specify the `--cpu-ids` parameter.
`--memory`	Yes	int	The amount of memory to allocate to the enclave. Unit: MiB. The memory size must be greater than or equal to 64 MiB and less than the total memory size of the instance. The memory size must also be large enough to support the operation of the enclave.
`--eif-path`	Yes	String	The path of the enclave image file in `.eif` format.
`--enclave-cid`	No	int	The context identifier (CID) of the enclave, which is used to define the VM Sockets (vsock) address of the enclave. Only CIDs of 4 and greater can be specified. If you do not specify this parameter, the system assigns an available CID to the enclave.
`--debug-mode`	No	String	Specifies whether to run the enclave in debug mode. Specify this parameter to enable debug mode, or leave this parameter empty to disable debug mode. You can run the `enclave-cli console` command to obtain the runtime output of the enclave only if the enclave runs in debug mode. The measurements that are generated when the enclave runs in debug mode are all zeros. You cannot attest the enclave.

Sample command

In this example, a sample.eif image file is used to run an enclave that is allocated 2 vCPUs and 1,024 MiB of memory and assigned a CID of 10.

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

Sample 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
}

Parameters

Parameter	Description
EnclaveID	The unique ID of the enclave.
ProcessID	The process identifier (PID) of the process that manages the resources of the enclave.
EnclaveCID	The CID of the enclave.
NumberOfCPUs	The number of vCPUs that are allocated to the enclave from the instance.
CPUIDs	The IDs of the vCPUs that are allocated to the enclave from the instance.
MemoryMiB	The amount of memory that is allocated to the enclave from the instance. Unit: MiB.

describe-enclaves

Queries information about an enclave that is running.

Syntax

enclave-cli describe-enclaves

Sample command

In this example, information about an enclave that is running is queried.

enclave-cli describe-enclaves

Sample output

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

Parameters

Parameter	Description
EnclaveID	The unique ID of the enclave.
ProcessID	The PID of the process that manages the resources of the enclave.
EnclaveCID	The CID of the enclave.
NumberOfCPUs	The number of vCPUs that are allocated to the enclave from the instance.
CPUIDs	The IDs of the vCPUs that are allocated to the enclave from the instance.
MemoryMiB	The amount of memory that is allocated to the enclave from the instance. Unit: MiB.
State	The state of the enclave. Valid values: `RUNNING` and `TERMINATING`.
Flags	Indicates whether the enclave is running in debug mode. Valid values: DEBUG_MODE and NONE.

console

Queries the output of an enclave that is running. This helps you troubleshoot applications in the enclave.

The command output is the standard output of the enclave when the enclave is running. No additional information exists. Therefore, the command output is not described.

Note

You can run this subcommand only on an enclave that was run with the --debug-mode parameter specified.

Syntax

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

Parameters

Parameter	Required	Type	Description
`--enclave-id`	Yes	String	The ID of the enclave.

Sample command

In this example, the output of an enclave that is running in debug mode and has an ID of 12345678-1234-5678-1234-12345678****-enc1 is queried.

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

Sample output

The command output is the kernel startup logs and the runtime output of the applications. If the enclave runs as expected, a command output similar to the following one is returned:

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

terminate-enclave

Terminates an enclave that is running.

Syntax

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

Parameters

Parameter	Required	Type	Description
`--enclave-id`	Yes	String	The ID of the enclave.

Sample command

In this example, an enclave that is running and has an ID of 12345678-1234-5678-1234-12345678****-enc1 is terminated.

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

Sample output

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

Parameters

Parameter	Description
EnclaveID	The unique ID of the enclave.
Terminated	Indicates whether the enclave is terminated. Valid values: `true` and `false`.

References

Error codes may be returned when you use Enclave CLI subcommands. For more information, see Error codes.