Use aliases to control access to KMS keys - AWS Key Management Service
kms:RequestAliaskms:ResourceAliases

Use aliases to control access to KMS keys

You can control access to KMS keys based on the aliases that are associated with the KMS key. To do so, use the kms:RequestAlias and kms:ResourceAliases condition keys. This feature is part of AWS KMS support for attribute-based access control (ABAC).

The kms:RequestAlias condition key allows or denies access to a KMS key based on the alias in a request. The kms:ResourceAliases condition key allows or denies access to a KMS key based on the aliases associated with the KMS key.

These features do not allow you to identify a KMS key by using an alias in the resource element of a policy statement. When an alias is the value of a resource element, the policy applies to the alias resource, not to any KMS key that might be associated with it.

Note

It might take up to five minutes for tag and alias changes to affect KMS key authorization. Recent changes might be visible in API operations before they affect authorization.

When using aliases to control access to KMS keys, consider the following:

  • Use aliases to reinforce the best practice of least privileged access. Give IAM principals only the permissions that they need for only the KMS keys that they must use or manage. For example, use aliases to identify the KMS keys used for a project. Then give the project team permission to use only KMS keys with the project aliases.

  • Be cautious about giving principals the kms:CreateAlias, kms:UpdateAlias, or kms:DeleteAlias permissions that let them add, edit, and delete aliases. When you use aliases to control access to KMS keys, changing an alias can give principals permission to use KMS keys that they didn't otherwise have permission to use. It can also deny access to KMS keys that other principals require to do their jobs.

  • Review the principals in your AWS account that currently have permission to manage aliases and adjust the permissions, if necessary. Key administrators who don't have permission to change key policies or create grants can control access to KMS keys if they have permission to manage aliases.

    For example, the console default key policy for key administrators includes kms:CreateAlias, kms:DeleteAlias, and kms:UpdateAlias permission. IAM policies might give alias permissions for all KMS keys in your AWS account. For example, the AWSKeyManagementServicePowerUser managed policy allows principals to create, delete, and list aliases for all KMS keys but not update them.

  • Before setting a policy that depends on an alias, review the aliases on the KMS keys in your AWS account. Make sure that your policy applies only to the aliases that you intend to include. Use CloudTrail logs and CloudWatch alarms to alert you to alias changes that might affect access to your KMS keys. Also, the ListAliases response includes the creation date and last updated date for each alias.

  • The alias policy conditions use pattern matching; they aren't tied to a particular instance of an alias. A policy that uses alias-based condition keys affects all new and existing aliases that match the pattern. If you delete and recreate an alias that matches a policy condition, the condition applies to the new alias, just as it did to the old one.

The kms:RequestAlias condition key relies on the alias specified explicitly in an operation request. The kms:ResourceAliases condition key depends on the aliases that are associated with a KMS key, even if they don't appear in the request.

kms:RequestAlias

Allow or deny access to a KMS key based on the alias that identifies the KMS key in a request. You can use the kms:RequestAlias condition key in a key policy or IAM policy. It applies to operations that use an alias to identify a KMS key in a request, namely cryptographic operations, DescribeKey, and GetPublicKey. It is not valid for alias operations, such as CreateAlias or DeleteAlias.

In the condition key, specify an alias name or alias name pattern. You cannot specify an alias ARN.

For example, the following key policy statement allows principals to use the specified operations on the KMS key. The permission is effective only when the request uses an alias that includes alpha to identify the KMS key.

{
  "Sid": "Key policy using a request alias condition",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:role/alpha-developer"
  },
  "Action": [
    "kms:Decrypt",
    "kms:GenerateDataKey*",
    "kms:DescribeKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringLike": {
      "kms:RequestAlias": "alias/*alpha*"
    }
  }
}

The following example request from an authorized principal would fulfill the condition. However, a request that used a key ID, a key ARN, or a different alias would not fulfill the condition, even if these values identified the same KMS key.

$ aws kms describe-key --key-id "arn:aws:kms:us-west-2:111122223333:alias/project-alpha"

kms:ResourceAliases

Allow or deny access to a KMS key based on the aliases associated with the KMS key, even if the alias isn't used in a request. The kms:ResourceAliases condition key lets you specify an alias or alias pattern, such as alias/test*, so you can use it in an IAM policy to control access to several KMS keys in the same Region. It's valid for any AWS KMS operation that uses a KMS key.

For example, the following IAM policy lets the principals call the specified operations on the KMS keys in two AWS accounts. However, the permission applies only to KMS keys associated with aliases that begin with restricted.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AliasBasedIAMPolicy",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
      ],
      "Resource": [
        "arn:aws:kms:*:111122223333:key/*",
        "arn:aws:kms:*:444455556666:key/*"
      ],
      "Condition": {
        "ForAnyValue:StringLike": {
          "kms:ResourceAliases": "alias/restricted*"
        }
      }
    }
  ]
}

The kms:ResourceAliases condition is a condition of the resource, not the request. As such, a request that doesn't specify the alias can still satisfy the condition.

The following example request, which specifies a matching alias, satisfies the condition.

$ aws kms enable-key-rotation --key-id "alias/restricted-project"

However, the following example request also satisfies the condition, provided that the specified KMS key has an alias that begins with restricted, even if that alias isn't used in the request.

$ aws kms enable-key-rotation --key-id "1234abcd-12ab-34cd-56ef-1234567890ab"