How Amazon Nitro Enclaves uses Amazon KMS - Amazon Key Management Service
How to call Amazon KMS APIs for a Nitro enclaveAmazon KMS condition keys for Amazon Nitro EnclavesMonitoring requests for Nitro enclaves
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

How Amazon Nitro Enclaves uses Amazon KMS

Amazon KMS supports cryptographic attestation for Amazon Nitro Enclaves. Applications that support Amazon Nitro Enclaves call the following Amazon KMS cryptographic operations with a signed attestation document for the enclave. These Amazon KMS APIs verify that the attestation document came from a Nitro enclave. 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.

The following table shows how the response to Nitro enclave requests differs from the standard response for each API operation.

Amazon KMS operation Standard response Response for Amazon Nitro Enclaves
Decrypt Returns plaintext data Returns the plaintext data 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

Amazon KMS supports policy condition keys that you can use to allow or deny enclave operations with an Amazon KMS key based on the content of the attestation document. You can also monitor requests to Amazon KMS for your Nitro enclave in your Amazon CloudTrail logs.

How to call Amazon KMS APIs for a Nitro enclave

To call Amazon KMS APIs for a Nitro enclave, use the Recipient parameter in the request to provide the signed attestation document for the enclave and the encryption algorithm to use with the enclave's public key. 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 Amazon Nitro enclave. Amazon KMS relies on the digital signature for the enclave’s attestation document to prove that the public key in the request came from a valid enclave. You cannot supply your own certificate to digitally sign the attestation document.

To specify the Recipient parameter, use the Amazon Nitro Enclaves SDK or any Amazon SDK. The Amazon Nitro Enclaves SDK, which is supported only within a Nitro enclave, automatically adds the Recipient parameter and its values to every Amazon KMS request. To make requests for Nitro enclaves in the Amazon SDKs, you have to specify the Recipient parameter and its values. Support for Nitro enclave cryptographic attestation in the Amazon SDKs was introduced in March 2023.

Amazon KMS supports policy condition keys that you can use to allow or deny enclave operations with an Amazon KMS key based on the content of the attestation document. You can also monitor requests to Amazon KMS for your Nitro enclave in your Amazon CloudTrail logs.

For detailed information about the Recipient parameter and the AWS CiphertextForRecipient response field, see the Decrypt, GenerateDataKey, GenerateDataKeyPair, and GenerateRandom topics in the Amazon Key Management Service API Reference, the Amazon Nitro Enclaves SDK, or any Amazon SDK. For information about setting up your data and data keys for encryption, see Using cryptographic attestation with Amazon KMS.

Amazon KMS condition keys for Amazon Nitro Enclaves

You can specify condition keys in the key policies and IAM policies that control access to your Amazon KMS resources. Policy statements that includes a condition key are effective only when its conditions are satisfied.

Amazon KMS provides condition keys that limit the permissions for the Decrypt, GenerateDataKey, GenerateDataKeyPair, and GenerateRandom operations based on the contents of the signed attestation document in the request. These condition keys that work only when a request for an Amazon KMS operation includes the Recipient parameter with a valid attestation document from an Amazon Nitro enclave. To specify the Recipient parameter, use the Amazon Nitro Enclaves SDK or any Amazon SDK.

The enclave-specific Amazon KMS condition keys are valid in key policy statements and IAM policy statements even though they do not appear in the IAM console or the IAM Service Authorization Reference.

kms:RecipientAttestation:ImageSha384

Amazon KMS Condition Keys Condition Type Value type API Operations Policy Type

kms:RecipientAttestation:ImageSha384

String

 Single-valued

Decrypt

GenerateDataKey

GenerateDataKeyPair

GenerateRandom

Key policies and IAM policies

The kms:RecipientAttestation:ImageSha384 condition key controls access to Decrypt, GenerateDataKey, GenerateDataKeyPair, and GenerateRandom with a KMS key when the image digest from the signed attestation document in the request matches the value in the condition key. The ImageSha384 value corresponds to PCR0 in the attestation document. This condition key is effective only when the Recipient parameter in the request specifies a signed attestation document for an Amazon Nitro enclave.

This value is also included in CloudTrail events for requests to Amazon KMS for Nitro enclaves.

Note

This condition key is valid in key policy statements and IAM policy statements even though it does not appear in the IAM console or the IAM Service Authorization Reference.

