Control 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.
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. For more information, see Authorizing Amazon KMS to synchronize multi-Region keys.
Topics
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" } }