Enclave CLI子命令说明

本文介绍Enclave CLI所有子命令的详细用法,以帮助您更好地理解和使用Enclave CLI。

您也可以在安装Enclave CLI后分别运行如下命令来查看Enclave CLI所有子命令的列表和各子命令的用法说明。

enclave-cli --help         # 子命令列表
enclave-cli <sub-command> --help  # 子命令用法说明

build-enclave:构建Enclave

该子命令用于将Docker镜像转换为.eif格式的Enclave镜像文件,您可以通过指定一个包含Dockerfile的本地目录或Docker仓库中的镜像名来选择用于构建Enclave镜像文件的Docker镜像。

该子命令会返回Enclave镜像文件的基准度量值,可用于Enclave运行时的远程证明过程,与其运行时生成的度量值进行对比,若一致则表示此Enclave是可信的。

说明

阿里云虚拟化Enclave中的度量值,也称为PCR(Platform Configuration Register),在Enclave运行时由vTPM生成,完全遵循TPM 2.0标准。

用法

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

参数说明

参数

是否必选

类型

说明

--docker-uri

String

指定Docker仓库中已有Docker镜像的资源标识符,格式为<repository>:<tag>,用于生成Enclave镜像。

若同时指定了--docker-dir参数,则将以--docker-uri指定的URI在本地创建Docker镜像,再用它生成Enclave镜像。

--docker-dir

String

指定包含Dockerfile的本地目录路径,以创建用于生成Enclave镜像的Docker镜像。

--output-file

String

指定生成的Enclave镜像的文件名。

--private-key

String

指定用于对Enclave镜像文件签名的私钥文件(PEM格式)。

若指定了此参数,必须同时指定--signing-certificate参数。这样,Enclave CLI就会生成一个包含签名的Enclave镜像文件,并且本命令的输出会增加额外的PCR12,即签名证书的基准度量值,在远程证明过程中可用于验证Enclave镜像文件的构建者是否可信。

--signing-certificate

String

指定用于对Enclave镜像文件签名的证书文件(PEM格式),必须与--private-key参数同时使用。

请求示例

本示例展示如何将本地Docker镜像sample:latest转换成名为sample.eif的Enclave镜像文件。

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

返回示例

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

参数说明

参数

说明

Measurements

JSON格式,包含Enclave镜像文件的基准度量值。

HashAlgorithm

用于生成度量值的哈希算法。

PCR8

Enclave镜像文件的度量值。

PCR9

内核和启动引导程序的度量值。

PCR11

应用程序的度量值。

run-enclave:运行Enclave

该子命令用于根据您指定的Enclave镜像文件启动一个新的Enclave,同时会将Enclave资源分配服务预留的vCPU和内存资源分配给运行的Enclave。

说明

当前一个ECS实例中仅支持运行一个Enclave。

用法

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

该子命令的JSON配置文件格式如下:

{
    "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
}

参数说明

参数

是否必选

类型

说明

--config

String

指定存放Enclave启动参数的JSON配置文件路径。

若指定了此参数,则不能指定其他任何参数。此时所有参数都在该配置文件中以JSON格式指定。

--cpu-count

int

指定分配给Enclave的vCPU数量,其数量必须小于实例的vCPU总数,以确保实例自身留有可用的vCPU。

该参数是否为必选取决于--cpu-ids参数设置:

  • 若未指定--cpu-ids参数,则--cpu-count为必选。

  • 若已指定--cpu-ids参数,则不能指定--cpu-count

说明

若实例未启用超线程,则Enclave的vCPU数最少可为1;若实例启用了超线程(默认),则为了保证安全性,Enclave的vCPU数必须为偶数,至少为2,故实例必须至少为4 vCPU。您可以通过运行lscpu命令查看Thread(s) per core这一项的值是否为2来检查实例是否开启超线程。

--cpu-ids

int

指定分配给Enclave的vCPU ID列表,其数量必须小于实例的vCPU总数,以确保实例自身留有可用的vCPU。