For example, the following key policy statement allows the data-processing role to use the KMS key for Decrypt, GenerateDataKey, GenerateDataKeyPair, and GenerateRandom operations. The kms:RecipientAttestation:ImageSha384 condition key allows the operations only when the image digest value (PCR0) of the attestation document in the request matches the image digest value in the condition. This condition key is effective only when the Recipient parameter in the request specifies a signed attestation document for an Amazon Nitro enclave.

If the request does not include a valid attestation document from an Amazon Nitro enclave, permission is denied because this condition is not satisfied.

{
  "Sid" : "Enable enclave data processing",
  "Effect" : "Allow",
  "Principal" : {
    "AWS" : "arn:aws:iam::111122223333:role/data-processing"
  },
  "Action": [
    "kms:Decrypt",
    "kms:GenerateDataKey",
    "kms:GenerateDataKeyPair",
    "kms:GenerateRandom"
  ],
  "Resource" : "*",
  "Condition": {
    "StringEqualsIgnoreCase": {
      "kms:RecipientAttestation:ImageSha384": "9fedcba8abcdef7abcdef6abcdef5abcdef4abcdef3abcdef2abcdef1abcdef1abcdef0abcdef1abcdef2abcdef3abcdef4abcdef5abcdef6abcdef7abcdef99"
    }
  }
}

kms:RecipientAttestation:PCR<PCR_ID>

Amazon KMS Condition Keys Condition Type Value type API Operations Policy Type

kms:RecipientAttestation:PCR<PCR_ID>

String

 Single-valued

Decrypt

GenerateDataKey

GenerateDataKeyPair

GenerateRandom

Key policies and IAM policies

The kms:RecipientAttestation:PCR<PCR_ID> condition key controls access to Decrypt, GenerateDataKey, GenerateDataKeyPair, and GenerateRandom with a KMS key only when the platform configuration registers (PCRs) from the signed attestation document in the request match the PCRs in the condition key. This condition key is effective only when the Recipient parameter in the request specifies a signed attestation document from an Amazon Nitro enclave.

This value is also included in CloudTrail events that represent requests to Amazon KMS for Nitro enclaves.

Note

This condition key is valid in key policy statements and IAM policy statements even though it does not appear in the IAM console or the IAM Service Authorization Reference.

To specify a PCR value, use the following format. Concatenate the PCR ID to the condition key name. The PCR value must be a lower-case hexadecimal string of up to 96 bytes.

"kms:RecipientAttestation:PCRPCR_ID": "PCR_value"

For example, the following condition key specifies a particular value for PCR1, which corresponds to the hash of the kernel used for the enclave and the bootstrap process.

kms:RecipientAttestation:PCR1: "0x1abcdef2abcdef3abcdef4abcdef5abcdef6abcdef7abcdef8abcdef9abcdef8abcdef7abcdef6abcdef5abcdef4abcdef3abcdef2abcdef1abcdef0abcde"

The following example key policy statement allows the data-processing role to use the KMS key for the Decrypt operation.

The kms:RecipientAttestation:PCR condition key in this statement allows the operation only when the PCR1 value in the signed attestation document in the request matches kms:RecipientAttestation:PCR1 value in the condition. Use the StringEqualsIgnoreCase policy operator to require a case-insensitive comparison of the PCR values.

If the request does not include an attestation document, permission is denied because this condition is not satisfied.

{
  "Sid" : "Enable enclave data processing",
  "Effect" : "Allow",
  "Principal" : {
    "AWS" : "arn:aws:iam::111122223333:role/data-processing"
  },
  "Action": "kms:Decrypt",
  "Resource" : "*",
  "Condition": {
    "StringEqualsIgnoreCase": {
      "kms:RecipientAttestation:PCR1": "0x1de4f2dcf774f6e3b679f62e5f120065b2e408dcea327bd1c9dddaea6664e7af7935581474844767453082c6f1586116376cede396a30a39a611b9aad7966c87"
    }
  }
}

Monitoring requests for Nitro enclaves

You can use your Amazon CloudTrail logs to monitor Decrypt, GenerateDataKey, GenerateDataKeyPair, and GenerateRandom operations for an Amazon Nitro enclave. In these log entries, the additionalEventData field has a recipient field with the module ID (attestationDocumentModuleId), image digest (attestationDocumentEnclaveImageDigest), and platform configuration registers (PCRs) from the attestation document in the request. These fields are included only when the Recipient parameter in the request specifies a signed attestation document from an Amazon Nitro enclave.

