Create KMS key, no review required - AMS Advanced Change Management User Guide

Create KMS key, no review required

Create a KMS key using the AMS console or the AMS API/CLI. This change type is ExecutionMode=Automated, so this change type does not require manual review by AMS operations and should execute more rapidly than KMS Key: Create (review required).

As part of automating this change type, AMS requires that you specify an existing KMS key policy.

Classification: Deployment | Advanced stack components | KMS key | Create (auto)

Change type ID: ct-1d84keiri1jhg

Version:

To learn more about AWS KMS keys, see AWS Key Management Service (KMS), AWS Key Management Service FAQs, and AWS Key Management Service Concepts.

Note

This CT has a new parameter, AllowServiceRolesAccessKMSKeys, that provides the specified AWS services access to the KMS key. The change was made because the Autoscaling group service role was unable to start the EC2 instances with encrypted EBS volumes due to lack of permissions to the KMS key.

Required Data:

  • Description: Meaningful information about the resource to be created.

  • VpcId: The VPC to use. For help finding VPC IDs, see Finding a VPC ID.

  • Name: A name for the stack or stack component; this becomes the Stack Name.

  • TimeoutInMinutes: How many minutes are allowed for the creation of the stack before the RFC is failed. This setting will not delay the RFC execution, but you must give enough time (for example, don't specify "5"). Valid values are "60" up to "360", for long-running UserData.

  • StackTemplateId: A name for the stack or stack component; this becomes the Stack Name.

  • Parameters:Description: Meaningful information about the KMS key.

Optional Data:

  • Parameters:

    • Alias: An alias for the AWS KMS key. The alias must not begin with "aws/".

    • EnableKeyRotation: True for automatic rotation of the key material for the specified KMS key, false for no automatic rotation. Default is true. For more information, see Rotating AWS KMS keys

    • Operation: Must be Create.

    • PendingWindow: The number of days in the waiting period before AWS KMS deletes the KMS key. Default is 30.

    • IAMPrincipalsRequiringDecryptPermissions: List of IAM ARNs that require permission to decrypt using the KMS key; for example arn:aws:iam::123456789012:role/myrole or arn:aws:iam::123456789012:user/myuser.

    • IAMPrincipalsRequiringEncryptPermissions: List of IAM ARNs that require permission to encrypt using the KMS key; for example arn:aws:iam::123456789012:role/myrole or arn:aws:iam::123456789012:user/myuser.

    • IAMPrincipalsRequiringGrantsPermissions: List of IAM ARNs, or account IDs, allowed to use this KMS key for key grants; for example arn:aws:iam::123456789012:role/myrole or 123456789012.

    • LimitGrantsToAWSResources: True to allow only AWS services that are integrated with AWS KMS to perform the grant operation on the user's behalf, false to allow any principal provided in IAMPrincipalsRequiringGrantsPermissions. Default is false.

    • EnforceEncryptionContextKeys: True to enforce use of encryption context keys in cryptographic operations, false to not. To define the encryption context keys, use AllowedEncryptionContextKeys. Default is false.

    • AllowedEncryptionContextKeys: List of encryption context keys that must be present in requests for cryptographic operations. If supplied, all cryptographic operations must have one of the context keys from this list.

    • AllowServiceRolesAccessKMSKeys: Provide KMS key access to AWS services, by providing the endpoint in the form, ec2.us-east-1.amazonaws.com. Then the specified AWS service can use the KMS key with limited permissions (list and create grants; describe, encrypt, decrypt, and reencrypt key; and generate data key).

Screenshot of this change type in the AMS console:

How it works:

  1. Navigate to the Choose change type page: RFCs -> Create RFC.

  2. Choose a change type from the drop-down lists. Optionally, open the Additional configuration area to select a change type version. After your selections are complete, a Change type: details area opens. Choose Next.

  3. Configure the request for change. A Subject is required. Optionally, open the Additional configuration area to add information about the RFC. Choose Next.

  4. Choose the execution parameters. At the top, in the RFC configuration area, enter values for the change type required parameters. These vary by change type. Open the Additional configuration area to add Tags or additional settings. Some change types also provide a Parameters area where only the required settings are visible. In that case, open the Additional configuration area to view optional parameters.

  5. When finished, choose Create. If there are no errors, the RFC successfully created page displays with the submitted RFC details, and the initial Execution output.

  6. Open the Execution parameters area to see the configurations you submitted. Refresh the page to update the RFC execution status. Optionally, cancel the RFC or create a copy of it with the options at the top of the page.

How it works:

  1. Use either the Inline Create (you issue a create-rfc command with all RFC and execution parameters included), or Template Create (you create two JSON files, one for the RFC parameters and one for the execution parameters) and issue the create-rfc command with the two files as input. Both methods are described here.

  2. Submit the RFC: aws amscm submit-rfc --rfc-id ID command with the returned RFC ID.

    Monitor the RFC: aws amscm get-rfc --rfc-id ID command.

To check the change type version, use this command:

aws amscm list-change-type-version-summaries --filter Attribute=ChangeTypeId,Value=CT_ID
Note

You can use any CreateRfc parameters with any RFC whether or not they are part of the schema for the change type. For example, to get notifications when the RFC status changes, add this line, --notification "{\"Email\": {\"EmailRecipients\" : [\"email@example.com\"]}}" to the RFC parameters part of the request (not the execution parameters). For a list of all CreateRfc parameters, see the AMS Change Management API Reference.

INLINE CREATE:

Issue the create RFC command with execution parameters provided inline (escape quotes when providing execution parameters inline), and then submit the returned RFC ID. For example, you can replace the contents with something like this:

Required parameters only:

aws amscm create-rfc --title my-app-key --change-type-id ct-1d84keiri1jhg --change-type-version 1.0 --execution-parameters '{"Description":"KMS key for my-app","VpcId":"VPC_ID","Name":"my-app-key","StackTemplateId":"stm-enf1j068fhg34vugt","TimeoutInMinutes":60,"Parameters":{"Description":"KMS key for my-app"}}'

TEMPLATE CREATE:

  1. Output the execution parameters JSON schema for this change type to a file; this example names it CreateKmsKeyAutoParams.json.

    aws amscm get-change-type-version --change-type-id "ct-2epp05svrlwod" --query "ChangeTypeVersion.ExecutionInputSchema" --output text > CreateKmsKeyAutoParams.json
  2. Modify and save the CreateKmsKeyAutoParams file. Examples follow.

    Grant a user or a role, permission to decrypt the created CMK. Example execution parameters:

    { "Description": "KMS key for my-app", "VpcId": "VPC_ID”, "Name": "my-app-key-decrypt", "StackTemplateId": "stm-enf1j068fhg34vugt", "TimeoutInMinutes": 60, "Parameters": { "IAMPrincipalsRequiringDecryptPermissions": [ "ARN:role/roleA", "ARN:user/userB", "ARN:role/instanceProfileA" ], "Description": "KMS key for my-app" } }

    For the resulting policy, see Grants Permissions to Decrypt with the CML for an IAM User or a Role.

    Grant a user or role, permission to encrypt using the created CMK. Example execution parameters:

    { "Description": "KMS key for my-app", "VpcId": "VPC_ID", "Name": "my-app-key-encrypt", "Tags": [ { "Key": "Name", "Value": "my-app-key" } ], "StackTemplateId": "stm-enf1j068fhg34vugt", "TimeoutInMinutes": 60, "Parameters": { "IAMPrincipalsRequiringEncryptPermissions": [ "ARN:role/roleA", "ARN:user/userB", "ARN:role/instanceProfileA" ], "Description": "KMS key for my-app" } }

    For the resulting policy, see Grants Permissions to Encrypt with the CML for an IAM User or a Role.

    Grant a user, role, or account, permission to create grants using the created CMK. Example execution parameters:

    { "Description": "KMS key for my-app", "VpcId": "VPC_ID", "Name": "my-app-key-create-grants", "StackTemplateId": "stm-enf1j068fhg34vugt", "TimeoutInMinutes": 60, "Parameters": { "IAMPrincipalsRequiringGrantsPermissions": [ "arn:aws:iam::999999999999:role/roleA", "888888888888" ], "Description": "KMS key for my-app" } }

    For the resulting policy, see Grants Permissions to Create Grants with the CMK for an IAM User, Role, or Account.

    Allow only AWS services that are integrated with AWS KMS to perform the GRANT operation. Example execution parameters:

    { "Description": "KMS key for my-app", "VpcId": "VPC_ID", "Name": "my-app-key-limit-to-services", "StackTemplateId": "stm-enf1j068fhg34vugt", "TimeoutInMinutes": 60, "Parameters": { "IAMPrincipalsRequiringGrantsPermissions": [ "arn:aws:iam::999999999999:role/roleA" ], "LimitGrantsToAWSResources": "true", "Description": "KMS key for my-app" } }

    For the resulting policy, see Allow only AWS services that are Integrated with AWS KMS to Perform the GRANT Operation.

    Enforce use of encryption context keys in cryptographic operations. Example execution parameters:

    { "Description": "KMS key for my-app", "VpcId": "VPC_ID", "Name": "my-app-key-encryption-keys", "StackTemplateId": "stm-enf1j068fhg34vugt", "TimeoutInMinutes": 60, "Parameters": { "EnforceEncryptionContextKeys": "true", "Description": "KMS key for my-app" } }

    For the resulting policy, see Enforce use of Encryption Context Keys in Cryptographic Operations.

    Enforce a specific list of encryption context keys in cryptographic operations. Example execution parameters:

    { "Description": "KMS key for my-app", "VpcId": "VPC_ID", "Name": "my-app-key-encryption-list", "StackTemplateId": "stm-enf1j068fhg34vugt", "TimeoutInMinutes": 60, "Parameters": { "AllowedEncryptionContextKeys": [ "Name", "Application" ], "Description": "KMS key for my-app" } }

    For the resulting policy, see Enforce a Specific List of Encryption Context Keys in Cryptographic Operations.

    Allow AWS services to access the created CMK. Example execution parameters:

    { "Description" : "KMS key for my-app", "VpcId" : "VPC_ID", "Name" : "my-app-key-allow-aws-service-access", "StackTemplateId" : "stm-enf1j068fhg34vugt", "TimeoutInMinutes" : 60, "Parameters" : { "AllowServiceRolesAccessKMSKeys": [ "ec2.us-east-1.amazonaws.com", "ecr.us-east-1.amazonaws.com" ], "Description": "KMS key for my-app" } }

    For the resulting policy, see Allow AWS services to access created CMK.

  3. Output the RFC template JSON file to a file; this example names it CreateKmsKeyAutoRfc.json:

    aws amscm create-rfc --generate-cli-skeleton > CreateKmsKeyAutoRfc.json
  4. Modify and save the CreateKmsKeyAutoRfc.json file. For example, you can replace the contents with something like this:

    { "ChangeTypeId": "ct-1d84keiri1jhg", "ChangeTypeVersion": "1.0", "Title": "Create KMS Key" }
  5. Create the RFC, specifying the CreateKmsKeyAuto Rfc file and the CreateKmsKeyAutoParams file:

    aws amscm create-rfc --cli-input-json file://CreateKmsKeyAutoRfc.json --execution-parameters file://CreateKmsKeyAutoParams.json

    You receive the ID of the new RFC in the response and can use it to submit and monitor the RFC. Until you submit it, the RFC remains in the editing state and does not start.

KMS Key Create (Auto) Resulting Policies

Depending on how you created your KMS key, you created policies. These example policies match various KMS key create scenarios provided in Creating an AWS KMS Key with the CLI.

Grants Permissions to Decrypt with the CML for an IAM User or a Role

Resulting example policy grants IAM users, roles or instance profiles, permission to decrypt using the CMK:

{ "Sid": "Allow decrypt using the key", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::999999999999:role/roleA", "arn:aws:iam::999999999999:user/userB", "arn:aws:iam::999999999999:role/instanceProfileA" ] }, "Action": [ "kms:DescribeKey", "kms:Decrypt" ], "Resource": "*" }

For the execution parameters to create this policy with the KMS key Create (auto) change type, see Creating an AWS KMS Key with the CLI

Grants Permissions to Encrypt with the CML for an IAM User or a Role

Resulting example policy grants IAM users, roles or instance profiles, permission to encrypt using the CMK:

{ "Sid": "Allow encrypt using the key", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::999999999999:role/roleA", "arn:aws:iam::999999999999:user/userB", "arn:aws:iam::999999999999:role/instanceProfileA" ] }, "Action": [ "kms:DescribeKey", "kms:Encrypt", "kms:ReEncrypt*", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext" ], "Resource": "*" }

For the execution parameters to create this policy with the KMS key Create (auto) change type, see Creating an AWS KMS Key with the CLI

Grants Permissions to Create Grants with the CMK for an IAM User, Role, or Account

Resulting example policy:

{ "Sid": "Allow grants", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::999999999999:role/roleA", "arn:aws:iam::888888888888:root" ] }, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*" }

For the execution parameters to create this policy with the KMS key Create (auto) change type, see Creating an AWS KMS Key with the CLI

Allow only AWS services that are Integrated with AWS KMS to Perform the GRANT Operation

Resulting example policy:

{ "Sid": "Allow grants", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::999999999999:role/roleA" }, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*" }, { "Sid": "Deny if grant is not for AWS resource", "Effect": "Deny", "Principal": { "AWS": "*" }, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*", "Condition": { "Bool": { "kms:GrantIsForAWSResource": "false" } } } } }

For the execution parameters to create this policy with the KMS key Create (auto) change type, see Creating an AWS KMS Key with the CLI

Enforce use of Encryption Context Keys in Cryptographic Operations

Resulting example policy:

{ "Effect": "Deny", "Principal": { "AWS": "*" }, "Action": [ "kms:CreateGrant", "kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey*", "kms:ReEncrypt" ], "Resource": "*", "Condition": { "Null": { "kms:EncryptionContextKeys": "true" } } }

For the execution parameters to create this policy with the KMS key Create (auto) change type, see Creating an AWS KMS Key with the CLI

Enforce a Specific List of Encryption Context Keys in Cryptographic Operations

Resulting example policy:

{ "Effect": "Deny", "Principal": { "AWS": "*" }, "Action": [ "kms:CreateGrant", "kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey*", "kms:ReEncrypt" ], "Resource": "*", "Condition": { "StringEquals": { "kms:EncryptionContextKeys": [ "Name", "Application" ] } } }

For the execution parameters to create this policy with the KMS key Create (auto) change type, see Creating an AWS KMS Key with the CLI

Allow AWS services to access created CMK

Resulting example policy:

{ "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": [ "kms:ListGrants", "kms:CreateGrant", "kms:DescribeKey", "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": [ "ec2.us-west-2.amazonaws.com", "ecr.us-east-1.amazonaws.com" ], "kms:CallerAccount": "111122223333" } } }

For the execution parameters to create this policy with the KMS key Create (auto) change type, see Creating an AWS KMS Key with the CLI