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 (PDF).

Controlling access to aliases

When you create or change an alias, you affect the alias and its associated KMS key. Therefore, principals who manage aliases must have permission to call the alias operation on the alias and on all affected KMS keys. You can provide these permissions by using key policies, IAM policies and grants.

For information about controlling access to all Amazon KMS operations, see Permissions reference.

Permissions to create and manage aliases work as follows.

kms:CreateAlias

To create an alias, the principal needs the following permissions for both the alias and for the associated KMS key.

You can use condition keys to limit the KMS keys that you can associate with an alias. For example, you can use the kms:KeySpec condition key to allow the principal to create aliases only on asymmetric KMS keys. For a full list of conditions keys that you can use to limit the kms:CreateAlias permission on KMS key resources, see Amazon KMS permissions.

kms:ListAliases

To list aliases in the account and Region, the principal must have kms:ListAliases permission in an IAM policy. Because this policy isn't related to any particular KMS key or alias resource, the value of the resource element in the policy must be "*".

For example, the following IAM policy statement gives the principal permission to list all KMS keys and aliases in the account and Region.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "kms:ListKeys",
      "kms:ListAliases"
    ],
    "Resource": "*"
  }
}

kms:UpdateAlias

To change the KMS key that is associated with an alias, the principal needs three permission elements: one for the alias, one for the current KMS key, and one for the new KMS key.

For example, suppose you want to change the test-key alias from the KMS key with key ID 1234abcd-12ab-34cd-56ef-1234567890ab to the KMS key with key ID 0987dcba-09fe-87dc-65ba-ab0987654321. In that case, include policy statements similar to the examples in this section.

You can use condition keys to limit either or both of KMS keys in an UpdateAlias operation. For example, you can use a kms:ResourceAliases condition key to allow the principal to update aliases only when the target KMS key already has a particular alias. For a full list of conditions keys that you can use to limit the kms:UpdateAlias permission on a KMS key resource, see Amazon KMS permissions.

kms:DeleteAlias

To delete an alias, the principal needs permission for the alias and for the associated KMS key.

As always, you should exercise caution when giving principals permission to delete a resource. However, deleting an alias has no effect on the associated KMS key. Although it might cause a failure in an application that relies on the alias, if you mistakenly delete an alias, you can recreate it.

Limiting alias permissions

You can use condition keys to limit alias permissions when the resource is a KMS key. For example, the following IAM policy allows the alias operations on KMS keys in a particular account and Region. However, it uses the kms:KeyOrigin condition key to further limit the permissions to KMS keys with key material from Amazon KMS.

For a full list of conditions keys that you can use to limit alias permission on a KMS key resource, see Amazon KMS permissions.

{
  "Sid": "IAMPolicyKeyPermissions",
  "Effect": "Allow",
  "Resource": "arn:aws:kms:us-west-2:111122223333:key/*",
  "Action": [
    "kms:CreateAlias",
    "kms:UpdateAlias",
    "kms:DeleteAlias"
  ],
  "Condition": {
    "StringEquals": {
      "kms:KeyOrigin": "AWS_KMS"
    }
  }  
}

You can't use condition keys in a policy statement where the resource is an alias. To limit the aliases that a principal can manage, use the value of the Resource element of the IAM policy statement that controls access to the alias. For example, the following policy statements allow the principal to create, update, or delete any alias in the Amazon Web Services account and Region unless the alias begins with Restricted.

{
  "Sid": "IAMPolicyForAnAliasAllow",
  "Effect": "Allow",
  "Action": [
    "kms:CreateAlias",
    "kms:UpdateAlias",
    "kms:DeleteAlias"
  ],
  "Resource": "arn:aws:kms:us-west-2:111122223333:alias/*"
},
{
  "Sid": "IAMPolicyForAnAliasDeny",
  "Effect": "Deny",
  "Action": [
    "kms:CreateAlias",
    "kms:UpdateAlias",
    "kms:DeleteAlias"
  ],
  "Resource": "arn:aws:kms:us-west-2:111122223333:alias/Restricted*"
}