Getting started with the Hello Enclaves sample application
The following tutorial walks you through the basics of using AWS Nitro Enclaves. It shows you how to launch an enclave-enabled parent instance, how to build an enclave image file, how to validate that an enclave is running, and how to terminate an enclave when it is no longer needed.
The tutorial uses the Hello Enclaves sample application.
Important
The steps for Windows and Linux parent instances are mostly similar. However, the
nitro-cli build-enclave
command referenced in Step 2: Build
the enclave image file is not supported on Windows instances. If you are using a
Windows instance, you must complete this step on a Linux instance and then transfer the enclave
image file (.eif
) to your Windows parent instance before continuing with the
remainder of the tutorial.
Steps
Step 1: Prepare the enclave-enabled parent instance
Launch the parent instance that you will use to create the enclave, and prepare the instance to run Nitro Enclaves.
To prepare the parent instance
-
Launch the instance using the run-instances command and set the
--enclave-options
parameter totrue
. At a minimum, you must also specify a Windows or Linux AMI and a supported instance type. For more information, see Requirements.The following example command launches an
m5.xlarge
instance using the Amazon Linux 2 Kernel 5.10 AMI.$
aws ec2 run-instances \ --image-id
ami-0b5eea76982371e91
\ --count 1 \ --instance-typem5.xlarge
\ --key-nameyour_key_pair
\ --enclave-options 'Enabled=true' -
Connect to the parent instance. For more information about connecting to an instance, see the following topics in the Amazon EC2 User Guide.
-
Install the AWS Nitro Enclaves CLI on the parent instance.
-
If you are using a Linux parent instance, you must preallocate the memory and vCPUs. For the purposes of this tutorial, you must preallocate at least 2 vCPUs and 512 MiB of memory. For more information, see Install the Nitro Enclaves CLI on Linux.
-
If you are using a Windows parent instance, see Install the Nitro Enclaves CLI on Windows.
-
Step 2: Build the enclave image file
Important
Only Linux-based operating systems can run inside an enclave. Therefore, you must use a Linux instance to
build your enclave image file .eif
. As a result of this, the nitro-cli build-enclave
command referenced in this section is not supported on Windows instances. If you are using a Windows parent
instance, you must complete this step on a Linux instance and then transfer the resulting enclave image file
(.eif
) to your Windows parent instance.
In this case, you must launch a temporary Linux instance and install the AWS Nitro Enclaves CLI on that instance. For more information, see Install the Nitro Enclaves CLI on Linux.
After you have launched the temporary Linux instance and you have installed the AWS Nitro Enclaves CLI,
connect to that instance and perform the steps described here. After you have completed the steps, transfer
the enclave image file (.eif
) to your Windows parent instance, reconnect to your Windows
parent instance and continue with Step 3: Run the enclave.
The Hello Enclave application is located in the /usr/share/nitro_enclaves/examples/hello
directory.
To build the enclave image file
-
Build a docker image from the application. The following command builds a Docker image named
hello
with a tag oflatest
.$
docker build /usr/share/nitro_enclaves/examples/hello -t hello
-
Run the following command to verify that the Docker image has been built.
$
docker image ls
-
Convert the Docker image to an enclave image file by using the nitro-cli build-enclave command. The following command builds an enclave image file named
hello.eif
.$
nitro-cli build-enclave --docker-uri hello:latest --output-file hello.eif
Example output
Start building the Enclave Image... Enclave Image successfully created. "Measurements": { "HashAlgorithm": "Sha384 { ... }", "PCR0": "2bb885ee2104203393c0d2f335f14061a9cd9154e4ede772a6a474d3679348fb33c4917d54fee3f11f9e7a49a0ef305c", "PCR1": "aca6e62ffbf5f7deccac452d7f8cee1b94048faf62afc16c8ab68c9fed8c38010c73a669f9a36e596032f0b973d21895", "PCR2": "40686da348b450210dcdd234fbb95826ecf81f67e4496b6182ba8eb7ab018977dce07448cd0b7ef44346dc1e283e3e64" } }
The
hello.eif
enclave image file has now been built. Note that the command output includes a set of hashes—PCR0
,PCR1
, andPCR2
. These hashes are measurements of the enclave image and boot up process, and they can be used in the attestation process. The attestation process will not be used in this tutorial.
Step 3: Run the enclave
You can now use the hello.eif
enclave image file to run the enclave. In this tutorial,
you will run an enclave with 2 vCPUs and 512 MiB of memory using the hello.eif
enclave
image file. You will also create the enclave in debug mode.
Note
Enclaves booted in debug mode generate attestation documents with PCRs that are made up entirely
of zeros (000000000000000000000000000000000000000000000000
). These attestation
documents cannot be used for cryptographic attestation.
Use the nitro-cli run-enclave
command. Specify the vCPUs, memory, and the path to the enclave image file, and include
the --debug-mode
option.
$
nitro-cli run-enclave --cpu-count 2 --memory 512 --enclave-cid 16 --eif-path hello.eif --debug-mode
Example output
Start allocating memory...
Started enclave with enclave-cid: 16, memory: 512 MiB, cpu-ids: [1, 3]
{
"EnclaveID": "i-05f6ed443aEXAMPLE-enc173dfe3eEXAMPLE",
"ProcessID": 7077,
"EnclaveCID": 16,
"NumberOfCPUs": 2,
"CPUIDs": [
1,
3
],
"MemoryMiB": 512
}
The enclave is now running. In this sample output, the enclave is created with an ID of
i-05f6ed443aEXAMPLE-enc173dfe3eEXAMPLE
, and an enclave context identifier
(EnclaveCID) of 16
. The EnclaveCID is like an IP address for the local socket (vsock)
between the parent instance and the enclave.
Step 4: Validate the enclave
Now that you have created the enclave, you can use the nitro-cli describe-enclaves command to verify that it is running.
$
nitro-cli describe-enclaves
{
"EnclaveID": "i-05f6ed443aEXAMPLE-enc173dfe3eEXAMPLE",
"ProcessID": 7077,
"EnclaveCID": 16,
"NumberOfCPUs": 2,
"CPUIDs": [
1,
3
],
"MemoryMiB": 512,
"State": "RUNNING",
"Flags": "DEBUG_MODE"
}
The command provides information about the enclave, including the enclave ID, number of
vCPUs, amount of memory, and its state. In this case, the enclave is in the
RUNNING
state.
Additionally, because you created the enclave in debug mode, you can use the nitro-cli console command to view the read-only console output of the enclave.
$
nitro-cli console --enclave-id
i-05f6ed443aEXAMPLE-enc173dfe3eEXAMPLE
Example output
Hello from the enclave side!
Hello from the enclave side!
Hello from the enclave side!
In this case, the Hello Enclave application is designed to print Hello from the enclave side!
to
the console every five seconds.
Step 5: Terminate the enclave
If you no longer need the enclave, you can use the nitro-cli terminate-enclave
command to terminate it.
$
nitro-cli terminate-enclave --enclave-id
i-05f6ed443aEXAMPLE-enc173dfe3eEXAMPLE
Example output
Successfully terminated enclave i-05f6ed443aEXAMPLE-enc173dfe3eEXAMPLE.
{
"EnclaveID": "i-05f6ed443aEXAMPLE-enc173dfe3eEXAMPLE",
"Terminated": true
}