# Aliases in AWS KMS
An *alias* is a friendly name for a AWS KMS key. For example, an alias lets you refer to a KMS key as `test-key` instead of `1234abcd-12ab-34cd-56ef-1234567890ab`.
You can use an alias to identify a KMS key in the AWS KMS console, in the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation, and in [cryptographic operations](kms-cryptography.md#cryptographic-operations), such as [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) and [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). Aliases also make it easy to recognize an [AWS managed key](concepts.md#aws-managed-key). Aliases for these KMS keys always have the form `aws/`. For example, the alias for the AWS managed key for Amazon DynamoDB is `aws/dynamodb`. You can establish similar alias standards for your projects, such as prefacing your aliases with the name of a project or category.
You can also allow and deny access to KMS keys based on their aliases without editing policies or managing grants. This feature is part of AWS KMS support for [attribute-based access control](abac.md) (ABAC). For details, see [Use aliases to control access to KMS keys](alias-authorization.md).
Much of the power of aliases come from your ability to change the KMS key associated with an alias at any time. Aliases can make your code easier to write and maintain. For example, suppose you use an alias to refer to a particular KMS key and you want to change the KMS key. In that case, just associate the alias with a different KMS key. You don't need to change your code.
Aliases also make it easier to reuse the same code in different AWS Regions. Create aliases with the same name in multiple Regions and associate each alias with a KMS key in its Region. When the code runs in each Region, the alias refers to the associated KMS key in that Region. For an example, see [Learn how to use aliases in your applications](alias-using.md).
You can create an alias for a KMS key in the AWS KMS console, by using the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) API, or by using the [AWS::KMS::Alias CloudFormation template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-alias.html).
The AWS KMS API provides full control of aliases in each account and Region. The API includes operations to create an alias ([CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html)), view alias names and alias ARNs ([ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html)), change the KMS key associated with an alias ([UpdateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateAlias.html)), and delete an alias ([DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html)).
## How aliases work
Learn how aliases work in AWS KMS.
**An alias is an independent AWS resource**
An alias is not a property of a KMS key. The actions that you take on the alias don't affect its associated KMS key. You can create an alias for a KMS key and then update the alias so it's associated with a different KMS key. You can even delete the alias without any effect on the associated KMS key. However, if you delete a KMS key, all aliases associated with that KMS key are deleted.
If you specify an alias as the resource in an IAM policy, the policy refers to the alias, not to the associated KMS key.
**Each alias has two formats**
When you create an alias, you specify the alias name. AWS KMS creates the alias ARN for you.
+ An [alias ARN](concepts.md#key-id-alias-ARN) is an Amazon Resource Name (ARN) that uniquely identifies the alias.
```
# Alias ARN
arn:aws:kms:us-west-2:111122223333:alias/
```
+ An [alias name](concepts.md#key-id-alias-name) that is unique in the account and Region. In the AWS KMS API, the alias name is always prefixed by `alias/`. That prefix is omitted in the AWS KMS console.
```
# Alias name
alias/
```
**Aliases are not secret**
Aliases may be displayed in plaintext in CloudTrail logs and other output. Do not include confidential or sensitive information in the alias name.
**Each alias is associated with one KMS key at a time**
The alias and its KMS key must be in the same account and Region.
You can associate an alias with any [customer managed key](concepts.md#customer-mgn-key) in the same AWS account and Region. However, you do not have permission to associate an alias with an [AWS managed key](concepts.md#aws-managed-key).
For example, this [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) output shows that the `test-key` alias is associated with exactly one target KMS key, which is represented by the `TargetKeyId` property.
```
{
"AliasName": "alias/test-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/test-key",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1593622000.191,
"LastUpdatedDate": 1593622000.191
}
```
**Multiple aliases can be associated with the same KMS key**
For example, you can associate the `test-key` and `project-key` aliases with the same KMS key.
```
{
"AliasName": "alias/test-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/test-key",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1593622000.191,
"LastUpdatedDate": 1593622000.191
},
{
"AliasName": "alias/project-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/project-key",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1516435200.399,
"LastUpdatedDate": 1516435200.399
}
```
**An alias must be unique in an account and Region**
For example, you can have only one `test-key` alias in each account and Region. Aliases are case-sensitive, but aliases that differ only in their capitalization are very prone to error. You cannot change an alias name. However, you can delete the alias and create a new alias with the desired name.
**You can create an alias with the same name in different Regions**
For example, you can have a `finance-key` alias in US East (N. Virginia) and a `finance-key` alias in Europe (Frankfurt). Each alias would be associated with a KMS key in its Region. If your code refers to an alias name like `alias/finance-key`, you can run it in multiple Regions. In each Region, it uses a different KMS key. For details, see [Learn how to use aliases in your applications](alias-using.md).
**You can change the KMS key associated with an alias**
You can use the [UpdateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateAlias.html) operation to associate an alias with a different KMS key. For example, if the `finance-key` alias is associated with the `1234abcd-12ab-34cd-56ef-1234567890ab` KMS key, you can update it so it is associated with the `0987dcba-09fe-87dc-65ba-ab0987654321` KMS key.
However, the current and new KMS key must be the same type (both symmetric or both asymmetric or both HMAC), and they must have the same [key usage](create-keys.md#key-usage) (ENCRYPT\$1DECRYPT or SIGN\$1VERIFY or GENERATE\$1VERIFY\$1MAC). This restriction prevents errors in code that uses aliases. If you must associate an alias with a different type of key, and you have mitigated the risks, you can delete and recreate the alias.
**Some KMS keys don't have aliases**
When you create a KMS key in the AWS KMS console, you must give it a new alias. But an alias is not required when you use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create a KMS key. Also, you can use the [UpdateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateAlias.html) operation to change the KMS key associated with an alias and the [DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html) operation to delete an alias. As a result, some KMS keys might have several aliases, and some might have none.
**AWS creates aliases in your account**
AWS creates aliases in your account for [AWS managed keys](concepts.md#aws-managed-key). These aliases have names of the form `alias/aws/`, such as `alias/aws/s3`.
Some AWS aliases have no KMS key. These predefined aliases are usually associated with an AWS managed key when you start using the service.
**Use aliases to identify KMS keys**
You can use an [alias name](concepts.md#key-id-alias-name) or [alias ARN](concepts.md#key-id-alias-ARN) to identify a KMS key in [cryptographic operations](kms-cryptography.md#cryptographic-operations), [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), and [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html). (If the [KMS key is in a different AWS account](key-policy-modifying-external-accounts.md), you must use its [key ARN](concepts.md#key-id-key-ARN) or alias ARN.) Aliases are not valid identifiers for KMS keys in other AWS KMS operations. For information about the valid [key identifiers](concepts.md#key-id) for each AWS KMS API operation, see the descriptions of the `KeyId` parameters in the *AWS Key Management Service API Reference*.
You cannot use an alias name or alias ARN to [identify a KMS key in an IAM policy](cmks-in-iam-policies.md). To control access to a KMS key based on its aliases, use the [kms:RequestAlias](conditions-kms.md#conditions-kms-request-alias) or [kms:ResourceAliases](conditions-kms.md#conditions-kms-resource-aliases) condition keys. For details, see [ABAC for AWS KMS](abac.md).
# 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](key-policies.md), [IAM policies](iam-policies.md) and [grants](grants.md).
**Note**
Be cautious when giving principals permission to manage tags and aliases. Changing a tag or alias can allow or deny permission to the customer managed key. For details, see [ABAC for AWS KMS](abac.md) and [Use aliases to control access to KMS keys](alias-authorization.md).
For information about controlling access to all AWS KMS operations, see [Permissions reference](kms-api-permissions-reference.md).
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.
+ `kms:CreateAlias` for the alias. Provide this permission in an IAM policy that is attached to the principal who is allowed to create the alias.
The following example policy statement specifies a particular alias in a `Resource` element. But you can list multiple alias ARNs or specify an alias pattern, such as "test\$1". You can also specify a `Resource` value of `"*"` to allow the principal to create any alias in the account and Region. Permission to create an alias can also be included in a `kms:Create*` permission for all resources in an account and Region.
```
{
"Sid": "IAMPolicyForAnAlias",
"Effect": "Allow",
"Action": [
"kms:CreateAlias",
"kms:UpdateAlias",
"kms:DeleteAlias"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:alias/test-key"
}
```
+ `kms:CreateAlias` for the KMS key. This permission must be provided in a key policy or in an IAM policy that is delegated from the key policy.
```
{
"Sid": "Key policy for 1234abcd-12ab-34cd-56ef-1234567890ab",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::111122223333:user/KMSAdminUser"},
"Action": [
"kms:CreateAlias",
"kms:DescribeKey"
],
"Resource": "*"
}
```
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](conditions-kms.md#conditions-kms-key-spec) 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 [AWS KMS permissions](kms-api-permissions-reference.md).
## 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 `"*"`](iam-policies-best-practices.md#require-resource-star).
For example, the following IAM policy statement gives the principal permission to list all KMS keys and aliases in the account and Region.
------
#### [ JSON ]
****
```
{
"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.
+ `kms:UpdateAlias` for the alias. You provide this permission in an IAM policy that is attached to the principal. The following IAM policy specifies a particular alias. But you can list multiple alias ARNs or specify an alias pattern, such as `"test*"`. You can also specify a `Resource` value of `"*"` to allow the principal to update any alias in the account and Region.
```
{
"Sid": "IAMPolicyForAnAlias",
"Effect": "Allow",
"Action": [
"kms:UpdateAlias",
"kms:ListAliases",
"kms:ListKeys"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:alias/test-key"
}
```
+ `kms:UpdateAlias` for the KMS key that is currently associated with the alias. This permission must be provided in a key policy or in an IAM policy that is delegated from the key policy.
```
{
"Sid": "Key policy for 1234abcd-12ab-34cd-56ef-1234567890ab",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::111122223333:user/KMSAdminUser"},
"Action": [
"kms:UpdateAlias",
"kms:DescribeKey"
],
"Resource": "*"
}
```
+ `kms:UpdateAlias` for the KMS key that the operation associates with the alias. This permission must be provided in a key policy or in an IAM policy that is delegated from the key policy.
```
{
"Sid": "Key policy for 0987dcba-09fe-87dc-65ba-ab0987654321",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::111122223333:user/KMSAdminUser"},
"Action": [
"kms:UpdateAlias",
"kms:DescribeKey"
],
"Resource": "*"
}
```
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](conditions-kms.md#conditions-kms-resource-aliases) 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 [AWS KMS permissions](kms-api-permissions-reference.md).
## 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.
+ `kms:DeleteAlias` for the alias. Provide this permission in an IAM policy attached to the principal who is allowed to delete the alias.
The following example policy statement specifies the alias in a `Resource` element. But you can list multiple alias ARNs or specify an alias pattern, such as `"test*"`, You can also specify a `Resource` value of `"*"` to allow the principal to delete any alias in the account and Region.
```
{
"Sid": "IAMPolicyForAnAlias",
"Effect": "Allow",
"Action": [
"kms:CreateAlias",
"kms:UpdateAlias",
"kms:DeleteAlias"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:alias/test-key"
}
```
+ `kms:DeleteAlias` for the associated KMS key. This permission must be provided in a key policy or in an IAM policy that is delegated from the key policy.
```
{
"Sid": "Key policy for 1234abcd-12ab-34cd-56ef-1234567890ab",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/KMSAdminUser"
},
"Action": [
"kms:CreateAlias",
"kms:UpdateAlias",
"kms:DeleteAlias",
"kms:DescribeKey"
],
"Resource": "*"
}
```
## 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](conditions-kms.md#conditions-kms-key-origin) condition key to further limit the permissions to KMS keys with key material from AWS KMS.
For a full list of conditions keys that you can use to limit alias permission on a KMS key resource, see [AWS KMS permissions](kms-api-permissions-reference.md).
```
{
"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 AWS 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*"
}
```
# Create aliases
You can create aliases in the AWS KMS console or by using AWS KMS API operations.
The alias must be string of 1–256 characters. It can contain only alphanumeric characters, forward slashes (/), underscores (\$1), and dashes (-). The alias name for a [customer managed key](concepts.md#customer-mgn-key) cannot begin with `alias/aws/`. The `alias/aws/` prefix is reserved for [AWS managed key](concepts.md#aws-managed-key).
You can create an alias for a new KMS key or for an existing KMS key. You might add an alias so that a particular KMS key is used in a project or application.
You can also use a AWS CloudFormation template to create an alias for a KMS key. For more information, see [AWS::KMS::Alias](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-alias.html) in the *AWS CloudFormation User Guide*.
## Using the AWS KMS console
When you [create a KMS key](create-keys.md) in the AWS KMS console, you must create an alias for the new KMS key. To create an alias for an existing KMS key, use the **Aliases** tab on the detail page for the KMS key.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**. You cannot manage aliases for AWS managed keys or AWS owned keys.
1. In the table, choose the key ID or alias of the KMS key. Then, on the KMS key detail page, choose the **Aliases** tab.
If a KMS key has multiple aliases, the **Aliases** column in the table displays one alias and an alias summary, such as **(\$1*n* more)**. Choosing the alias summary takes you directly to the **Aliases** tab on the KMS key detail page.
1. On the **Aliases** tab, choose **Create alias**. Enter an alias name and choose **Create alias**.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
**Note**
Do not add the `alias/` prefix. The console automatically adds it for you. If you enter `alias/ExampleAlias`, the actual alias name will be `alias/alias/ExampleAlias`.
## Using the AWS KMS API
To create an alias, use the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) operation. Unlike the process of creating KMS keys in the console, the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation doesn't create an alias for a new KMS key.
**Important**
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
You can use the `CreateAlias` operation to create an alias for a new KMS key with no alias. You can also use the `CreateAlias` operation to add an alias to any existing KMS key or to recreate an alias that was accidentally deleted.
In the AWS KMS API operations, the alias name must begin with `alias/` followed by a name, such as `alias/ExampleAlias`. The alias must be unique in the account and Region. To find the alias names that are already in use, use the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) operation. The alias name is case sensitive.
The `TargetKeyId` can be any [customer managed key](concepts.md#customer-mgn-key) in the same AWS Region. To identify the KMS key, use its [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN). You cannot use another alias.
The following example creates the `example-key` alias and associates it with the specified KMS key. These examples use the AWS Command Line Interface (AWS CLI). For examples in multiple programming languages, see [Use `CreateAlias` with an AWS SDK or CLI](example_kms_CreateAlias_section.md).
```
$ aws kms create-alias \
--alias-name alias/example-key \
--target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
`CreateAlias` does not return any output. To see the new alias, use the `ListAliases` operation. For details, see [Using the AWS KMS API](alias-view.md#alias-view-api).
# Find the alias name and alias ARN for a KMS key
Aliases make it easy to recognize KMS keys in the AWS KMS console. You can view the aliases for a KMS key in the AWS KMS console or by using the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) operation. The [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation, which returns the properties of a KMS key, does not include aliases.
The following procedures demonstrate how to view and identify the aliases associated with a KMS key using the AWS KMS console and AWS KMS API. The AWS KMS API examples use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
## Using the AWS KMS console
The AWS KMS console displays the aliases associated with the KMS key.
1. Open the AWS KMS console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. To view the keys in your account that you create and manage, in the navigation pane choose **Customer managed keys**. To view the keys in your account that AWS creates and manages for you, in the navigation pane, choose **AWS managed keys**.
1. The **Aliases** column displays the alias for each KMS key. If a KMS key does not have an alias, a dash (**-**) appears in the **Aliases** column.
If a KMS key has multiple aliases, the **Aliases** column also has an alias summary, such as **(\$1*n* more)**. For example, the following KMS key has two aliases, one of which is `key-test`.
To find the alias name and alias ARN of all aliases for the KMS key, use the **Aliases** tab.
+ To go directly to the **Aliases** tab, in the **Aliases** column, choose the alias summary (**\$1*n* more**). An alias summary appears only if the KMS key has more than one alias.
+ Or, choose the alias or key ID of the KMS key (which opens the detail page for the KMS key) and then choose the **Aliases** tab. The tabs are under the **General configuration** section.
![\[Customer managed keys interface showing a list with one key and options to create or filter keys.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/find-alias-name-1-sm.png)
1. The **Aliases** tab displays the alias name and alias ARN of all aliases for a KMS key. You can also create and delete aliases for the KMS key on this tab.
![\[Aliases tab showing two key aliases with their names and ARNs listed in a table format.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/alias-tab-1.png)
**AWS managed keys**
You can use the alias to recognize an AWS managed key, as shown in this example **AWS managed keys** page. The aliases for AWS managed keys always have the format: `aws/`. For example, the alias for the AWS managed key for Amazon DynamoDB is `aws/dynamodb`.
![\[Aliases in the AWS managed keys page of the AWS KMS console\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/alias-console-aws-managed-sm.png)
## Using the AWS KMS API
The [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) operation returns the alias name and alias ARN of aliases in the account and Region. The output includes aliases for AWS managed keys and for customer managed keys. The aliases for AWS managed keys have the format `aws/`, such as `aws/dynamodb`.
The response might also include aliases that have no `TargetKeyId` field. These are predefined aliases that AWS has created but has not yet associated with a KMS key.
```
$ aws kms list-aliases
{
"Aliases": [
{
"AliasName": "alias/access-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": 1516435200.399,
"LastUpdatedDate": 1516435200.399
},
{
"AliasName": "alias/ECC-P521-Sign",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ECC-P521-Sign",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1693622000.704,
"LastUpdatedDate": 1693622000.704
},
{
"AliasName": "alias/ImportedKey",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ImportedKey",
"TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
"CreationDate": 1493622000.704,
"LastUpdatedDate": 1521097200.235
},
{
"AliasName": "alias/finance-project",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/finance-project",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": 1604958290.014,
"LastUpdatedDate": 1604958290.014
},
{
"AliasName": "alias/aws/dynamodb",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb",
"TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef",
"CreationDate": 1521097200.454,
"LastUpdatedDate": 1521097200.454
},
{
"AliasName": "alias/aws/ebs",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs",
"TargetKeyId": "abcd1234-09fe-ef90-09fe-ab0987654321",
"CreationDate": 1466518990.200,
"LastUpdatedDate": 1466518990.200
}
]
}
```
To get all aliases that are associated with a particular KMS key, use the optional `KeyId` parameter of the `ListAliases` operation. The `KeyId` parameter takes the [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN) of the KMS key.
This example gets all aliases associated with the `0987dcba-09fe-87dc-65ba-ab0987654321` KMS key.
```
$ aws kms list-aliases --key-id 0987dcba-09fe-87dc-65ba-ab0987654321
{
"Aliases": [
{
"AliasName": "alias/access-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": "2018-01-20T15:23:10.194000-07:00",
"LastUpdatedDate": "2018-01-20T15:23:10.194000-07:00"
},
{
"AliasName": "alias/finance-project",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/finance-project",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": 1604958290.014,
"LastUpdatedDate": 1604958290.014
}
]
}
```
The `KeyId` parameter doesn't take wildcard characters, but you can use the features of your programming language to filter the response.
For example, the following AWS CLI command gets only the aliases for AWS managed keys.
```
$ aws kms list-aliases --query 'Aliases[?starts_with(AliasName, `alias/aws/`)]'
```
The following command gets only the `access-key` alias. The alias name is case-sensitive.
```
$ aws kms list-aliases --query 'Aliases[?AliasName==`alias/access-key`]'
[
{
"AliasName": "alias/access-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": "2018-01-20T15:23:10.194000-07:00",
"LastUpdatedDate": "2018-01-20T15:23:10.194000-07:00"
}
]
```
# Update aliases
Because an alias is an independent resource, you can change the KMS key associated with an alias. For example, if the `test-key` alias is associated with one KMS key, you can use the [UpdateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateAlias.html) operation to associate it with a different KMS key. This is one of several ways to [manually rotate a KMS key](rotate-keys.md) without changing its key material. You might also update a KMS key so that an application that was using one KMS key for new resources is now using a different KMS key.
You cannot update an alias in the AWS KMS console. Also, you cannot use `UpdateAlias` (or any other operation) to change an alias name. To change an alias name, delete the current alias and then create a new alias for the KMS key.
When you update an alias, the current KMS key and the new KMS key must be the same type (both symmetric or asymmetric or HMAC). They must also have the same key usage (`ENCRYPT_DECRYPT` or `SIGN_VERIFY` or GENERATE\$1VERIFY\$1MAC). This restriction prevents cryptographic errors in code that uses aliases.
The following example begins by using the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) operation to show that the `test-key` alias is currently associated with KMS key `1234abcd-12ab-34cd-56ef-1234567890ab`.
```
$ aws kms list-aliases --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
"Aliases": [
{
"AliasName": "alias/test-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/test-key",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1593622000.191,
"LastUpdatedDate": 1593622000.191
}
]
}
```
Next, it uses the `UpdateAlias` operation to change the KMS key that is associated with the `test-key` alias to KMS key `0987dcba-09fe-87dc-65ba-ab0987654321`. You don't need to specify the currently associated KMS key, only the new ("target") KMS key. The alias name is case sensitive.
```
$ aws kms update-alias --alias-name 'alias/test-key' --target-key-id 0987dcba-09fe-87dc-65ba-ab0987654321
```
To verify that the alias is now associated with the target KMS key, use the `ListAliases` operation again. This AWS CLI command uses the `--query` parameter to get only the `test-key` alias. The `TargetKeyId` and `LastUpdatedDate` fields are updated.
```
$ aws kms list-aliases --query 'Aliases[?AliasName==`alias/test-key`]'
[
{
"AliasName": "alias/test-key",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/test-key",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": 1593622000.191,
"LastUpdatedDate": 1604958290.154
}
]
```
# Delete an alias
You can delete an alias in the AWS KMS console or by using the [DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html) operation. Before deleting an alias, make sure that it's not in use. Although deleting an alias doesn't affect the associated KMS key, it might create problems for any application that uses the alias. If you delete an alias by mistake, you can create a new alias with the same name and associate it with the same or a different KMS key.
If you delete a KMS key, all aliases associated with that KMS key are deleted.
## Using the AWS KMS console
To delete an alias in the AWS KMS console, use the **Aliases** tab on the detail page for the KMS key. You can delete multiple aliases for a KMS key at one time.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**. You cannot manage aliases for AWS managed keys or AWS owned keys.
1. In the table, choose the key ID or alias of the KMS key. Then, on the KMS key detail page, choose the **Aliases** tab.
If a KMS key has multiple aliases, the **Aliases** column in the table displays one alias and an alias summary, such as **(\$1*n* more)**. Choosing the alias summary takes you directly to the **Aliases** tab on the KMS key detail page.
1. On the **Aliases** tab, select the check box next to the aliases that you want to delete. Then choose **Delete**.
## Using the AWS KMS API
To delete an alias, use the [DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html) operation. This operation deletes one alias at a time. The alias name is case-sensitive and it must be preceded by the `alias/` prefix.
For example, the following command deletes the `test-key` alias. This command does not return any output.
```
$ aws kms delete-alias --alias-name alias/test-key
```
To verify that the alias is deleted, use the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) operation. The following command uses the `--query` parameter in the AWS CLI to get only the `test-key` alias. The empty brackets in the response indicate that the `ListAliases` response didn't include a `test-key` alias. To eliminate the brackets, use the `--output text` parameter and value.
```
$ aws kms list-aliases --query 'Aliases[?AliasName==`alias/test-key`]'
[]
```
# 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](conditions-kms.md#conditions-kms-request-alias) and [kms:ResourceAliases](conditions-kms.md#conditions-kms-resource-aliases) condition keys. This feature is part of AWS KMS support for [attribute-based access control](abac.md) (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](iam-policies-best-practices.md). 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](key-policy-default.md#key-policy-default-allow-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](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/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](alias-ct.md) and [CloudWatch alarms](monitoring-cloudwatch.md) to alert you to alias changes that might affect access to your KMS keys. Also, the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) 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](conditions-kms.md#conditions-kms-request-alias) condition key in a [key policy](key-policies.md) or IAM policy. It applies to operations that use an alias to identify a KMS key in a request, namely [cryptographic operations](kms-cryptography.md#cryptographic-operations), [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), and [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html). It is not valid for alias operations, such as [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) or [DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html).
**Important**
A `Deny` policy statement with the `kms:RequestAlias` condition is not recommended because callers can bypass it by using the [key ID](concepts.md#key-id-key-id), [key ARN](concepts.md#key-id-key-ARN), or a different alias to identify the KMS key in the request. To deny access based on aliases associated with a KMS key, use the [kms:ResourceAliases](conditions-kms.md#conditions-kms-resource-aliases) condition key instead.
In the condition key, specify an [alias name](concepts.md#key-id-alias-name) or alias name pattern. You cannot specify an [alias ARN](concepts.md#key-id-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](concepts.md#key-id-key-id), a [key ARN](concepts.md#key-id-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](conditions-kms.md#conditions-kms-resource-aliases) 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`.
------
#### [ JSON ]
****
```
{
"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"
```
# Learn how to use aliases in your applications
You can use an alias to represent a KMS key in your application code. The `KeyId` parameter in AWS KMS [cryptographic operations](kms-cryptography.md#cryptographic-operations), [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), and [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) accepts an alias name or alias ARN.
For example, the following `GenerateDataKey` command uses an alias name (`alias/finance`) to identify a KMS key. The alias name is the value of the `KeyId` parameter.
```
$ aws kms generate-data-key --key-id alias/finance --key-spec AES_256
```
If the KMS key is in a different AWS account, you must use a key ARN or alias ARN in these operations. When using an alias ARN, remember that the alias for a KMS key is defined in the account that owns the KMS key and might differ in each Region. For help finding the alias ARN, see [Find the alias name and alias ARN for a KMS key](alias-view.md).
For example, the following `GenerateDataKey` command uses a KMS key that's not in the caller's account. The `ExampleAlias` alias is associated with the KMS key in the specified account and Region.
```
$ aws kms generate-data-key --key-id arn:aws:kms:us-west-2:444455556666:alias/ExampleAlias --key-spec AES_256
```
One of the most powerful uses of aliases is in applications that run in multiple AWS Regions. For example, you might have a global application that uses an RSA [asymmetric KMS key](symmetric-asymmetric.md) for signing and verification.
+ In US West (Oregon) (us-west-2), you want to use `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`.
+ In Europe (Frankfurt) (eu-central-1), you want to use `arn:aws:kms:eu-central-1:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321`
+ In Asia Pacific (Singapore) (ap-southeast-1), you want to use `arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d`.
You could create a different version of your application in each Region or use a dictionary or switch statement to select the right KMS key for each Region. But it's much easier to create an alias with the same alias name in each Region. Remember that the alias name is case-sensitive.
```
aws --region us-west-2 kms create-alias \
--alias-name alias/new-app \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
aws --region eu-central-1 kms create-alias \
--alias-name alias/new-app \
--key-id arn:aws:kms:eu-central-1:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321
aws --region ap-southeast-1 kms create-alias \
--alias-name alias/new-app \
--key-id arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
```
Then, use the alias in your code. When your code runs in each Region, the alias will refer to its associated KMS key in that Region. For example, this code calls the [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) operation with an alias name.
```
aws kms sign --key-id alias/new-app \
--message $message \
--message-type RAW \
--signing-algorithm RSASSA_PSS_SHA_384
```
However, there is a risk that the alias might be deleted or updated to be associated with a different KMS key. In that case, the application's attempts to verify signatures using the alias name will fail, and you might need to recreate or update the alias.
To mitigate this risk, be cautious about giving principals permission to manage the aliases that you use in your application. For details, see [Controlling access to aliases](alias-access.md).
There are several other solutions for applications that encrypt data in multiple AWS Regions, including the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/).
# Find aliases in AWS CloudTrail logs
You can use an alias to represent an AWS KMS key in an AWS KMS API operation. When you do, the alias and the key ARN of the KMS key are recorded in the AWS CloudTrail log entry for the event. The alias appears in the `requestParameters` field. The key ARN appears in the `resources` field. This is true even when an AWS service uses an AWS managed key in your account.
For example, the following [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) request uses the `project-key` alias to represent a KMS key.
```
$ aws kms generate-data-key --key-id alias/project-key --key-spec AES_256
```
When this request is recorded in the CloudTrail log, the log entry includes both the alias and the key ARN of the actual KMS key that was used.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "ABCDE",
"arn": "arn:aws:iam::111122223333:role/ProjectDev",
"accountId": "111122223333",
"accessKeyId": "FFHIJ",
"userName": "example-dev"
},
"eventTime": "2020-06-29T23:36:41Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKey",
"awsRegion": "us-west-2",
"sourceIPAddress": "205.205.123.000",
"userAgent": "aws-cli/1.18.89 Python/3.6.10 Linux/4.9.217-0.1.ac.205.84.332.metal1.x86_64 botocore/1.17.12",
"requestParameters": {
"keyId": "alias/project-key",
"keySpec": "AES_256"
},
"responseElements": null,
"requestID": "d93f57f5-d4c5-4bab-8139-5a1f7824a363",
"eventID": "d63001e2-dbc6-4aae-90cb-e5370aca7125",
"readOnly": true,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
],
"eventType": "AwsApiCall",
"recipientAccountId": "111122223333"
}
```
For details about logging AWS KMS operations in CloudTrail logs, see [Logging AWS KMS API calls with AWS CloudTrail](logging-using-cloudtrail.md).