Menu
AWS Key Management Service
Developer Guide

Working with Aliases

This topic discusses how to create, delete, and update an alias.

An alias is a display name for a key. It can be used in place of a KeyId for the following operations:

  • DescribeKey

  • Encrypt

  • GenerateDataKey

  • GenerateDataKeyWithoutPlaintext

  • ListKeyPolicies

  • ReEncrypt

You can use a full ARN to specify an alias or just the alias name as shown in the following example. If you use the alias name, be sure to prepend "alias/" to it.

Copy
// Fully specified ARN arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias // Alias name (prefixed with "alias/") alias/ExampleAlias

An alias is not a property of a key, and therefore can be associated with and disassociated from an existing key without changing the properties of the key. Deleting an alias does not delete the underlying key.

Creating an Alias

Call the CreateAlias function to create an alias. The alias should be unique.

Copy
// Creating an alias // // Input Parameters: // The function takes two parameters. // AliasName - String that contains a display name for a key. This is of the format // "alias/[a-zA-Z0-9/_-]+". That is, the alias name can be an alphanumeric // value and contain an underscore or a dash. Alias names that begin with // "alias/aws..." are reserved for AWS use. // TargetKeyId - Unique key identifier of the key to which the display name will // be associated // // Return Values: // The function does not return a value. // String aliasName = "alias/projectKey1"; String targetKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; CreateAliasRequest req = new CreateAliasRequest().withAliasName(aliasName).withTargetKeyId(targetKeyId); kms.createAlias(req);

Deleting an Alias

Call the DeleteAlias function to delete an alias.

Copy
// Deleting an alias // // Input Parameters: // The function takes one parameter. // AliasName - String that contains a display name for a key // // Return Values: // The function does not return a value. // String aliasName = "alias/projectKey1"; DeleteAliasRequest req = new DeleteAliasRequest().withAliasName(aliasName); kms.deleteAlias(req);

Listing Aliases

Call the ListAliases function to list all of the key aliases for your account.

Copy
// Listing aliases // // Input Parameters: // The function takes three parameters. // Limit - Specify this parameter only when paginating results to indicate the // maximum number of aliases you want listed in the response. If there are // additional aliases beyond the maximum you specify, the Truncated // response element will be set to true. // Marker - Use this parameter only when paginating results, and only in a subsequent // request after you've received a response where the results are truncated. // Set it to the value of the NextMarker in the response you // just received. // // Return Values: // The function returns a list of aliases for the keys in your account. // Integer limit = 10; ListAliasesRequest req = new ListAliasesRequest().withLimit(limit); ListAliasesResult result = kms.listAliases(req);

Updating an Alias

Call the UpdateAlias function to associate an alias with a different key.

Copy
// Updating an alias // // Input Parameters: // The function takes two parameters. // AliasName - String that contains the name of the alias to be modified. An alias name can // contain only alphanumeric characters, forward slashes, underscores, and dashes. // An alias must start with the word "alias" followed by a forward slash (alias/). // An alias that begins with "aws" after the forward slash is reserved by // Amazon Web Services (AWS). // TargetKeyId - Unique identifier of the customer master key to be associated with the alias. // This value can be a globally unique identifier or the fully specified ARN of // a key. // // Return Values: // The function does not return a value. // String aliasName = "alias/projectKey1"; String targetKeyId = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"; UpdateAliasRequest req = new UpdateAliasRequest() .withAliasName(aliasName) .withTargetKeyId(targetKeyId); kms.updateAlias(req);