# Cryptographic attestation support in AWS KMS AWS KMS supports *cryptographic attestation* for [AWS Nitro Enclaves](https://docs.aws.amazon.com/enclaves/latest/user/) and [AWS NitroTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm-attestation.html). Applications that support these attestation methods call the following AWS KMS cryptographic operations with a signed attestation document. AWS KMS verifies that the attestation document came from a valid source (either a Nitro enclave or NitroTPM). Then, instead of returning plaintext data in the response, these APIs encrypt the plaintext with the public key from the attestation document and return ciphertext that can be decrypted only by the corresponding private key in the enclave or EC2 instance. + [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt) + [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret) + [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey) + [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair) + [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom) The following table shows how the response to attested requests differs from the standard response for each API operation. | AWS KMS operation | Standard response | Response for attested requests | | --- | --- | --- | | Decrypt | Returns plaintext data | Returns the plaintext data encrypted by the public key from the attestation document | | DeriveSharedSecret | Returns raw shared secret | Returns the raw shared secret encrypted by the public key from the attestation document | | GenerateDataKey | Returns a plaintext copy of the data key(Also returns a copy of the data key encrypted by a KMS key) | Returns a copy of the data key encrypted by the public key from the attestation document(Also returns a copy of the data key encrypted by a KMS key) | | GenerateDataKeyPair | Returns a plaintext copy of the private key(Also returns the public key and a copy of the private key encrypted by a KMS key) | Returns a copy of the private key encrypted by the public key from the attestation document(Also returns the public key and a copy of the private key encrypted by a KMS key) | | GenerateRandom | Returns a random byte string | Returns the random byte string encrypted by the public key from the attestation document | AWS KMS supports [policy condition keys](conditions-attestation.md) that you can use to allow or deny attested operations with an AWS KMS key based on the content of the attestation document. You can also [monitor attested requests to AWS KMS](ct-attestation.md) in your AWS CloudTrail logs. **Learn more** + [Cryptographic attestation](https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html) + [AWS KMS condition keys for attested platforms](conditions-attestation.md) + [How to make attested calls to AWS KMS](attested-calls.md) + [Monitoring attested requests](ct-attestation.md) # How to make attested calls to AWS KMS To make an attested call to AWS KMS, use the `Recipient` parameter in the request to provide the signed attestation document and the encryption algorithm to use with the public key in the attestation document. When a request includes the `Recipient` parameter with a signed attestation document, the response includes a `CiphertextForRecipient` field with the ciphertext encrypted by the public key. The plaintext field is null or empty. The `Recipient` parameter must specify a signed attestation document from an AWS Nitro Enclaves or AWS NitroTPM. AWS KMS relies on the digital signature for the attestation document to prove that the public key in the request came from a valid source. You cannot supply your own certificate to digitally sign the attestation document. The AWS Nitro Enclaves SDK, which is supported only within a Nitro enclave, automatically adds the `Recipient` parameter and its values to every AWS KMS request. To make attested requests in the AWS SDKs, you have to specify the `Recipient` parameter and its values. The attestation document can be retrieved from the NitroTPM using the [nitro-tpm-attest utility](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/attestation-get-doc.html) or from the Nitro Secure Module (NSM) using [the NSM API](https://github.com/aws/aws-nitro-enclaves-nsm-api). AWS KMS supports [policy condition keys](conditions-attestation.md) that you can use to allow or deny attested operations with an AWS KMS key based on the content of the attestation document. You can also [monitor attested requests to AWS KMS](ct-attestation.md) in your AWS CloudTrail logs. For detailed information about the `Recipient` parameter and the AWS `CiphertextForRecipient` response field, see the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt), [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair), and [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom) topics in the *AWS Key Management Service API Reference*, the [AWS Nitro Enclaves SDK](https://docs.aws.amazon.com/enclaves/latest/user/developing-applications.html#sdk), or any AWS SDK. For information about setting up your data and data keys for encryption, see [Using cryptographic attestation with AWS KMS](https://docs.aws.amazon.com/enclaves/latest/user/kms.html). # Monitoring attested requests You can use your AWS CloudTrail logs to monitor [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt), [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair), and [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom) operations that use attestation. In these log entries, the `additionalEventData` field has a `recipient` field with information from the attestation document in the request. These fields are included only when the `Recipient` parameter in the request specifies a signed attestation document. The specific information included in the CloudTrail log depends on the attestation method used. # Monitoring requests for Nitro enclaves For Nitro enclave attestation, the CloudTrail log includes the module ID (`attestationDocumentModuleId`), image digest (`attestationDocumentEnclaveImageDigest`), and platform configuration registers (PCRs) from the attestation document. The module ID is the [enclave ID](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave-concepts.html#term-enclaveid) of the Nitro enclave. The image digest is the SHA384 hash of the enclave image. You can use the image digest and PCR values in [conditions for key policies and IAM policies](conditions-attestation.md). For information about the PCRs, see [Where to get an enclave's measurements](https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html#where) in the *AWS Nitro Enclaves User Guide*. This section shows an example CloudTrail log entry for each of the supported Nitro enclave requests to AWS KMS. ## Decrypt (for an enclave) The following example shows an AWS CloudTrail log entry of a [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation for an AWS Nitro enclave. ``` { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2020-07-27T22:58:24Z", "eventSource": "kms.amazonaws.com", "eventName": "Decrypt", "awsRegion": "us-west-2", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": { "encryptionAlgorithm": "SYMMETRIC_DEFAULT", "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-enc123456789abcde12", "attestationDocumentEnclaveImageDigest": "", "attestationDocumentEnclavePCR1": "", "attestationDocumentEnclavePCR2": "", "attestationDocumentEnclavePCR3": "", "attestationDocumentEnclavePCR4": "", "attestationDocumentEnclavePCR8": "" } }, "requestID": "b4a65126-30d5-4b28-98b9-9153da559963", "eventID": "e5a2f202-ba1a-467c-b4ba-f729d45ae521", "readOnly": true, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` ## GenerateDataKey (for an enclave) The following example shows an AWS CloudTrail log entry of a [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation for an AWS Nitro enclave. ``` { "eventVersion": "1.02", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2014-11-04T00:52:40Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateDataKey", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": { "keyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "numberOfBytes": 32 }, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-enc123456789abcde12", "attestationDocumentEnclaveImageDigest": "", "attestationDocumentEnclavePCR1": "", "attestationDocumentEnclavePCR2": "", "attestationDocumentEnclavePCR3": "", "attestationDocumentEnclavePCR4": "", "attestationDocumentEnclavePCR8": "" } }, "requestID": "e0eb83e3-63bc-11e4-bc2b-4198b6150d5c", "eventID": "a9dea4f9-8395-46c0-942c-f509c02c2b71", "readOnly": true, "resources": [{ "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "accountId": "111122223333" }], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` ## GenerateDataKeyPair (for an enclave) The following example shows an AWS CloudTrail log entry of a [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html) operation for an AWS Nitro enclave. ``` { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2020-07-27T18:57:57Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateDataKeyPair", "awsRegion": "us-west-2", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": { "keyPairSpec": "RSA_3072", "encryptionContext": { "Project": "Alpha" }, "keyId": "1234abcd-12ab-34cd-56ef-1234567890ab" }, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-enc123456789abcde12", "attestationDocumentEnclaveImageDigest": "", "attestationDocumentEnclavePCR1": "", "attestationDocumentEnclavePCR2": "", "attestationDocumentEnclavePCR3": "", "attestationDocumentEnclavePCR4": "", "attestationDocumentEnclavePCR8": "" } }, "requestID": "52fb127b-0fe5-42bb-8e5e-f560febde6b0", "eventID": "9b6bd6d2-529d-4890-a949-593b13800ad7", "readOnly": true, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` ## GenerateRandom (for an enclave) The following example shows an AWS CloudTrail log entry of a [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) operation for an AWS Nitro enclave. ``` { "eventVersion": "1.02", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2014-11-04T00:52:37Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateRandom", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": null, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-enc123456789abcde12", "attestationDocumentEnclaveImageDigest": "", "attestationDocumentEnclavePCR1": "", "attestationDocumentEnclavePCR2": "", "attestationDocumentEnclavePCR3": "", "attestationDocumentEnclavePCR4": "", "attestationDocumentEnclavePCR8": "" } }, "requestID": "df1e3de6-63bc-11e4-bc2b-4198b6150d5c", "eventID": "239cb9f7-ae05-4c94-9221-6ea30eef0442", "readOnly": true, "resources": [], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` # Monitoring requests for NitroTPM For NitroTPM attestation, the CloudTrail log includes the module ID (`attestationDocumentModuleId`) and platform configuration registers (PCRs) from the attestation document. The module ID is the ID of the EC2 instance with NitroTPM with a TPM identifier. You can use the PCR values in [conditions for key policies and IAM policies](conditions-attestation.md). This section shows an example CloudTrail log entry for each of the supported NitroTPM requests to AWS KMS. ## Decrypt (for a NitroTPM) The following example shows an AWS CloudTrail log entry of a [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation for a NitroTPM. ``` { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2020-07-27T22:58:24Z", "eventSource": "kms.amazonaws.com", "eventName": "Decrypt", "awsRegion": "us-west-2", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": { "encryptionAlgorithm": "SYMMETRIC_DEFAULT", "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-tpm0000000000000000", "attestationDocumentNitroTPMPCR4": "", "attestationDocumentNitroTPMPCR7": "", "attestationDocumentNitroTPMPCR8": "", "attestationDocumentNitroTPMPCR9": "", "attestationDocumentNitroTPMPCR16": "", "attestationDocumentNitroTPMPCR23": "" } }, "requestID": "b4a65126-30d5-4b28-98b9-9153da559963", "eventID": "e5a2f202-ba1a-467c-b4ba-f729d45ae521", "readOnly": true, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` ## GenerateDataKey (for a NitroTPM) The following example shows an AWS CloudTrail log entry of a [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation for a NitroTPM. ``` { "eventVersion": "1.02", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2014-11-04T00:52:40Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateDataKey", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": { "keyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "numberOfBytes": 32 }, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-tpm0000000000000000", "attestationDocumentNitroTPMPCR4": "", "attestationDocumentNitroTPMPCR7": "", "attestationDocumentNitroTPMPCR8": "", "attestationDocumentNitroTPMPCR9": "", "attestationDocumentNitroTPMPCR16": "", "attestationDocumentNitroTPMPCR23": "" } }, "requestID": "e0eb83e3-63bc-11e4-bc2b-4198b6150d5c", "eventID": "a9dea4f9-8395-46c0-942c-f509c02c2b71", "readOnly": true, "resources": [{ "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "accountId": "111122223333" }], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` ## GenerateDataKeyPair (for a NitroTPM) The following example shows an AWS CloudTrail log entry of a [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html) operation for a NitroTPM. ``` { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2020-07-27T18:57:57Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateDataKeyPair", "awsRegion": "us-west-2", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": { "keyPairSpec": "RSA_3072", "encryptionContext": { "Project": "Alpha" }, "keyId": "1234abcd-12ab-34cd-56ef-1234567890ab" }, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-tpm0000000000000000", "attestationDocumentNitroTPMPCR4": "", "attestationDocumentNitroTPMPCR7": "", "attestationDocumentNitroTPMPCR8": "", "attestationDocumentNitroTPMPCR9": "", "attestationDocumentNitroTPMPCR16": "", "attestationDocumentNitroTPMPCR23": "" } }, "requestID": "52fb127b-0fe5-42bb-8e5e-f560febde6b0", "eventID": "9b6bd6d2-529d-4890-a949-593b13800ad7", "readOnly": true, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ``` ## GenerateRandom (for a NitroTPM) The following example shows an AWS CloudTrail log entry of a [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) operation for a NitroTPM. ``` { "eventVersion": "1.02", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::111122223333:user/Alice", "accountId": "111122223333", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2014-11-04T00:52:37Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateRandom", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "AWS Internal", "requestParameters": null, "responseElements": null, "additionalEventData": { "recipient": { "attestationDocumentModuleId": "i-123456789abcde123-tpm0000000000000000", "attestationDocumentNitroTPMPCR4": "", "attestationDocumentNitroTPMPCR7": "", "attestationDocumentNitroTPMPCR8": "", "attestationDocumentNitroTPMPCR9": "", "attestationDocumentNitroTPMPCR16": "", "attestationDocumentNitroTPMPCR23": "" } }, "requestID": "df1e3de6-63bc-11e4-bc2b-4198b6150d5c", "eventID": "239cb9f7-ae05-4c94-9221-6ea30eef0442", "readOnly": true, "resources": [], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" } ```