Working with aliases - Amazon Key Management Service
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).

Working with aliases

The examples in this topic use the Amazon KMS API to create, view, update, and delete aliases. For information about aliases, see Using aliases.

Creating an alias

When you create an Amazon KMS key in the Amazon Web Services Management Console, you must create an alias for it. However, the CreateKey operation that creates a KMS key does not create an alias.

To create an alias, use the CreateAlias operation. The alias must be unique in the account and Region. You cannot create an alias that begins with aws/. The aws/ prefix is reserved by Amazon Web Services for Amazon managed keys.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

Java

For details, see the createAlias method in the Amazon SDK for Java API Reference.

// Create an alias for a KMS key // String aliasName = "alias/projectKey1"; // Replace the following example key ARN with a valid key ID or key ARN String targetKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; CreateAliasRequest req = new CreateAliasRequest().withAliasName(aliasName).withTargetKeyId(targetKeyId); kmsClient.createAlias(req);
C#

For details, see the CreateAlias method in the Amazon SDK for .NET.

// Create an alias for a KMS key // String aliasName = "alias/projectKey1"; // Replace the following example key ARN with a valid key ID or key ARN String targetKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; CreateAliasRequest createAliasRequest = new CreateAliasRequest() { AliasName = aliasName, TargetKeyId = targetKeyId }; kmsClient.CreateAlias(createAliasRequest);
Python

For details, see the create_alias method in the Amazon SDK for Python (Boto3).

# Create an alias for a KMS key alias_name = 'alias/projectKey1' # Replace the following example key ARN with a valid key ID or key ARN target_key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.create_alias( AliasName=alias_name, TargetKeyId=key_id )
Ruby

For details, see the create_alias instance method in the Amazon SDK for Ruby.

# Create an alias for a KMS key alias_name = 'alias/projectKey1' # Replace the following example key ARN with a valid key ID or key ARN target_key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.create_alias({ alias_name: alias_name, target_key_id: target_key_id })
PHP

For details, see the CreateAlias method in the Amazon SDK for PHP.

// Create an alias for a KMS key // $aliasName = "alias/projectKey1"; // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $result = $KmsClient->createAlias([ 'AliasName' => $aliasName, 'TargetKeyId' => $keyId, ]);
Node.js

For details, see the createAlias property in the Amazon SDK for JavaScript in Node.js.

// Create an alias for a KMS key // const AliasName = 'alias/projectKey1'; // Replace the following example key ARN with a valid key ID or key ARN const TargetKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; kmsClient.createAlias({ AliasName, TargetKeyId }, (err, data) => { ... });
PowerShell

To create an alias, use the New-KMSAlias cmdlet. The alias name is case-sensitive.

# Create an alias for a KMS key $aliasName = 'alias/projectKey1' # Replace the following example key ARN with a valid key ID or key ARN $targetKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' New-KMSAlias -TargetKeyId $targetKeyId -AliasName $aliasName

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Listing aliases

To list aliases in the account and region, use the ListAliases operation.

By default, the ListAliases command returns all aliases in the account and Region. This includes aliases that you created and associated with your customer managed keys, and aliases that Amazon created and associated with your Amazon managed keys. 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.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

Java

For details about the Java implementation, see the listAliases method in the Amazon SDK for Java API Reference.

// List the aliases in this Amazon Web Services account // Integer limit = 10; ListAliasesRequest req = new ListAliasesRequest().withLimit(limit); ListAliasesResult result = kmsClient.listAliases(req);
C#

For details, see the ListAliases method in the Amazon SDK for .NET.

// List the aliases in this Amazon Web Services account // int limit = 10; ListAliasesRequest listAliasesRequest = new ListAliasesRequest() { Limit = limit }; ListAliasesResponse listAliasesResponse = kmsClient.ListAliases(listAliasesRequest);
Python

For details, see the list_aliases method in the Amazon SDK for Python (Boto3).

# List the aliases in this Amazon Web Services account response = kms_client.list_aliases( Limit=10 )
Ruby

For details, see the list_aliases instance method in the Amazon SDK for Ruby.

# List the aliases in this Amazon Web Services account response = kmsClient.list_aliases({ limit: 10 })
PHP

For details, see the List Aliases method in the Amazon SDK for PHP.

// List the aliases in this Amazon Web Services account // $limit = 10; $result = $KmsClient->listAliases([ 'Limit' => $limit, ]);
Node.js

For details, see the listAliases property in the Amazon SDK for JavaScript in Node.js.

// List the aliases in this Amazon Web Services account // const Limit = 10; kmsClient.listAliases({ Limit }, (err, data) => { ... });
PowerShell

To list the aliases in the account and Region, use the Get-KMSAliasList cmdlet.

To limit the number of output objects, this example uses the Select-Object cmdlet, instead of the Limit parameter, which is being deprecated in list cmdlets. For help with paginating output in Amazon Tools for PowerShell, see Output Pagination with Amazon Tools for PowerShell.

# List the aliases in this Amazon Web Services account $limit = 10 $result = Get-KMSAliasList | Select-Object -First $limit

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

To list only the aliases that are associated with a particular KMS key, use the KeyId parameter. Its value can be the key ID or key ARN of any KMS key in the region. You cannot specify an alias name or alias ARN.

Java

For details about the Java implementation, see the listAliases method in the Amazon SDK for Java API Reference.

// List the aliases for one KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; ListAliasesRequest req = new ListAliasesRequest().withKeyId(keyId); ListAliasesResult result = kmsClient.listAliases(req);
C#

For details, see the ListAliases method in the Amazon SDK for .NET.

// List the aliases for one KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; ListAliasesRequest listAliasesRequest = new ListAliasesRequest() { KeyId = keyId }; ListAliasesResponse listAliasesResponse = kmsClient.ListAliases(listAliasesRequest);
Python

