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.

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 AWS 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 AWS 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.

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:

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 AWS 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:

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 AWS KMS.

To restrict the AWS 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.

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 AWS 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 AWS 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 AWS 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 AWS KMS to synchronize multi-Region keys

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

About the service-linked role for multi-Region keys

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

For multi-Region keys, AWS 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 AWS KMS can assume this service-linked role. This role is limited to the operations that AWS KMS needs to synchronize multi-Region shared properties. It does not give AWS KMS any additional permissions. For example, AWS KMS does not have permission to create, replicate, or delete any KMS keys.

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

Create the service-linked role

AWS KMS automatically creates the AWSServiceRoleForKeyManagementServiceMultiRegionKeys service-linked role in your AWS 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

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