Controlling access to multi-Region keys - Amazon Key Management Service
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.

Controlling access to multi-Region keys

You can use multi-Region keys in compliance, disaster recovery, and backup scenarios that would be more complex with single-Region keys. However, because the security properties of multi-Region keys are significantly different from those of single-Region keys, we recommend using caution when authorizing the creation, management, and use of multi-Region keys.

Note

Existing IAM policy statements with wildcard characters in the Resource field now apply to both single-Region and multi-Region keys. To restrict them to single-Region KMS keys or multi-Region keys, use the kms:MultiRegion condition key.

Use your authorization tools to prevent creation and use of multi-Region keys in any scenario where a single-Region will suffice. Allow principals to replicate a multi-Region key only into Amazon Web Services Regions that require them. Give permission for multi-Region keys only to principals who need them and only for tasks that require them.

You can use key policies, IAM policies, and grants to allow IAM principals to manage and use multi-Region keys in your Amazon Web Services account. Each multi-Region key is an independent resource with a unique key ARN and key policy. You need to establish and maintain a key policy for each key and make sure that new and existing IAM policies implement your authorization strategy.

Authorization basics for multi-Region keys

When designing key policies and IAM policies for multi-Region keys, consider the following principles.

  • Key policy — Each multi-Region key is an independent KMS key resource with its own key policy. You can apply the same or a different key policy to each key in the set of related multi-Region keys. Key policies are not shared properties of multi-Region keys. Amazon KMS does not copy or synchronize key policies among related multi-Region keys.

    When you create a replica key in the Amazon KMS console, the console displays the current key policy of the primary key as a convenience. You can use this key policy, edit it, or delete and replace it. But even if you accept the primary key policy unchanged, Amazon KMS doesn't synchronize the policies. For example, if you change the key policy of the primary key, the key policy of the replica key remains the same.

  • Default key policy — When you create multi-Region keys by using the CreateKey and ReplicateKey operations, the default key policy is applied unless you specify a key policy in the request. This is the same default key policy that is applied to single-Region keys.

  • IAM policies — As with all KMS keys, you can use IAM policies to control access to multi-Region keys only when the key policy allows it. IAM policies apply to all Amazon Web Services Regions by default. However, you can use condition keys, such as aws:RequestedRegion, to limit permissions to a particular Region.

    To create primary and replica keys, principals must have kms:CreateKey permission in an IAM policy that applies to the Region where the key is created.

  • Grants — Amazon KMS grants are Regional. Each grant allows permissions to one KMS key. You can use grants to allow permissions to a multi-Region primary key or replica key. But you cannot use a single grant to allow permissions to multiple KMS keys, even if they are related multi-Region keys.

  • Key ARN — Each multi-Region key has a unique key ARN. The key ARNs of related multi-Region keys have the same partition, account, and key ID, but different Regions.

    To apply an IAM policy statement to a particular multi-Region key, use its key ARN or a key ARN pattern that includes the Region. To apply an IAM policy statement to all related multi-Region keys, use a wildcard character (*) in the Region element of the ARN, as shown in the following example.

    { "Effect": "Allow", "Action": [ "kms:Describe*", "kms:List*" ], "Resource": { "arn:aws:kms:*::111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab" } }

    To apply a policy statement to all multi-Region keys in your Amazon Web Services account, you can use the kms:MultiRegion policy condition or a key ID pattern that includes the distinctive mrk- prefix.

  • Service-linked role — Principals who create multi-Region primary keys must have iam:CreateServiceLinkedRole permission.

    To synchronize the shared properties of related multi-Region keys, Amazon KMS assumes an IAM service-linked role. Amazon KMS creates the service-linked role in the Amazon Web Services account whenever you create a multi-Region primary key. (If the role exists, Amazon KMS recreates it, which has no harmful effect.) The role is valid in all Regions. To allow Amazon KMS to create (or recreate) the service-linked role, principals who create multi-Region primary keys must have iam:CreateServiceLinkedRole permission.

Authorizing multi-Region key administrators and users

Principals who create and manage multi-Region keys need the following permissions in the primary and replica Regions:

  • kms:CreateKey

  • kms:ReplicateKey

  • kms:UpdatePrimaryRegion

  • iam:CreateServiceLinkedRole

Creating a primary key

To create a multi-Region primary key, the principal needs kms:CreateKey and iam:CreateServiceLinkedRole permissions in an IAM policy that is effective in the primary key's Region. Principals who have these permissions can create single-Region and multi-Region keys unless you restrict their permissions.

The iam:CreateServiceLinkedRole permission allows Amazon KMS to create the AWSServiceRoleForKeyManagementServiceMultiRegionKeys role to synchronize the shared properties of related multi-Region keys.

For example, this IAM policy allows a principal to create any type of KMS key.

{ "Version": "2012-10-17", "Statement":{ "Action": [ "kms:CreateKey", "iam:CreateServiceLinkedRole" ], "Effect":"Allow", "Resource":"*" } }

To allow or deny permission to create multi-Region primary keys, use the kms:MultiRegion condition key. Valid values are true (multi-Region key) or false (single-Region key). For example, the following IAM policy statement uses a Deny action with the kms:MultiRegion condition key to prevent principals from creating multi-Region keys.

{ "Version": "2012-10-17", "Statement":{ "Action":"kms:CreateKey", "Effect":"Deny", "Resource":"*", "Condition": { "Bool": "kms:MultiRegion": true } } }

Replicating keys

To create a multi-Region replica key, the principal needs the following permissions:

  • kms:ReplicateKey permission in the key policy of the primary key.

  • kms:CreateKey permission in an IAM policy that is effective in the replica key Region.