For details, see the list_aliases method in the Amazon SDK for Python (Boto3).

# List the aliases for one KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.list_aliases( KeyId=key_id )
Ruby

For details, see the list_aliases instance method in the Amazon SDK for Ruby.

# List the aliases for one KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.list_aliases({ key_id: key_id })
PHP

For details, see the List Aliases method in the Amazon SDK for PHP.

// List the aliases for one KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $result = $KmsClient->listAliases([ 'KeyId' => $keyId, ]);
Node.js

For details, see the listAliases property in the Amazon SDK for JavaScript in Node.js.

// List the aliases for one KMS key // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; kmsClient.listAliases({ KeyId }, (err, data) => { ... });
PowerShell

To list the aliases for a KMS key, use the KeyId parameter of the Get-KMSAliasList cmdlet.

# List the aliases for one KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $response = Get-KmsAliasList -KeyId $keyId

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Updating an alias

To associate an existing alias with a different KMS key, use the UpdateAlias operation.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

Java

For details about the Java implementation, see the updateAlias method in the Amazon SDK for Java API Reference.

// Updating an alias // String aliasName = "alias/projectKey1"; // Replace the following example key ARN with a valid key ID or key ARN String targetKeyId = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"; UpdateAliasRequest req = new UpdateAliasRequest() .withAliasName(aliasName) .withTargetKeyId(targetKeyId); kmsClient.updateAlias(req);
C#

For details, see the UpdateAlias method in the Amazon SDK for .NET.

// Updating an alias // String aliasName = "alias/projectKey1"; // Replace the following example key ARN with a valid key ID or key ARN String targetKeyId = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"; UpdateAliasRequest updateAliasRequest = new UpdateAliasRequest() { AliasName = aliasName, TargetKeyId = targetKeyId }; kmsClient.UpdateAlias(updateAliasRequest);
Python

For details, see the update_alias method in the Amazon SDK for Python (Boto3).

# Updating an alias alias_name = 'alias/projectKey1' # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321' response = kms_client.update_alias( AliasName=alias_name, TargetKeyID=key_id )
Ruby

For details, see the update_alias instance method in the Amazon SDK for Ruby.

# Updating an alias alias_name = 'alias/projectKey1' # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321' response = kmsClient.update_alias({ alias_name: alias_name, target_key_id: key_id })
PHP

For details, see the UpdateAlias method in the Amazon SDK for PHP.

// Updating an alias // $aliasName = "alias/projectKey1"; // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'; $result = $KmsClient->updateAlias([ 'AliasName' => $aliasName, 'TargetKeyId' => $keyId, ]);
Node.js

For details, see the updateAlias property in the Amazon SDK for JavaScript in Node.js.

// Updating an alias // const AliasName = 'alias/projectKey1'; // Replace the following example key ARN with a valid key ID or key ARN const TargetKeyId = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'; kmsClient.updateAlias({ AliasName, TargetKeyId }, (err, data) => { ... });
PowerShell

To change the KMS key that is associated with an alias, use the Update-KMSAlias cmdlet. The alias name is case-sensitive.

The Update-KMSAlias cmdlet does not return any output. To verify that the command worked, use the Get-KMSAliasList cmdlet.

# Updating an alias $aliasName = 'alias/projectKey1' # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321' Update-KMSAlias -AliasName $aliasName -TargetKeyID $keyId

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Deleting an alias

To delete an alias, use the DeleteAlias operation. Deleting an alias has no effect on the associated KMS key.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

Java

For details, see the deleteAlias method in the Amazon SDK for Java API Reference.

// Delete an alias for a KMS key // String aliasName = "alias/projectKey1"; DeleteAliasRequest req = new DeleteAliasRequest().withAliasName(aliasName); kmsClient.deleteAlias(req);
C#

For details, see the DeleteAlias method in the Amazon SDK for .NET.

// Delete an alias for a KMS key // String aliasName = "alias/projectKey1"; DeleteAliasRequest deleteAliasRequest = new DeleteAliasRequest() { AliasName = aliasName }; kmsClient.DeleteAlias(deleteAliasRequest);
Python

For details, see the delete_alias method in the Amazon SDK for Python (Boto3).

# Delete an alias for a KMS key alias_name = 'alias/projectKey1' response = kms_client.delete_alias( AliasName=alias_name )
Ruby

For details, see the delete_alias instance method in the Amazon SDK for Ruby.

# Delete an alias for a KMS key alias_name = 'alias/projectKey1' response = kmsClient.delete_alias({ alias_name: alias_name })
PHP

For details, see the DeleteAlias method in the Amazon SDK for PHP.

// Delete an alias for a KMS key // $aliasName = "alias/projectKey1"; $result = $KmsClient->deleteAlias([ 'AliasName' => $aliasName, ]);
Node.js

For details, see the deleteAlias property) in the Amazon SDK for JavaScript in Node.js.

// Delete an alias for a KMS key // const AliasName = 'alias/projectKey1'; kmsClient.deleteAlias({ AliasName }, (err, data) => { ... });
PowerShell

To delete an alias, use the Remove-KMSAlias cmdlet. The alias name is case-sensitive.

Because this cmdlet permanently deletes the alias, PowerShell prompts you to confirm the command. The ConfirmImpact is High, so you cannot use a ConfirmPreference to suppress this prompt. If you must suppress the confirmation prompt, add the Confirm common parameter with a value of $false, for example: -Confirm:$false.

The Remove-KMSAlias cmdlet doesn't return any output. To verify that the command was effective, use the Get-KMSAliasList cmdlet.

# Delete an alias for a KMS key $aliasName = 'alias/projectKey1' Remove-KMSAlias -AliasName $aliasName

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.