The module ID is the enclave ID 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. For information about the PCRs, see Where to get an enclave's measurements in the Amazon Nitro Enclaves User Guide.

This section shows an example CloudTrail log entry for each of the supported Nitro enclave requests to Amazon KMS.

Decrypt (for an enclave)

The following example shows an Amazon CloudTrail log entry of a Decrypt operation for an Amazon 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": "Amazon 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": "<AttestationDocument.PCR0>",
            "attestationDocumentEnclavePCR1": "<AttestationDocument.PCR1>",
            "attestationDocumentEnclavePCR2": "<AttestationDocument.PCR2>",
            "attestationDocumentEnclavePCR3": "<AttestationDocument.PCR3>",
            "attestationDocumentEnclavePCR4": "<AttestationDocument.PCR4>",
            "attestationDocumentEnclavePCR8": "<AttestationDocument.PCR8>"
        }
    },
    "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"
}
Show moreShow less

GenerateDataKey (for an enclave)

The following example shows an Amazon CloudTrail log entry of a GenerateDataKey operation for an Amazon 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": "Amazon Internal",
    "requestParameters": {
        "keyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "numberOfBytes": 32
    },
    "responseElements": null,
    "additionalEventData": {
        "recipient": {
            "attestationDocumentModuleId": "i-123456789abcde123-enc123456789abcde12",
            "attestationDocumentEnclaveImageDigest": "<AttestationDocument.PCR0>",
            "attestationDocumentEnclavePCR1": "<AttestationDocument.PCR1>",
            "attestationDocumentEnclavePCR2": "<AttestationDocument.PCR2>",
            "attestationDocumentEnclavePCR3": "<AttestationDocument.PCR3>",
            "attestationDocumentEnclavePCR4": "<AttestationDocument.PCR4>",
            "attestationDocumentEnclavePCR8": "<AttestationDocument.PCR8>"
        }
    },
    "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"
}
Show moreShow less

GenerateDataKeyPair (for an enclave)

The following example shows an Amazon CloudTrail log entry of a GenerateDataKeyPair operation for an Amazon 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": "Amazon Internal",
    "requestParameters": {
        "keyPairSpec": "RSA_3072",
        "encryptionContext": {
            "Project": "Alpha"
        },
        "keyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
    },
    "responseElements": null,
    "additionalEventData": {
        "recipient": {
            "attestationDocumentModuleId": "i-123456789abcde123-enc123456789abcde12",
            "attestationDocumentEnclaveImageDigest": "<AttestationDocument.PCR0>",
            "attestationDocumentEnclavePCR1": "<AttestationDocument.PCR1>",
            "attestationDocumentEnclavePCR2": "<AttestationDocument.PCR2>",
            "attestationDocumentEnclavePCR3": "<AttestationDocument.PCR3>",
            "attestationDocumentEnclavePCR4": "<AttestationDocument.PCR4>",
            "attestationDocumentEnclavePCR8": "<AttestationDocument.PCR8>"
        }
    },
    "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"
}
Show moreShow less

GenerateRandom (for an enclave)

The following example shows an Amazon CloudTrail log entry of a GenerateRandom operation for an Amazon 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": "Amazon Internal",
    "requestParameters": null,
    "responseElements": null,
    "additionalEventData": {
        "recipient": {
            "attestationDocumentModuleId": "i-123456789abcde123-enc123456789abcde12",
            "attestationDocumentEnclaveImageDigest": "<AttestationDocument.PCR0>",
            "attestationDocumentEnclavePCR1": "<AttestationDocument.PCR1>",
            "attestationDocumentEnclavePCR2": "<AttestationDocument.PCR2>",
            "attestationDocumentEnclavePCR3": "<AttestationDocument.PCR3>",
            "attestationDocumentEnclavePCR4": "<AttestationDocument.PCR4>",
            "attestationDocumentEnclavePCR8": "<AttestationDocument.PCR8>"
        }
    },
    "requestID": "df1e3de6-63bc-11e4-bc2b-4198b6150d5c",
    "eventID": "239cb9f7-ae05-4c94-9221-6ea30eef0442",
    "readOnly": true,
    "resources": [],
    "eventType": "AwsApiCall",
    "recipientAccountId": "111122223333"
}
Show moreShow less