Share Custom Encryption Keys More Securely Between Accounts by Using AWS Key Management Service

AWS Key Management Service (KMS) is a managed service that makes it easy for you to create, control, rotate, and use your encryption keys in your applications. KMS allows you to create custom keys that other AWS Identity and Access Management (IAM) users and roles in your AWS account can use. You can also enable cross-account access to those custom keys in your account.

You may find cross-account access useful when you have multiple AWS accounts and want to restrict management actions on a key to one account, but enable IAM users and roles in other accounts to use the key to encrypt and decrypt data. This configuration protects the key from being modified or disabled if the other accounts under your control are no longer trusted. In this post, you will learn how to enable cross-account access to custom encryption keys by using the KMS console. Cross-account access can be enabled either during the key creation process or after you have created a custom key. 

How to enable cross-account access during the key creation process

You can give external accounts (in other words, different AWS accounts) usage permissions to a key during the key creation process. In the Define Key Usage Permissions section of the key-creation workflow in the KMS console, click Add an External Account and then type the 12-digit AWS account ID of the external AWS account. Repeat this process for each additional external account you want to add.

You can preview the policy document tied to this key by clicking Next Step.

How to enable cross-account access to existing custom keys

In the KMS console, click the custom key alias for which you want to enable cross-account access. On the following page, you will see the Key Usage section in the bottom half of the page.

In the Key Usage section, look for the External Accounts subsection, and click Add External Account. Type the 12-digit AWS account ID of the account that you want to be able to use this key. Repeat this process for each additional external account you want to add. Click Save Changes when you are done.

When you grant access to an external account to use your custom key, keep in mind four important things:

1. The key will not appear anywhere in the AWS Management Console for administrators of the external account to directly manage or select when creating encrypted resources. The administrator of the external account will need to specify the key’s ARN to use the key to create encrypted resources.
2. After you grant access to external accounts, root users of those external accounts can execute the following actions using your key: Encrypt, Decrypt, ReEncrypt, GenerateDataKey, and DescribeKey. These KMS APIs are the ones needed to select keys from the console of supported AWS services and use them to encrypt data in these services or in your own applications. The usage permissions statement defines which users or accounts have permissions to use Encrypt, Decrypt, ReEncrypt, GenerateDataKey, and DescribeKey operations with this key. In the following example, both the parent account, 109876543210, and the external account, 012345678901, are principals with these permissions.

	         {
	                  "Sid": "AllowUseOfTheKey",
	              "Effect": "Allow",
	              "Principal": {
	                "AWS": [
	                  "arn:aws:iam:: 109876543210:user/User1","arn:aws:iam::012345678901:root"
	                ]
	              },
	              "Action": [
	                "kms:Encrypt",
	                "kms:Decrypt",
	                "kms:ReEncrypt*",
	                "kms:GenerateDataKey*",
	                "kms:DescribeKey"
	              ],
	              "Resource": "*"
                  }

You can use the command line interface (CLI) to edit this key policy using the PutPolicy call to further restrict the allowable actions to a subset of these actions. For example, you may have a use case where you want to allow the account only to encrypt with the KMS key but not to decrypt it.

3. AWS services integrated with KMS can use your key on behalf of external accounts for which you have enabled cross-account access. These permissions enable AWS services integrated with KMS to use this key on behalf of the specified principals—in this case, the parent account, 109876543210, and the external account, 012345678901. Specifically, this statement permits AWS services to create and manage grants on your key. These grants are additional scoped-down permissions that AWS services use to manage certain encrypted resources in a more secure fashion. The condition in this key policy uses a context key that is designed to ensure that AWS services apply only these permissions on resources in your AWS account.

                    {    
                      "Sid": "AllowAttachmentOfPersistentResources",
		      "Effect": "Allow",
		      "Principal": {
		        "AWS": [
		          "arn:aws:iam::109876543210:user/User1","arn:aws:iam::012345678901:root"
		        ]
		      },
		      "Action": [
		        "kms:CreateGrant",
		        "kms:ListGrants",
		        "kms:RevokeGrant"
		      ],
		      "Resource": "*",
		      "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}}  
                    }

4. IAM users and roles in the external account will not be able to use the key unless the account administrator of the external account creates and attaches a resource-level policy that specifies the KMS key ARN and permitted actions. The key’s ARN can be referenced only in a policy associated with IAM users under the external account (012345678901, in this example).The permitted actions will be a subset of the actions that the administrator has access to, as defined in step 1 above. If IAM users or roles in the external account, 012345678901, need to be able to use your custom key, the following IAM policy should be attached to those users or roles by the IAM administrator of the external account:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowUseOfTheKey",
            "Effect": "Allow",
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:DescribeKey"
            ],
            "Resource": [
                "arn:aws:kms:us-east-1:109876543210:key/1a345678-1234-1234-1234-12345678901c"
            ]
        },
        {
            "Sid": "AllowAttachmentOfPersistentResources",
            "Effect": "Allow",
            "Action": [
                "kms:CreateGrant",
                "kms:ListGrants",
                "kms:RevokeGrant"
            ],
            "Resource": [
                "arn:aws:kms:us-east-1:109876543210:key/1a345678-1234-1234-1234-12345678901c"
            ],
            "Condition": {
                "Bool": {
                    "kms:GrantIsForAWSResource": true
                }
          }
        }
    ]
}

The resource in the first statement of this key policy refers to the Amazon Resource Name (ARN) of your custom key. The second statement allows the IAM user to create grants. We do not recommend making changes to the actions allowed in this policy if your IAM users or roles need to use AWS services that integrate with KMS. These services assume that all the default actions are enabled for the user or role; if any actions are missing, your users will experience unexpected results. However, if you know that an IAM user or role will use a key only from within a custom application that uses the KMS SDK, you can confidently control which API actions are allowed to meet your use-case goals.

The external account and the IAM users in that account can now use your custom key. Note that the external account and the IAM users in that account must specify the key ARN or alias ARN to use the key. If the external account no longer needs access to your key, you can go back to the KMS console and remove the external account from the External Accounts section, as shown in the following image.

To learn more about cross-account access to custom keys, see the KMS documentation. If you have questions or comments about this feature or any other KMS feature, post them in the KMS forum.

-Sree

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.