Use caution when allowing these permissions. They allow principals to create KMS keys and the key policies that authorize their use. The kms:ReplicateKey permission also authorizes the transfer of key material across Region boundaries within Amazon KMS.

To restrict the Amazon Web Services Regions in which a multi-Region key can be replicated, use the kms:ReplicaRegion condition key. It limits only the kms:ReplicateKey permission. Otherwise, it has no effect. For example, the following key policy allows the principal to replicate this primary key, but only in the specified Regions.

{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/Administrator" }, "Action": "kms:ReplicateKey", "Resource": "*", "Condition": { "StringEquals": { "kms:ReplicaRegion": [ "us-east-1", "eu-west-3", "ap-southeast-2" ] } } }

Updating the primary Region

Authorized principals can convert a replica key to a primary key, which changes the former primary key into a replica. This action is known as updating the primary Region. To update the primary Region, the principal needs kms:UpdatePrimaryRegion permission in both Regions. You can provide these permissions in a key policy or IAM policy.

  • kms:UpdatePrimaryRegion on the primary key. This permission must be effective in the primary key Region.

  • kms:UpdatePrimaryRegion on the replica key. This permission must be effective in the replica key Region.

For example, the following key policy gives users who can assume the Administrator role permission to update the primary Region of the KMS key. This KMS key can be the primary key or a replica key in this operation.

{ "Effect": "Allow", "Resource": "*", "Principal": { "AWS": "arn:aws:iam::111122223333:role/Administrator" }, "Action": "kms:UpdatePrimaryRegion" }

To restrict the Amazon Web Services Regions that can host a primary key, use the kms:PrimaryRegion condition key. For example, the following IAM policy statement allows the principals to update the primary Region of the multi-Region keys in the Amazon Web Services account, but only when the new primary Region is one of the specified Regions.

{ "Effect": "Allow", "Action": "kms:UpdatePrimaryRegion", "Resource": { "arn:aws:kms:*:111122223333:key/*" }, "Condition": { "StringEquals": { "kms:PrimaryRegion": [ "us-west-2", "sa-east-1", "ap-southeast-1" ] } } }

Using and managing multi-Region keys

By default, principals who have permission to use and manage KMS keys in an Amazon Web Services account and Region also have permission to use and manage multi-Region keys. However, you can use the kms:MultiRegion condition key to allow only single-Region keys or only multi-Region keys. Or use the kms:MultiRegionKeyType condition key to allow only multi-Region primary keys or only replica keys. Both condition keys controls access to the CreateKey operation and to any operation that uses an existing KMS key, such as Encrypt or EnableKey.

The following example IAM policy statement uses the kms:MultiRegion condition key to prevent the principals from using or managing any multi-Region key.

{ "Effect": "Deny", "Action": "kms:*", "Resource": "*", "Condition": { "Bool": "kms:MultiRegion": true } }

This example IAM policy statement uses the kms:MultiRegionKeyType condition to allow principals to schedule and cancel key deletion, but only on multi-Region replica keys.

{ "Effect": "Allow", "Action": [ "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": { "arn:aws:kms:us-west-2:111122223333:key/*" }, "Condition": { "StringEquals": "kms:MultiRegionKeyType": "REPLICA" } }

Authorizing Amazon KMS to synchronize multi-Region keys

To support multi-Region keys, Amazon KMS uses an IAM service linked role. This role gives Amazon KMS the permissions it needs to synchronize shared properties. You can view the SynchronizeMultiRegionKey CloudTrail event that records Amazon KMS synchronizing shared properties in your Amazon CloudTrail logs.

About the service-linked role for multi-Region keys

A service-linked role is an IAM role that gives one Amazon service permission to call other Amazon services on your behalf. It's designed to make it easier for you to use the features of multiple integrated Amazon services without having to create and maintain complex IAM policies.

For multi-Region keys, Amazon KMS creates the AWSServiceRoleForKeyManagementServiceMultiRegionKeys service-linked role with the AWSKeyManagementServiceMultiRegionKeysServiceRolePolicy policy. This policy gives the role the kms:SynchronizeMultiRegionKey permission, which allows it to synchronize the shared properties of multi-Region keys.

Because the AWSServiceRoleForKeyManagementServiceMultiRegionKeys service-linked role trusts only mrk.kms.amazonaws.com, only Amazon KMS can assume this service-linked role. This role is limited to the operations that Amazon KMS needs to synchronize multi-Region shared properties. It does not give Amazon KMS any additional permissions. For example, Amazon KMS does not have permission to create, replicate, or delete any KMS keys.

For more information about how Amazon services use service-linked roles, see Using Service-Linked Roles in the IAM User Guide.

Create the service-linked role

Amazon KMS automatically creates the AWSServiceRoleForKeyManagementServiceMultiRegionKeys service-linked role in your Amazon Web Services account when you create a multi-Region key, if the role does not already exist. You cannot create or re-create this service-linked role directly.

Edit the service-linked role description

You cannot edit the role name or the policy statements in the AWSServiceRoleForKeyManagementServiceMultiRegionKeys service-linked role, but you can edit the role description. For instructions, see Editing a Service-Linked Role in the IAM User Guide.

Delete the service-linked role

Amazon KMS does not delete the AWSServiceRoleForKeyManagementServiceMultiRegionKeys service-linked role from your Amazon Web Services account and you cannot delete it. However, Amazon KMS does not assume the AWSServiceRoleForKeyManagementServiceMultiRegionKeys role or use any of its permissions unless you have multi-Region keys in your Amazon Web Services account and Region.