# Cryptographic attestation Attestation is a unique feature available to Nitro Enclaves. The enclave uses the attestation process to prove its identity and build trust with an external service. The attestation process uses a series of measurements that are unique to an enclave. You can use these measurements to create access policies in external services to grant the enclave access to special cryptographic operations. For more information, see [Where to get an enclave's measurements](#where). Using the Nitro Enclaves SDK, an enclave can request a signed attestation document from the Nitro Hypervisor that includes its unique measurements. This document can be attached to requests from the enclave to an external service. The external service can validate the measurements included in the attestation document against the values in the access policy to determine whether to grant the enclave access to the requested operation. For more information, see [How to get an enclave's attestation document](#attestation-doc). **Topics** + [ ## Integration with AWS KMS ](#kms-integration) + [ ## Where to get an enclave's measurements ](#where) + [ ## How to get an enclave's attestation document ](#attestation-doc) + [ # Using cryptographic attestation with AWS KMS ](kms.md) + [Getting started with cryptographic attestation](hello-kms.md) ## Integration with AWS KMS Nitro Enclaves includes built-in support for attestation with AWS KMS. AWS KMS has the ability to ingest attestation documents that are presented by an enclave. Using the AWS KMS APIs included in the Nitro Enclaves SDK, you can perform AWS KMS actions, such as **Decrypt**, **GenerateDataKey**, and **GenerateRandom** from within the enclave. For more information about using the KMS APIs with Nitro Enclaves, see the [Nitro Enclaves SDK GitHub repo](https://github.com/aws/aws-nitro-enclaves-sdk-c/tree/main/docs/kms-apis) and the [ How Nitro Enclaves uses AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-nitro-enclaves.html) in the *AWS Key Management Service Developer Guide*. For more information about how to use attestation with AWS KMS, see [Using cryptographic attestation with AWS KMS](kms.md). If you are using a third-party external service, you must implement your own access policies and mechanisms for attestation using the attestation document and the enclave's measurements. ## Where to get an enclave's measurements An enclave's measurements includes a series of hashes and platform configuration registers (PCRs) that are unique to the enclave. An enclave has six measurements: | PCR | Hash of ... | Description | | --- | --- | --- | | PCR0 | Enclave image file | A contiguous measure of the contents of the image file, without the section data. | | PCR1 | Linux kernel and bootstrap | A contiguous measurement of the kernel and boot ramfs data. | | PCR2 | Application | A contiguous, in-order measurement of the user applications, without the boot ramfs. | | PCR3 | IAM role assigned to the parent instance | A contiguous measurement of the IAM role assigned to the parent instance. Ensures that the attestation process succeeds only when the parent instance has the correct IAM role. | | PCR4 | Instance ID of the parent instance | A contiguous measurement of the ID of the parent instance. Ensures that the attestation process succeeds only when the parent instance has a specific instance ID. | | PCR8 | Enclave image file signing certificate | A measure of the signing certificate specified for the enclave image file. Ensures that the attestation process succeeds only when the enclave was booted from an enclave image file signed by a specific certificate. | Some of the measures are exposed when the enclave image file is built, while others need to be manually generated based on information about the parent instance. Enclaves launched using the `--debug-mode` or `--attach-console` options generate attestation documents with PCR values made up entirely of zeroes. **Topics** + [ ### PCR0, PCR1, and PCR2 ](#pcr012) + [ ### PCR3 ](#pcr3) + [ ### PCR4 ](#pcr4) + [ ### PCR8 ](#pcr8) ### PCR0, PCR1, and PCR2 PCR0, PCR1, and PCR2 are exposed when the enclave image file (`.eif`) is built. In other words, they are provided as part of the output of the [nitro-cli build-enclave](cmd-nitro-build-enclave.md) command. For example, when building the enclave image file for the `hello-world` sample application, the output includes the following. ``` Enclave Image successfully created. { "Measurements": { "HashAlgorithm": "Sha384 { ... }", "PCR0": "7fb5c55bc2ecbb68ed99a13d7122abfc0666b926a79d5379bc58b9445c84217f59cfdd36c08b2c79552928702efe23e4", "PCR1": "235c9e6050abf6b993c915505f3220e2d82b51aff830ad14cbecc2eec1bf0b4ae749d311c663f464cde9f718acca5286", "PCR2": "0f0ac32c300289e872e6ac4d19b0b5ac4a9b020c98295643ff3978610750ce6a86f7edff24e3c0a4a445f2ff8a9ea79d" } } ``` ### PCR3 To further strengthen the security posture of the enclave, you can create and attach an instance profile to the parent instance. After you create the instance profile and associate an IAM role with it, you can generate a SHA384 hash based on the Amazon resource name (ARN) of the IAM role that's associated with the instance profile. You can then use the hash as PCR3 in the condition keys for your AWS KMS key policies. Doing this ensures that only enclaves running on an instance that has the correct IAM role can perform specific AWS KMS actions against a KMS key. For more information, see [Using instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) in the *IAM User Guide*. You can generate the hash using any tool that is capable of converting a string to a SHA384 hash. For example, the following command generates a SHA384 hash for an IAM role with an ARN of `arn:aws:iam::123456789012:role/Webserver`. **Note** In this example, the hash is padded with 48 `null` (`\0`) characters. ``` $ ROLEARN="arn:aws:iam::123456789012:role/Webserver"; \ python -c"import hashlib, sys; \ h=hashlib.sha384(); h.update(b'\0'*48); \ h.update(\"$ROLEARN\".encode('utf-8')); \ print(h.hexdigest())" ``` Example output ``` $ 78fce75db17cd4e0a3fb8dad3ad128ca5e77edbb2b2c7f75329dccd99aa5f6ef4fc1f1a452e315b9e98f9e312e6921e6 ``` ### PCR4 PCR4 is based on a SHA384 of the instance ID of the parent instance. Therefore, you can generate the PCR after you have launched the parent instance. You can generate this hash using any tool that is capable of converting a string to a SHA384 hash. For example, the following command generates a SHA384 hash for a parent instance with an instance ID of `i-1234567890abcdef0`. **Note** In this example, the hash is padded with 48 `null` (`\0`) characters. ``` $ INSTANCE_ID="i-1234567890abcdef0"; \ python -c"import hashlib, sys; \ h=hashlib.sha384(); h.update(b'\0'*48); \ h.update(\"$INSTANCE_ID\".encode('utf-8')); \ print(h.hexdigest())" ``` Example output ``` $ 08f996b5d43e047a9eb51e7f548bfee7e164fd7dc8f65541f2ac09d6545ac812719327281c401a67a10fcba87ae79ce0 ``` ### PCR8 You can also sign the enclave image file using your signing certificate and your private key. PCR8 is exposed only when building a signed enclave image file (`.eif`) . In other words it is provided as part of the output of the [nitro-cli build-enclave](cmd-nitro-build-enclave.md) command when the `--private-key` and `--signing-certificate` options are specified. Doing this creates a signed enclave image file. Using PCR8 ensures that only enclaves booted from an enclave image file signed by a specific certificate can perform specific AWS KMS actions against a KMS key. It also enables you to build more flexible condition keys that remain effective even if the enclave image or parent instance is changed. We recommend that you use PCR3 and PCR8 together for the best flexibility. You can use OpenSSL to generate a private key and signing certificate that can be used to sign an enclave image file. **To generate a private key and signing certificate** 1. Generate the private key. ``` $ openssl ecparam -name secp384r1 -genkey -out key_name.pem ``` This command generates the private key needed for the `--private-key` option. 1. Generate a certificate signing request (CSR). You can customize the request information if needed. ``` $ openssl req -new -key key_name.pem -sha384 -nodes -subj "/CN=AWS/C=US/ST=WA/L=Seattle/O=Amazon/OU=AWS" -out csr.pem ``` 1. Generate a certificate based on the CSR. Specify the CSR, the private key, a name for the certificate, and the number of days for which the certificate is to remain valid. **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`. ``` $ openssl x509 -req -days 20 -in csr.pem -out certificate.pem -sha384 -signkey key_name.pem ``` This command generates the signing certificate needed for the `--signing-certificate` option. For example, when building the enclave image file for the `hello-world` sample application and specifying a private key and signing certificate, the output includes the following. ``` $ nitro-cli build-enclave --docker-uri hello-world:latest --output-file hello-signed.eif --private-key key_name.pem --signing-certificate certificate.pem ``` ``` Enclave Image successfully created. { "Measurements": { "HashAlgorithm": "Sha384 { ... }", "PCR0": "7fb5c55bc2ecbb68ed99a13d7122abfc0666b926a79d5379bc58b9445c84217f59cfdd36c08b2c79552928702efe23e4", "PCR1": "235c9e6050abf6b993c915505f3220e2d82b51aff830ad14cbecc2eec1bf0b4ae749d311c663f464cde9f718acca5286", "PCR2": "0f0ac32c300289e872e6ac4d19b0b5ac4a9b020c98295643ff3978610750ce6a86f7edff24e3c0a4a445f2ff8a9ea79d", "PCR8": "70da58334a884328944cd806127c7784677ab60a154249fd21546a217299ccfa1ebfe4fa96a163bf41d3bcfaebe68f6f" } } ``` ## How to get an enclave's attestation document An enclave's attestation document is generated by the Nitro Hypervisor. You can request an enclave's attestation document from inside the enclave only, using the `get-attestation-document` API, which is included in the Nitro Enclaves SDK. For more information, see [AWS Nitro Enclaves SDK Github repository](https://github.com/aws/aws-nitro-enclaves-sdk-c). **Important** Enclaves booted in debug mode generate attestation documents with PCRs that are made up entirely of zeros. These attestation documents can't be used for cryptographic attestation. # Using cryptographic attestation with AWS KMS This section explains how to set up attestation to work with AWS Key Management Service. AWS KMS integrates with Nitro Enclaves to provide built-in attestation support. ## Secret data preparation Before using Nitro Enclaves with AWS KMS, it is important that you encrypt your sensitive data before sending it to the parent instance or the enclave. This section provides an overview of the steps needed to prepare your sensitive data for processing inside the enclave. 1. Create a AWS KMS key. For more information, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) in the *AWS Key Management Service Developer Guide*. 1. Generate a plaintext and encrypted data key using the KMS key. For more information, see [ generate-data-key](https://docs.aws.amazon.com/cli/latest/reference/kms/generate-data-key.html) in the *AWS KMS AWS CLI Command Reference*. 1. Encrypt the secret data under the KMS key using the plaintext data key and a client-side cryptographic library, such as the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html). For more information, see [Encrypt data with a data key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys-encrypt) in the *AWS Key Management Service Developer Guide*. You must modify the KMS key policy to grant the IAM principal that you’re using in your client permission to call the GenerateDataKey API action. 1. Upload the encrypted secret data and the encrypted data key to a storage location, such as Amazon S3. If you’re using the AWS Encryption SDK, the encrypted data key is automatically included in the header of the encrypted message. ## KMS key preparation After you have created your KMS key and you have encrypted your sensitive data under it, you need to ensure that only the enclave can access it to decrypt the encrypted data. AWS KMS enables you to create KMS key policies with condition keys that are based on an enclave's measurements. For more information about using condition keys in KMS key policies, see [AWS KMS condition keys for AWS Nitro Enclaves](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-nitro-enclaves) in the *AWS Key Management Service Developer Guide*. The Nitro Enclaves SDK includes some APIs (`kms-decrypt`, `kms-generate-data-key`, and `kms-generate-random`) that integrate with AWS KMS. When these APIs are called against a specific key, the enclave's attestation document, which includes its measurements, is attached to the request. AWS KMS receives the request and validates the measurements in the provided attestation document against the measurements specified in the condition keys of the KMS key policy. It uses this information to determine whether the enclave should be granted permission to perform the requested action using the requested KMS key. To prepare AWS KMS for attestation you must have the enclave's measurements. When you have the measurements, you can create a KMS key policy that includes condition keys that are based on those measurements. AWS KMS provides `kms:RecipientAttestation:ImageSha384` and `kms:RecipientAttestation:PCR` condition keys that enable you to create attestation-based condition keys for KMS key policies. These policies ensure that AWS KMS only allows operations using the KMS key if the enclave provides a signed attestation document that contains measurements that match the measurements specified in the KMS key policy's condition keys. For more information about the condition keys, see [ kms:RecipientAttestation:ImageSha384](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-recipient-image-sha) and [kms:RecipientAttestation:PCR](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-recipient-pcrs) in the *AWS Key Management Service Developer Guide*. For example, the following KMS key policy allows enclaves running on instances that have the `data-processing` instance profile to use the KMS key for the `Decrypt`, `GenerateDataKey`, and `GenerateRandom` actions. The condition key allows the operation only when measurements in the attestation document in the request matches the measurements in the condition. If the request doesn't include an attestation document, the role doesn't have permission to call the operation because this condition cannot be satisfied. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Sid" : "Enable enclave data processing", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::123456789012:role/data-processing" }, "Action": [ "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateRandom" ], "Resource": "*", "Condition": { "StringEqualsIgnoreCase": { "kms:RecipientAttestation:ImageSha384":"EXAMPLE8abcdef7abcdef6abcdef5abcdef4abcdef3abcdef2abcdef1abcdef1abcdef0abcdef1abcdEXAMPLE", "kms:RecipientAttestation:PCR0":"EXAMPLE8abcdef7abcdef6abcdef5abcdef4abcdef3abcdef2abcdef1abcdef1abcdef0abcdef1abcdEXAMPLE", "kms:RecipientAttestation:PCR1":"EXAMPLE050abf6b993c915505f3220e2d82b51aff830ad14cbecc2eec1bf0b4ae749d311c663f464cde9f718aEXAMPLE", "kms:RecipientAttestation:PCR2":"EXAMPLEc300289e872e6ac4d19b0b5ac4a9b020c98295643ff3978610750ce6a86f7edff24e3c0a4a445f2ff8EXAMPLE", "kms:RecipientAttestation:PCR3":"EXAMPLE11de9baee597508183477f097ae385d4a2c885aa655432365b53b812694e230bbe8e1bb1b8de748fe1EXAMPLE", "kms:RecipientAttestation:PCR4":"EXAMPLE6b9b3d89a53b13f5dfd14a1049ec0b80a9ae4b159adde479e9f7f512f33e835a0b9023ca51ada02160EXAMPLE", "kms:RecipientAttestation:PCR8":"EXAMPLE34a884328944cd806127c7784677ab60a154249fd21546a217299ccfa1ebfe4fa96a163bf41d3bcfaeEXAMPLE" } } }] } ``` ------ # Getting started with cryptographic attestation using the KMS Tool sample application Getting started with cryptographic attestation The AWS Nitro Enclaves SDK ships with a sample application, called **KMS Tool**, that demonstrates the cryptographic attestation process. The KMS Tool sample application is supported on both Windows and Linux parent instances. KMS Tool includes two applications: + **kmstool-instance**—An application that runs on the parent instance. It connects to *kmstool-enclave* (over the vsock socket), passes credentials to the enclave, along with a base64-encoded message for decryption. + **kmstool-enclave**—An application that runs in an enclave. It uses the Nitro Enclaves SDK to call AWS KMS in order to decrypt the base64-encoded message received from the application running on the parent instance. For instructions on how to set up and use the KMS Tool sample application, see the tutorial in the [AWS Nitro Enclaves SDK Github repository](https://github.com/aws/aws-nitro-enclaves-sdk-c/blob/main/docs/kmstool.md). This tutorial shows you how to: + Launch an enclave-enabled parent instance. + Build a Docker image from a Docker file. + Convert a Docker image to an enclave image file. + Create an AWS KMS key. + Add attestation-based condition keys to a KMS key policy. + Create an enclave using an enclave image file. **Tip** The tutorial also discusses some best practices for preparing your enclave and KMS key for attestation. You can use this sample application as a reference for building your own enclave applications and for preparing your enclave and KMS keys for attestation.