若实例启用超线程,则vCPU数量必须为偶数,具体说明见--cpu-count参数说明。

该参数是否为必选取决于--cpu-count参数设置:

  • 若未指定--cpu-count参数,则--cpu-ids为必选。

  • 若已指定--cpu-count参数,则不能指定--cpu-ids

--memory

int

指定分配给Enclave的内存大小,单位:MiB。64 MiB≤memory<实例的内存总大小,并且必须满足Enclave运行的最小内存。

--eif-path

String

指定.eif格式的Enclave镜像文件路径。

--enclave-cid

int

指定Enclave在vsock通信中的CID地址,该CID必须至少为4。

若未指定该参数,则系统会为Enclave分配一个可用的CID。

--debug-mode

String

指定该参数表示令Enclave在调试模式下运行,未指定该参数则表示令Enclave在正常模式下运行。

只有在调试模式下,您才能通过enclave-cli console命令获取Enclave的运行时输出。此时Enclave运行产生的度量值皆为全零,不能通过远程证明的验证。

请求示例

本示例展示如何使用sample.eif镜像文件启动一个Enclave并为其分配2 vCPU、1024 MiB内存和值为10的vsock CID地址。

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

返回示例

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
}

参数说明

参数

说明

EnclaveID

标识Enclave的唯一ID。

ProcessID

实例中Enclave管理进程的PID。

EnclaveCID

Enclave的CID地址。

NumberOfCPUs

实例分配给Enclave的vCPU数量。

CPUIDs

实例分配给Enclave的vCPU ID列表。

MemoryMiB

实例分配给Enclave的内存大小,单位:MiB。

describe-enclaves:获取Enclave信息

该子命令无参数,用于获取当前正在运行的Enclave信息。

用法

enclave-cli describe-enclaves

请求示例

本示例展示如何获取实例中正在运行的Enclave信息。

enclave-cli describe-enclaves

返回示例

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

参数说明

参数

说明

EnclaveID

标识Enclave的唯一ID。

ProcessID

实例中Enclave管理进程的PID。

EnclaveCID

Enclave的CID地址。

NumberOfCPUs

实例分配给Enclave的vCPU数量。

CPUIDs

实例分配给Enclave的vCPU ID列表。

MemoryMiB

实例分配给Enclave的内存大小,单位:MiB。

State

Enclave的当前状态,可能值为RUNNINGTERMINATING

Flags

Enclave是否在调试模式下运行,可能值为DEBUG_MODE或NONE。

console:获取Enclave调试模式输出信息

该子命令用于获取一个正在运行的指定Enclave的输出内容,以便于排查Enclave应用程序的问题。

该子命令的输出就是Enclave运行时向标准输出打印的内容,无额外信息,故以下不再对命令输出进行说明。

说明

仅可用于带有--debug-mode参数启动的调试模式Enclave。

用法

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

参数说明

参数

是否必选

类型

说明

--enclave-id

String

指定要获取输出内容的Enclave ID

请求示例

本示例展示如何获取ID为12345678-1234-5678-1234-12345678****-enc1在调试模式下,Enclave的运行时输出内容。

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

返回示例

本命令会输出此Enclave的内核启动日志和应用程序运行时输出。当Enclave运行正常时,其输出应为如下所示内容。

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

terminate-enclave:终止Enclave

该子命令用于终止一个正在运行的Enclave。

用法

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

参数说明

参数

是否必选

类型

说明

--enclave-id

String

指定要获取输出内容的Enclave ID

请求示例

本示例展示如何终止运行ID为12345678-1234-5678-1234-12345678****-enc1的Enclave。

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

返回示例

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

参数说明

参数

说明

EnclaveID

标识Enclave的唯一ID。

Terminated

Enclave是否成功终止运行。可能值:truefalse

相关文档

当使用Enclave CLI子命令时,可能返回的错误码。关于错误说明,请参见错误码