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.