# Nitro Enclaves Command Line Interface
The Nitro Enclaves CLI (Nitro CLI) is a command line tool for managing the lifecycle of enclaves. You can use the Nitro CLI to create, manage, and terminate enclaves. The Nitro CLI must be installed on the Amazon EC2 parent instance.
**Topics**
+ [Install the CLI on Linux](nitro-enclave-cli-install.md)
+ [Install the CLI on Windows](nitro-enclave-cli-install-win.md)
+ [Uninstall the CLI on Linux](uninstall-cli.md)
+ [Uninstall the CLI on Windows](uninstall-cli-win.md)
+ [Nitro CLI Reference](nitro-enclave-cli-ref.md)
+ [
# Nitro Enclaves CLI error codes
](cli-errors.md)
# Install the Nitro Enclaves CLI on Linux
The following instructions are for installing or uninstalling the AWS Nitro Enclaves CLI on or from a parent instance running Amazon Linux 2023 or Amazon Linux 2. For instructions for installing the Nitro CLI on different Linux distributions, see the [Nitro CLI github repository](https://github.com/aws/aws-nitro-enclaves-cli).
------
#### [ Amazon Linux 2023 ]
**To install the Nitro CLI on an instance running AL2023**
1. Install the Nitro CLI.
```
$ sudo dnf install aws-nitro-enclaves-cli -y
```
1. Install the Nitro Enclaves development tools needed to build enclave images. The development tools also includes some sample applications.
```
$ sudo dnf install aws-nitro-enclaves-cli-devel -y
```
1. Add your user to the `ne` user group.
```
$ sudo usermod -aG ne username
```
1. Add your user to the `docker` user group.
```
$ sudo usermod -aG docker username
```
**Important**
For the permissions changes to take effect, log out of the instance and then reconnect to it.
1. Verify that the Nitro CLI installed correctly.
```
$ nitro-cli --version
```
The command should return version information about the Nitro CLI.
1. Preallocate the memory and the vCPUs that you intend to use for the enclaves.
**Important**
Nitro Enclaves uses an allocator service to preallocate vCPUs and memory to the enclaves. The amount of vCPUs and memory to preallocate are defined in the allocator service configuration file (`/etc/nitro_enclaves/allocator.yaml`). By default, the configuration file is set up to preallocate 512 MiB of memory and 2 vCPUs for use by the enclaves. In some cases, you might need to manually update the configuration file to preallocate a different number vCPUs or amount of memory. For example:
If you launched an AWS Graviton-based instance with 2 vCPUs, you must configure the allocate service to preallocate only 1 vCPU.
If you launched an instance with 4 or more vCPUs, you can configure the allocator service to preallocate more vCPUs to the enclave.
If you are going to run multiple enclaves, you must configure the allocator service to preallocate enough vCPUs and memory for all of the enclaves. For example, to run 3 enclaves with 4 vCPUs and 2 GiB memory each, you must configure the allocator service to preallocate 12 vCPUs and 6 GiB of memory.
If you need to change the configuration file, use your preferred text editor to open `/etc/nitro_enclaves/allocator.yaml`. Then, for `memory_mib` and `cpu_count`, specify the overall amount of memory (in MiB) and the number of vCPUs that you want to preallocate. Save and close the file and then run the command below.
If you want to preallocate the default 512 MiB of memory and 2 vCPUs, you do not need to make any changes to the configuration file.
Run the following command to allocate the resource specified in the configuration file and to ensure that they are automatically allocated every time the instance starts.
```
$ sudo systemctl enable --now nitro-enclaves-allocator.service
```
**Note**
When you create an enclave, the requested memory and vCPUs must be less than or equal to the values that you specified here. If you need to create an enclave with more memory or vCPUs in the future, you must update the values in this file and restart the service.
1. Start the Docker service and ensure that it starts every time the instance starts.
```
$ sudo systemctl enable --now docker
```
------
#### [ Amazon Linux 2 ]
**To install the Nitro CLI on an instance running AL2**
1. Install the Nitro CLI.
```
$ sudo amazon-linux-extras install aws-nitro-enclaves-cli -y
```
1. Install the Nitro Enclaves development tools needed to build enclave images. The development tools also includes some sample applications.
```
$ sudo yum install aws-nitro-enclaves-cli-devel -y
```
1. Add your user to the `ne` user group.
```
$ sudo usermod -aG ne username
```
1. Add your user to the `docker` user group.
```
$ sudo usermod -aG docker username
```
**Important**
For the permissions changes to take effect, log out of the instance and then reconnect to it.
1. Verify that the Nitro CLI installed correctly.
```
$ nitro-cli --version
```
The command should return version information about the Nitro CLI.
1. Preallocate the memory and the vCPUs that you intend to use for the enclaves.
**Important**
Nitro Enclaves uses an allocator service to preallocate vCPUs and memory to the enclaves. The amount of vCPUs and memory to preallocate are defined in the allocator service configuration file (`/etc/nitro_enclaves/allocator.yaml`). By default, the configuration file is set up to preallocate 512 MiB of memory and 2 vCPUs for use by the enclaves. In some cases, you might need to manually update the configuration file to preallocate a different number vCPUs or amount of memory. For example:
If you launched an AWS Graviton-based instance with 2 vCPUs, you must configure the allocate service to preallocate only 1 vCPU.
If you launched an instance with 4 or more vCPUs, you can configure the allocator service to preallocate more vCPUs to the enclave.
If you are going to run multiple enclaves, you must configure the allocator service to preallocate enough vCPUs and memory for all of the enclaves. For example, to run 3 enclaves with 4 vCPUs and 2 GiB memory each, you must configure the allocator service to preallocate 12 vCPUs and 6 GiB of memory.
If you need to change the configuration file, use your preferred text editor to open `/etc/nitro_enclaves/allocator.yaml`. Then, for `memory_mib` and `cpu_count`, specify the overall amount of memory (in MiB) and the number of vCPUs that you want to preallocate. Save and close the file and then run the command below.
If you want to preallocate the default 512 MiB of memory and 2 vCPUs, you do not need to make any changes to the configuration file.
Run the following command to allocate the resource specified in the configuration file and to ensure that they are automatically allocated every time the instance starts.
```
$ sudo systemctl enable --now nitro-enclaves-allocator.service
```
**Note**
When you create an enclave, the requested memory and vCPUs must be less than or equal to the values that you specified here. If you need to create an enclave with more memory or vCPUs in the future, you must update the values in this file and restart the service.
1. Start the Docker service and ensure that it starts every time the instance starts.
```
$ sudo systemctl enable --now docker
```
------
# Install the Nitro Enclaves CLI on Windows
The AWS Nitro Enclaves CLI is packaged together with all of the components that are required to run Nitro Enclaves on a Windows parent instance. The package includes kernel drivers for the Enclave and vsock devices, a service provider interface for Winsock to support vsock sockets, the vsock-proxy, and the AWS Nitro Enclaves CLI.
The following instructions are for installing and uninstalling the AWS Nitro Enclaves CLI on or from a parent instance running Windows.
**Note**
You may get the following error when you install, uninstall, or update the Nitro CLI: `Installation failed with code 3010`. This message indicates that a reboot is required to complete the installation. This error is likely caused by a component in use, such as a running enclave or a vsock-proxy process. To complete the installation, shut down all applications running on the instance and reboot it.
## Install Nitro CLI
To use the Nitro Enclaves on your parent instance, you must install the ** AWSNitroEnclavesWindows** package using AWS Systems Manager Distributor.
Before you can install a package using the AWS Systems Manager Distributor, you must first [complete the Distributor prerequisites](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-prerequisites.html).
After you have completed the prerequisites, install the **AWSNitroEnclavesWindows** package. For more information, see one of the following in the *AWS Systems Manager User Guide*:
+ [ Installing or updating a package one time using the console](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html#distributor-deploy-pkg-console)
+ [ Installing a package one time using the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html#distributor-deploy-pkg-cli)
You must reload the path environment variable from the updated environment in any PowerShell or command prompt already open on the instance. When you open a new PowerShell or command prompt, Windows automatically updates the path variable.
# Uninstall the Nitro Enclaves CLI on Linux
If you no longer want to use AWS Nitro Enclaves on your Linux instance, use the following command to uninstall the AWS Nitro Enclaves CLI.
------
#### [ Amazon Linux 2023 ]
```
$ sudo dnf remove aws-nitro-enclaves-cli
```
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove aws-nitro-enclaves-cli
```
------
# Uninstall the Nitro Enclaves CLI on Windows
If you no longer want to use AWS Nitro Enclaves on your Windows instance, you can remove the AWS Nitro Enclaves CLI from the parent instance by uninstalling the **AWSNitroEnclavesWindows** package using the AWS Systems Manager Distributor. For more information see [Uninstall a package](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-uninstall.html) in the *AWS Systems Manager User Guide*.
Alternatively, you can uninstall the AWS Nitro Enclaves CLI using **Programs and Features**, which can be accessed using the Windows Control Panel.
# Nitro Enclaves Command Line Interface reference
The following commands are available in the Nitro CLI. All of the Nitro CLI commands start with `nitro-cli`, followed by one of the following subcommands. To view the command line help for a command, add the `--help` option.
**Topics**
+ [
# nitro-cli build-enclave
](cmd-nitro-build-enclave.md)
+ [
# nitro-cli run-enclave
](cmd-nitro-run-enclave.md)
+ [
# nitro-cli describe-enclaves
](cmd-nitro-describe-enclaves.md)
+ [
# nitro-cli console
](cmd-nitro-console.md)
+ [
# nitro-cli describe-eif
](cmd-nitro-describe-eif.md)
+ [
# nitro-cli sign-eif
](cmd-nitro-sign-eif.md)
+ [
# nitro-cli pcr
](cmd-nitro-pcr.md)
+ [
# nitro-cli terminate-enclave
](cmd-nitro-terminate-enclave.md)
# nitro-cli build-enclave
Converts a Docker image into an enclave image file (`.eif`). You can specify either a local directory containing a Dockerfile, or a Docker image in a Docker repository.
**Important**
This command is not supported on Windows. If you are using a Windows parent instance, you must run this command on a Linux computer and then transfer the enclave image file (`.eif`) to the Windows parent instance.
You can build enclave images files using the Nitro CLI on any Linux environment, including outside of AWS. To manage the lifecycle of an instance—such as with the `run-enclave` command—you will need to use the Nitro CLI on a parent instance (EC2 instance with Nitro Enclave enabled).
The command returns a set of measurements (SHA384 hashes) that are unique to the enclave image file. These measurements are provided in the form of platform configuration registers (PCRs). The PCRs are used during the enclave's attestation process. For more information, see [Nitro Enclaves concepts](nitro-enclave-concepts.md).
For example, when using Nitro Enclaves with AWS Key Management Service (AWS KMS), you can specify these PCRs in condition keys for customer managed keys policies. When an application in the enclave performs an AWS KMS operation, AWS KMS compares the PCRs in the enclave's signed attestation document with the PCRs specified in the condition keys of the KMS key policy before allowing the operation.
## Syntax
```
nitro-cli build-enclave
--docker-uri repository:tag
[--docker-dir /path_to/dockerfile_directory ]
--output-file file-location
[--private-key key]
--signing-certificate certificate.pem
[--name image_name]
[--version image_version]
```
## Options
**`--docker-uri`**
The uniform resource identifier (URI) of a Docker image in a Docker repository. The URI is specified using the `repository`:`tag` format.
Type: String
Required: Yes
**`--docker-dir`**
The path to a local directory containing a Dockerfile.
Type: String
Required: No
**`--output-file`**
The file name of the enclave image file that is created.
Type: String
Required: Yes
**`--private-key `**
The private key to use to sign the enclave image file. This can be a KMS key ARN, or a path to a local private key file. For more information, see [Key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).
Only ECDSA keys are supported for code for signing. If you specify `--private-key` then you must also specify `--signing-certificate`. If you specify this parameter, the command creates a signed enclave image file. The command output will include an additional PCR, `PCR8`, which can be used in condition keys for KMS key policies. For more information, see [Where to get an enclave's measurements](set-up-attestation.md#where).
Type: String
Required: No
**`--signing-certificate`**
The signing key to use to sign the enclave image file. If you specify `--signing-certificate` then you must also specify `--private-key`. If you specify these parameters, the command creates a signed enclave image file. The command output will include and additional PCR, `PCR8`, which can be used in condition keys for KMS key policies. For more information, see [Where to get an enclave's measurements](set-up-attestation.md#where).
Ensure that the specified certificate is still valid. If you attempt to start an enclave with an enclave image file that is signed with a certificate that is no longer valid, the `nitro-cli run-enclave` fails with errors `E36`, `E39`, and `E11`.
Type: String
Required: No
## Output
**`Measurements`**
The cryptographic measurements (SHA384 hashes) that are unique to the enclave image file.
Type: String
## Example
The following example converts a Docker image with a URI of `sample:latest` to an enclave image file named `sample.eif`.
**Command**
```
nitro-cli build-enclave --docker-uri sample:latest --output-file sample.eif
```
**Output**
```
Enclave Image successfully created.
{
"Measurements": {
"HashAlgorithm": "Sha384 { ... }",
"PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
"PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
"PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE"
}
}
```
The following example converts a Docker image with a URI of `sample:latest` to an enclave image file named `sample.eif`, and signs it using a KMS key.
**Command**
```
nitro-cli build-enclave --docker-uri sample:latest --output-file sample.eif --private-key arn:aws:kms:eu-west-1:123456789321:key/abcdef12-3456-789a-bcde-111122223333 --signing-certificate certificate.pem
```
**Output**
```
Enclave Image successfully created.{
"Measurements": {
"HashAlgorithm": "Sha384 { ... }",
"PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
"PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
"PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE",
"PCR8": "EXAMPLEdcca7f74398ae152d6ee245d8ac2cd430fb63644b46bf47b7d36b53b91c7597edda2d5df772cc81b72EXAMPLE"
}
}
```
# nitro-cli run-enclave
Launches a new enclave. This command partitions the specified number of vCPUs and the amount of memory from the Amazon EC2 parent instance to create the enclave. You also need to provide an enclave image file (`.eif`) that contains the operating system and the applications that you want to run inside the enclave.
**Important**
If you attempt to start an enclave with an enclave image file that is signed with a certificate that is no longer valid, the `nitro-cli run-enclave` command fails with errors `E36`, `E39`, and `E11`.
## Syntax
```
nitro-cli run-enclave
[--enclave-name enclave_name]
[--cpu-count number_of_vcpus
--cpu-ids list_of_vcpu_ids]
--memory amount_of_memory_in_MiB
--eif-path path_to_enclave_image_file
[--enclave-cid cid_number]
[--debug-mode]
[--attach-console]
```
Alternatively, pass the enclave settings using a JSON file as follows.
```
nitro-cli run-enclave --config config_file.json
```
The following is an example JSON file.
```
{
"enclave_name": enclave_name,
"cpu_count": number_of_vcpus,
"cpu_ids": list_of_vcpu_ids,
"memory_mib": amount_of_memory_in_MiB,
"eif_path": "path_to_enclave_image_file",
"enclave_cid": cid_number,
"debug_mode": true|false,
"attach_console": true|false
}
```
## Options
**`--enclave-name`**
A unique name for the enclave. You can use this name to reference the enclave when using the `nitro-cli console` and `nitro-cli terminate-enclave` commands.
If you do not specify a name, the name of the enclave image file (.eif) is used as the enclave name.
Type: String
Required: No
**`--cpu-count`**
The number of vCPUs to allocate to the enclave.
+ Amazon EC2 instances support multithreading, which enables multiple threads to run concurrently on a single CPU core. Each thread is represented as a virtual CPU (vCPU) on the instance. For more information about vCPUs, see [Optimize CPU options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) in the *Amazon EC2 User Guide*.
+ If the parent instance is enabled for multithreading, you must specify an even number of vCPUs.
The number of vCPUs that you can allocate to an enclave depends on the size and configuration of the parent instance. If the parent instance is enabled for multithreading, you must leave at least 2 vCPUs for the parent instance. If multithreading is not enabled, you must leave at least 1 vCPU for the parent instance. For example, if your parent instance has 4 vCPUs and it is enabled for multithreading, you can allocate up to 2 vCPUs to the enclave.
You must specify either `--cpu-count` or `--cpu-ids`. If you specify this option, omit `--cpu-ids`.
Type: Integer
Required: Conditional
**`--cpu-ids`**
The IDs of the vCPUs to allocate to the enclave.
+ Amazon EC2 instances support multithreading, which enables multiple threads to run concurrently on a single CPU core. Each thread is represented as a virtual CPU (vCPU) on the instance. For more information about vCPUs, see [Optimize CPU options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) in the *Amazon EC2 User Guide*.
+ If the parent instance is enabled for multithreading, you must specify an even number of vCPUs.
The number of vCPUs that you can allocate to an enclave depends on the size and configuration of the parent instance. If the parent instance is enabled for multithreading, you must leave at least 2 vCPUs for the parent instance. If multithreading is not enabled, you must leave at least 1 vCPU for the parent instance. For example, if your parent instance has 4 vCPUs and it is enabled for multithreading, you can allocate up to 2 vCPUs to the enclave.
You must specify either `--cpu-count` or `--cpu-ids`. If you specify this option, omit `--cpu-count`.
Type: String
Required: Conditional
**`--memory`**
The amount of memory (in MiB) to allocate to the enclave.
The amount of memory that you can allocate to an enclave depends on the size of the parent instance and the applications that you intend to run on it. The specified amount of memory cannot exceed the amount of memory provided by the parent instance. You must leave enough memory for the applications running on the parent instance. You must allocate a minimum of `64` MiB of memory to the enclave.
Type: Integer (MiB)
Required: Yes
**`--eif-path`**
The path to the enclave image file.
Type: String
Required: Yes
**`--enclave-cid`**
The context identifier (CID) for the enclave. The CID is the socket address used by the *vsock* socket. Only CIDs of `4` and higher can be specified. If you omit this option, a random CID is allocated to the enclave.
Type: Integer
Required: No
**`--debug-mode`**
Indicates whether to run the enclave in debug mode. Specify this option to enable debug mode, or omit it to disable debug mode.
If you enable debug mode, you can view the enclave's console in read-only mode using the `nitro-cli console` command. Enclaves booted in debug mode generate attestation documents with PCRs that are made up entirely of zeros.
Required: No
**`--attach-console`**
Attach the enclave console immediately after starting the enclave.
**`--config`**
The path to a .json configuration file that specifies the parameters for the enclave. If you specify `--config`, the specified JSON file must include the required and optional parameters as described above, and you must not specify any other parameters in the command itself.
Type: String
Required: No
## Output
**`EnclaveName`**
The unique name of the enclave.
Type: String
**`EnclaveID`**
The unique ID of the enclave.
Type: String
**`ProcessID`**
The process identifier (PID) of the process holding the enclave's resources.
Type: String
**`EnclaveCID`**
The context ID (CID) of the enclave.
Type: Integer
**`NumberOfCPUs`**
The number of vCPUs allocated to the enclave from the parent instance.
Type: Integer
**`CPUIDs`**
The IDs of the vCPUs allocated to the enclave from the parent instance.
Type: String
**`MemoryMiB`**
The amount of memory (in MiB) allocated to the enclave from the parent instance.
Type: Integer
## Examples
### Example 1: Inline parameters
The following example creates an enclave with `2` vCPUs, `1600` MiB of memory, and a context ID of `10`. It also uses an enclave image file named `sample.eif`, which is located in the same directory from which the command is being run.
**Command**
```
nitro-cli run-enclave --enclave-name my-enclave --cpu-count 2 --memory 1600 --eif-path sample.eif --enclave-cid 10
```
**Output**
```
Start allocating memory...
Started enclave with enclave-cid: 10, memory: 1600 MiB, cpu-ids: [1, 3]
{
"EnclaveName": "my_enclave",
"EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
"ProcessID": 12345,
"EnclaveCID": 10,
"NumberOfCPUs": 2,
"CPUIDs": [
1,
3
],
"MemoryMiB": 1600
}
```
### Example 2: Config file
The following example creates an enclave with `2` vCPUs, `1600` MiB of memory, and a context ID of `10`. It also uses an enclave image file named `sample.eif`, which is located in the same directory from which the command is being run.
**Command**
```
nitro-cli run-enclave --config enclave_config.json
```
The following is an example of the `enclave_config.json` file.
```
{
"enclave_name": "my_enclave",
"cpu_count": 2,
"memory_mib": 1600,
"eif_path": "sample.eif",
"enclave_cid": 10,
"debug_mode": true
}
```
**Output**
```
Start allocating memory...
Started enclave with enclave-cid: 10, memory: 1600 MiB, cpu-ids: [1, 3]
{
"EnclaveName": "my_enclave",
"EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
"ProcessID": 12345,
"EnclaveCID": 10,
"NumberOfCPUs": 2,
"CPUIDs": [
1,
3
],
"MemoryMiB": 1600
}
```
# nitro-cli describe-enclaves
Describes an enclave.
## Syntax
```
nitro-cli describe-enclaves
```
## Options
This command has no options.
## Output
**`EnclaveName`**
The unique name of the enclave.
Type: String
**`EnclaveID`**
The unique ID of the enclave.
Type: String
**`ProcessID`**
[Linux parent instances only] The process identifier (PID) of the process holding the enclave's resources.
Type: String
**`EnclaveCID`**
The unique context ID (CID) of the enclave. The CID is the socket address used by the *vsock* socket.
Type: Integer
**`NumberOfCPUs`**
The number of vCPUs allocated to the enclave from the parent instance.
Type: Integer
**`CPUIDs`**
[Linux parent instances only] The IDs of the vCPUs allocated to the enclave from the parent instance.
Type: Integer
**`MemoryMiB`**
The amount of memory (in MiB) allocated to the enclave from the parent instance.
Type: Integer
**`State`**
The current status of the enclave.
Possible values: `running` \$1 `terminating`
Type: String
**`Flags`**
Indicates if the enclave is in debug mode. `None` indicates that debug mode is disabled. `Debug` indicates that debug mode is enabled.
Possible values: `None` \$1 `Debug`
Type: String
## Example
The following example describes an enclave.
**Command**
```
nitro-cli describe-enclaves
```
**Output**
```
[
{
"EnclaveName": "my_enclave",
"EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
"ProcessID": 12345,
"EnclaveCID": 10,
"NumberOfCPUs": 2,
"CPUIDs": [
1,
3
],
"MemoryMiB": 1600,
"State": "RUNNING",
"Flags": "NONE"
}
]
```
# nitro-cli console
Enters a read-only console for the specified enclave. This enables you to view the enclave's console output to assist with troubleshooting. You can use this command only on an enclave that was launched with the `--debug-mode` option.
## Syntax
```
nitro-cli console
[--enclave-name enclave_name]
[--enclave-id enclave_id]
[--disconnect-timeout number_of_seconds]
```
## Options
**`--enclave-name`**
The unique name of the enclave. You must specify either `--enclave-name` or `--enclave-id`.
Type: String
Required: Conditional
**`--enclave-id`**
The unique ID of the enclave. You must specify either `--enclave-id` or `--enclave-name`.
Type: String
Required: Conditional
**`--disconnect-timeout`**
The number of seconds after which to automatically disconnect idle console sessions.
Type: Integer
Required: No
## Example
The following command enters a read-only console for an enclave with an ID of `i-05f6ed443ae428c95-enc173dfe3e2b1c87b`. The session automatically disconnects if the connection is idle for `60` seconds.
**Command**
```
nitro-cli console --enclave-id i-05f6ed443ae428c95-enc173dfe3e2b1c87b --disconnect-timeout 60
```
# nitro-cli describe-eif
Describes the specified enclave image file (`.eif`). The output is a static description of the enclave image file that includes the enclave image file version, build measurements, signing certificate information, the result of the CRC and signature check, and the metadata added at build time.
## Syntax
```
nitro-cli describe-eif
--eif-path path_to_enclave_image_file
```
## Options
**`--eif-path`**
The path to the enclave image file.
Type: String
Required: Yes
## Output
**`Measurements`**
The cryptographic measurements (SHA384 hashes) that are unique to the enclave image file.
Type: String
## Example
The following example describes an enclave image file named `sample.eif`.
**Command**
```
nitro-cli describe-eif --eif-path image.eif
```
**Output**
```
{
"Measurements": {
"HashAlgorithm": "Sha384 { ... }",
"PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
"PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
"PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE"
}
}
```
# nitro-cli sign-eif
Signs an existing enclave image file (`.eif`). You must specify a private key and a signing certificate. For the private key, you can use a KMS key ARN or a local private key file.
The signature is added to the enclave image file (`.eif`). The signature is updated if it already exists in the enclave image file.
The command returns a set of measurements (SHA384 hashes) that are unique to the enclave image file. These measurements are provided in the form of platform configuration registers (PCRs). The PCRs are used during the enclave's attestation process. For more information, see [Nitro Enclaves concepts](nitro-enclave-concepts.md).
For example, when using Nitro Enclaves with AWS Key Management Service (AWS KMS), you can specify these PCRs in condition keys for customer managed keys policies. When an application in the enclave performs an AWS KMS operation, AWS KMS compares the PCRs in the enclave's signed attestation document with the PCRs specified in the condition keys of the KMS key policy before allowing the operation.
## Syntax
```
nitro-cli sign-eif
--eif-path /path/to/eif
--private-key key
--signing-certificate certificate.pem
```
## Options
**`--eif-path`**
The path to the enclave image file.
Type: String
Required: Yes
**`--private-key`**
The private key to use to sign the enclave image file. This can be a KMS key ARN, or a path to a local private key file. Only ECDSA keys are supported for signing.
Type: String
Required: Yes
**`--signing-certificate`**
The signing key to use to sign the enclave image file.
Type: String
Required: Yes
**Important**
Ensure that the specified certificate is valid. If you start an enclave with an invalid certificate, then the `nitro-cli run-enclave` command fails with errors `E36`, `E39`, and `E11`. For more information, see [Nitro Enclaves CLI error codes](https://docs.aws.amazon.com/enclaves/latest/user/cli-errors.html).
## Output
**`Measurements`**
The cryptographic measurements (SHA384 hashes) that are unique to the enclave image file. The command output includes an additional PCR, `PCR8` that can be used in condition keys for KMS key policies. For more information, see [Where to get an enclave's measurements](https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html#where).
Type: String
## Example
The following example signs the enclave image file `sample.eif` with the given KMS key.
**Command**
```
nitro-cli sign-eif --eif-path sample.eif --private-key arn:aws:kms:eu-west-1:123456789321:key/abcdef12-3456-789a-bcde-111122223333 --signing-certificate certificate.pem
```
**Output**
```
Enclave Image successfully signed.{
"Measurements": {
"HashAlgorithm": "Sha384 { ... }",
"PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
"PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
"PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE",
"PCR8": "EXAMPLEdcca7f74398ae152d6ee245d8ac2cd430fb63644b46bf47b7d36b53b91c7597edda2d5df772cc81b72EXAMPLE"
}
}
```
# nitro-cli pcr
Returns the platform configuration register (PCR) value for a specified input file or PEM certificate. You can use this command to identify the files and signing certificate that were used to sign an enclave by comparing the command output with PCR values in the enclave's build measurements.
## Syntax
```
nitro-cli pcr
[--input path_to_file]
[--signing-certificate path_to_certificate]
```
## Options
**`--input`**
The path to the file for which to generate the platform configuration register (PCR) value.
You must specify either `--input` or `--signing-certificate`.
Type: String
Required: Conditional
**`--signing-certificate`**
The path to the PEM certificate for which to generate PCR8. This option is used to specifically request the PCR8 value by performing deserialisation of the certificate and PEM format validation.
You must specify either `--input` or `--signing-certificate`.
Type: String
Required: Conditional
## Output
**`PCR`**
The platform configuration register (PCR) value for the specified input file or PEM certificate.
Type: String
## Example
The following example generates the PCR8 value for a PEM certificate named `cert.pem`.
**Command**
```
nitro-cli pcr --signing-certificate cert.pem
```
**Output**
```
{
"PCR8": "example39de75e8ed2939e95examplea96f2c79eaf5d5ac3bacf2cb76c75a31f9examplef55b29f0acd256b8example"
}
```
# nitro-cli terminate-enclave
Terminates a specific enclave or all enclaves owned by the current user.
To terminate a specific enclave, specify `--enclave-name` or `--enclave-id`. To terminate all enclaves, specify `--all`.
## Syntax
```
nitro-cli terminate-enclave
[--enclave-id enclave_id]
[--enclave-name enclave_name]
[--all]
```
## Options
**`--enclave-name`**
The unique name of the enclave to terminate. You must specify either `--enclave-name` or `--enclave-id`.
Type: String
Required: Conditional
**`--enclave-id`**
The unique ID of the enclave to terminate. You must specify either `--enclave-id` or `--enclave-name`.
Type: String
Required: Conditional
**`--all`**
Indicates whether to terminate all of the enclaves owned by the current user. If you specify this option, omit `--enclave-id` and `--enclave-name`.
Required: No
## Example
### Example: Terminate specific enclave
The following example terminates an enclave with an ID of `i-abc12345def67890a-enc9876abcd543210ef12`.
**Command**
```
nitro-cli terminate-enclave --enclave-id i-abc12345def67890a-enc9876abcd543210ef12
```
**Output**
```
Successfully terminated enclave i-abc12345def67890a-enc9876abcd543210ef12.
{
"EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
"Terminated": true
}
```
### Example: Terminate all running enclaves
The following example terminates all of the enclaves owned by the current user.
**Command**
```
nitro-cli terminate-enclave --all
```
**Output**
```
Successfully terminated enclave i-abc12345def67890a-enc9876abcd543210ef12.
{
"EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
"Terminated": true
}
```
# Nitro Enclaves CLI error codes
This section lists the possible errors that the Nitro CLI can return.
**`E01`**
**Missing mandatory argument.** At least one mandatory argument has not been specified. Ensure that all mandatory arguments have been specified.
**`E02`**
**Conflicting arguments.** The command includes two or more incompatible arguments. Ensure that you specify only one of the conflicting arguments. For example, you cannot specify `--cpu-count` and `--cpu-ids` in the same `run-enclave` command.
**`E03`**
**Invalid argument provided.** A value of the incorrect type has been specified for one or more arguments. For example, a string was specified for an argument that expects an integer. Ensure that all values are of the expected type.
**`E04`**
**Socket pair creation failure.** The Nitro CLI attempted to open a stream pair with the enclave, but the stream initialization has failed. Either there is insufficient memory available for the Nitro CLI process, or the system-wide maximum number of open descriptors was reached. Retry the command. If that fails, reboot the instance and then retry the command.
**`E05`**
**Process spawn failure.** The Nitro CLI failed to spawn the enclave process while running the `run-enclave` command. Either the system has reached its maximum number of threads, or there is insufficient memory available to spawn the new process. Ensure that the system has enough free memory and then retry the command. If that fails, reboot the instance and then retry the command.
**`E06`**
**Daemonize process failure.** An error occurred while attempting to daemonize the newly spawned enclave process. Possible reasons are that the system has reached its maximum number of threads, there is insufficient memory available to spawn the new process, or the configuration of the Nitro CLI main process is not allowing the daemon creation process. Ensure that the system has enough free memory and then retry the command. If that fails, reboot the instance and then retry the command.
**`E07`**
**Read from disk failure.** The Nitro CLI failed to read content from the enclave's socket directory (typically `/var/run/nitro_enclaves/`) while running the `describe-enclave` command. Ensure that the directory exists and that it has the correct permissions. Alternatively, run the Nitro Enclaves configuration script to reconfigure the environment.
**`E08`**
**Unusable connection error.** The Nitro CLI is unable to connect to an enclave. Ensure that it exists and that it is in the `running` state.
**`E09`**
**Socket close error.** The Nitro CLI is unable to close the communication channel. The socket close operation was interrupted by another signal. Retry the command.
**`E10`**
**Socket connect set timeout error.** The Nitro CLI failed to configure a specific timeout for the specified socket. Ensure that the operation is being performed on a valid socket.
**`E11`**
**Socket error.** An unexpected error occurred with the socket.
**`E12`**
**Epoll error.** The Nitro CLI failed to register the enclave descriptor for event monitoring with `epoll`. Either the system has insufficient memory to handle the requested operation, or the per-user maximum number of watches was reached while trying to register a new descriptor on an epoll instance. Ensure that the system has enough free memory and then retry the command. If that fails, reboot the instance and then retry the command.
**`E13`**
**Inotify error.** The Nitro CLI failed to configure a socket for monitoring. Either the system has insufficient memory to handle the requested operation, or the user limit of inotify watches has been reached. Ensure that the system has enough free memory and then retry the command. If that fails, reboot the instance and then retry the command.
**`E14`**
**Invalid command.** An unknown command or command argument was specified. Verify the command and argument names.
**`E15`**
**Lock acquire failure.** The Nitro CLI failed to obtain a lock on an object with concurrent access, such as a structure containing information about a running enclave. A previous thread failed an operation while holding the lock. Retry the command. If that fails, reboot the instance and then retry the command.
**`E16`**
**Thread join failure.** The Nitro CLI failed to join a thread after it finished executing. Retry the command.
**`E17`**
**Serde error.** An error occurred while serializing or deserializing a command or command response. The JSON in the supplied command might not be valid. If you are supplying command arguments in the JSON file, ensure that the supplied JSON is valid.
**`E18`**
**File permissions error.** You do not have permission to modify the logging file (typically `/var/log/nitro_enclaves/nitro_enclaves.log`). Ensure that your user is part of the `ne` user group. For more information, see [Install the Nitro Enclaves CLI on Linux](nitro-enclave-cli-install.md).
**`E19`**
**File operation failure.** The system failed to perform the requested file operations. Ensure that the file on which the operation is performed exists and that you have permission to modify it.
**`E20`**
**Invalid CPU configuration.** The same CPU ID has been specified more than once for the `--cpu-ids` argument. Ensure that each vCPU ID is specified only once.
**`E21`**
**No such CPU available in the pool.** One or more of the specified CPU IDs does not exist in the CPU pool. Either retry the command and specify different vCPU IDs, or preallocate the environment resources so that the vCPU pool includes the vCPU IDs that you want to use. For more information, see [Install the Nitro Enclaves CLI on Linux](nitro-enclave-cli-install.md).
**`E22`**
**Insufficient CPUs available in the pool.** The number of requested vCPUs is greater than the number of available vCPUs. Either specify a number of vCPUs less than or equal to the configured vCPU pool size, or preallocate the environment resources so that the vCPU pool includes the number of vCPUs that you want to use. For more information, see [Install the Nitro Enclaves CLI on Linux](nitro-enclave-cli-install.md).
**`E23`**
**Malformed CPU ID error.** This error appears when a `lscpu` line is malformed and it reports an online CPUs list that is not valid. Ensure that the `lscpu` output is not corrupt.
**`E24`**
**CPU error.** A CPU line interval is not valid. Ensure that the `lscpu` output is not corrupt.
**`E25`**
**No such hugepage flag error.** The enclave process attempted to use a hugepage size that is not valid for initializing the enclave memory. Make sure that the Nitro CLI code has not been modified to include hugepage sizes that are not valid.
**`E26`**
**Insufficient memory requested.** Insufficient memory was requested for the enclave. The memory should be equal to or greater than the size of the enclave image file. Preallocate enough memory to ensure that the enclave image file fits in the enclave's memory. For more information, see [Install the Nitro Enclaves CLI on Linux](nitro-enclave-cli-install.md).
**`E27`**
**Insufficient memory available.** The amount of requested memory is greater than the amount of available memory. The enclave memory should not be greater than the size of the configured hugepage memory. For example, if you request 100 MiB of memory while the allocated hugepage memory is 80MiB, the request fails. Preallocate enough memory for the enclave. For more information, see [Install the Nitro Enclaves CLI on Linux](nitro-enclave-cli-install.md). Alternatively, specify a smaller amount of memory with the `run-enclave` command.
**`E28`**
**Invalid enclave descriptor.** `NE_CREATE_VM ioctl` returned an error. Review the error backtrace for more information.
**`E29`**
**Ioctl failure.** An unexpected `ioctl` error occurred. Review the error backtrace for more information.
**`E30`**
**Ioctl image get load info failure.** The `ioctl` used for getting the memory load information failed. Review the error backtrace for more information.
**`E31`**
**Ioctl set memory region failure.** The `ioctl` used for setting a given memory region has failed. Review the error backtrace for more information.
**`E32`**
**Ioctl add vCPU failure.** The `ioctl` used for adding a vCPU failed. Review the error backtrace for more information.
**``E33**
**Ioctl start enclave failure.** The `ioctl` used for starting an enclave has failed. Review the error backtrace for more information.
**`E34`**
**Memory overflow.** An error occurred while loading the enclave image file in memory regions that will be conceded to the future enclave. For example, this can occur if the regions offset plus the enclave image file size exceeds the maximum address of the target platform.
**`E35`**
**EIF file parsing error.** Failed to fill a memory region with a section of the enclave image file.
**`E36`**
**Enclave boot failure.** The enclave failed to return a `ready` signal after booting. For example, if booting from an enclave image file that is not valid, the enclave process exits immediately, before returning a ready signal. Ensure that the enclave image file is not corrupt. Review the error backtrace for more information.
**`E37`**
**Enclave event wait error.** Failed to monitor an enclave descriptor for events.
**`E38`**
**Enclave process command not executed error.** At least one enclave process failed to provide the description information.
**`E39`**
**Enclave process connection failure.** The enclave manager failed to connect to at least one enclave process for retrieving the description information.
**`E40`**
**Socket path not found.** The Nitro CLI failed to build the corresponding socket path starting from a given enclave ID.
**`E41`**
**Enclave process send reply failure.** The enclave process failed to report its status to the requesting command.
**`E42`**
**Enclave mmap error.** Failed to allocate memory to the enclave. Make sure that the system has enough free memory available. Retry the command. If that fails, reboot the instance and then retry the command.
**`E43`**
**Enclave munmap error.** Failed to unmap an enclave's memory. Make sure that the Nitro CLI code has not been modified to pass flags to the memory region unmapping operation that are not valid.
**`E44`**
**Enclave console connection failure.** The Nitro CLI failed to establish a connection with a running enclave's console. Make sure that the enclave has been started with the `--debug` flag.
**`E45`**
**Enclave console read error.** Failed to read from a running enclave's console. Retry the command.
**`E46`**
**Enclave console write output error.** Failed to write the information retrieved from a running enclave's console to a stream. Retry the command.
**`E47`**
Integer parsing error. Unable to connect to a running enclave's console because the CID could not be parsed. Use the `nitro-cli describe-enclaves` command to confirm the CID, and to ensure that it is a valid number.
**`E48`**
**EIF building error.** An error occurred while building the enclave image file. Review the error backtrace for more information.
**`E49`**
**Docker image build error.** An error occurred while building the enclave image file because the specified Docker image could not be built. Review the error backtrace for more information.
**`E50`**
**Docker image pull error.** An error occurred while building the enclave image file because the specified Docker image could not be pulled. Review the error backtrace for more information.
**`E51`**
**Artifacts path environment variable not set.** An error occurred while building the enclave image file because the artifacts path environment variable has not been set.
**`E52`**
**Blobs path environment variable not set.** An error occurred while building the enclave image file because the blobs path environment variable has not been set. Retry the command.
**`E53`**
**Clock skew error.** Failed to measure the elapsed time between consecutive reads from a running enclave's console. Retry the command.
**`E54`**
**Signal masking error.** Failed to mask specific signals after creating an enclave process. Retry the command.
**`E55`**
**Signal unmasking error.** Failed to unmask specific signals after creating an enclave process. Retry the command.
**`E56`**
**Logger error.** An error occurred while initializing the underlying logging system. Review the error backtrace for more information.
**`E57`**
**Hasher error.** An I/O error occurred while initializing a hasher or while writing bytes to the hasher.
**`E58`**
**Naming error.** The specified enclave name does not exist.
**`E59`**
**EIF signature checker error.** An error occurred while validating the signing certificate.