Managing aliases - Amazon Key Management Service
Creating an aliasViewing aliasesUpdating aliasesDeleting an alias
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).

Managing aliases

Authorized users can create, view, and delete aliases. You can also update an alias, that is, associate an existing alias with a different KMS key.

Creating an alias

You can create aliases in the Amazon KMS console or by using Amazon KMS API operations.

The alias must be string of 1–256 characters. It can contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). The alias name for a customer managed key cannot begin with alias/aws/. The alias/aws/ prefix is reserved for Amazon 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.

Create an alias (console)

When you create a KMS key in the Amazon 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 Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys. You cannot manage aliases for Amazon managed keys or Amazon owned keys.

  4. 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 (+n more). Choosing the alias summary takes you directly to the Aliases tab on the KMS key detail page.

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

Create an alias (Amazon KMS API)

To create an alias, use the CreateAlias operation. Unlike the process of creating KMS keys in the console, the CreateKey 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 Amazon 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 operation. The alias name is case sensitive.

The TargetKeyId can be any customer managed key in the same Amazon Web Services Region. To identify the KMS key, use its key ID or 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 Amazon Command Line Interface (Amazon CLI). For examples in multiple programming languages, see Working with aliases.

$ 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 Viewing aliases (Amazon KMS API).

Viewing aliases

Aliases make it easy to recognize KMS keys in the Amazon KMS console. You can view the aliases for a KMS key in the Amazon KMS console or by using the ListAliases operation. The DescribeKey operation, which returns the properties of a KMS key, does not include aliases.

Viewing aliases (console)

The Customer managed keys and Amazon managed keys pages in the Amazon KMS console display the alias associated with each KMS key. You can also search, sort, and filter KMS keys based on their aliases.

The following image of the Amazon KMS console shows the aliases on the Customer managed keys page of an example account. As shown in the image, some KMS keys do not have an alias.

When a KMS key has multiple aliases, the Aliases column displays one alias and an alias summary (+n more). The alias summary shows how many additional aliases are associated with the KMS key and links to the display of all aliases for the KMS key on the Aliases tab.

Aliases in the Customer managed keys page of the Amazon KMS console

The Aliases tab on the details page for each KMS key displays the alias name and alias ARN of all aliases for the KMS key in the Amazon Web Services account and Region. You can also use the Aliases tab to create aliases and delete aliases.

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 (+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.

The following image shows the Aliases tab for an example KMS key.

You can use the alias to recognize an Amazon managed key, as shown in this example Amazon managed keys page. The aliases for Amazon managed keys always have the format: aws/<service-name>. For example, the alias for the Amazon managed key for Amazon DynamoDB is aws/dynamodb.

Aliases in the Amazon managed keys page of the Amazon KMS console

Viewing aliases (Amazon KMS API)

The ListAliases operation returns the alias name and alias ARN of aliases in the account and Region. The output includes aliases for Amazon managed keys and for customer managed keys. The aliases for Amazon managed keys have the format aws/<service-name>, such as aws/dynamodb.

The response might also include aliases that have no TargetKeyId field. These are predefined aliases that Amazon 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 or 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 Amazon CLI command gets only the aliases for Amazon 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"
    }
]

Updating 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 operation to associate it with a different KMS key. This is one of several ways to manually rotate a KMS key 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 Amazon 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_VERIFY_MAC). This restriction prevents cryptographic errors in code that uses aliases.

The following example begins by using the ListAliases 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 Amazon 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
    }
]

Deleting an alias

You can delete an alias in the Amazon KMS console or by using the DeleteAlias 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.

Delete aliases (console)

To delete an alias in the Amazon 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 Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys. You cannot manage aliases for Amazon managed keys or Amazon owned keys.

  4. 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 (+n more). Choosing the alias summary takes you directly to the Aliases tab on the KMS key detail page.

  5. On the Aliases tab, select the check box next to the aliases that you want to delete. Then choose Delete.

Delete an alias (Amazon KMS API)

To delete an alias, use the DeleteAlias 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 operation. The following command uses the --query parameter in the Amazon 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`]'
[]