Creating an alias Listing aliases Updating an alias Deleting an alias

Working with aliases

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

Topics

Creating an alias
Listing aliases
Updating an alias
Deleting an alias

Creating an alias

When you create an AWS KMS key in the AWS 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 AWS managed keys.

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

Java

For details, see the createAlias method in the AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS 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 AWS created and associated with your AWS managed keys. 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.

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

Java

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


// List the aliases in this AWS account
//
Integer limit = 10;

ListAliasesRequest req = new ListAliasesRequest().withLimit(limit);
ListAliasesResult result = kmsClient.listAliases(req);

C#

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


// List the aliases in this AWS 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 AWS SDK for Python (Boto3).


# List the aliases in this AWS account

response = kms_client.list_aliases(
    Limit=10
)

Ruby

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


# List the aliases in this AWS account

response = kmsClient.list_aliases({
  limit: 10
})

PHP

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


// List the aliases in this AWS account
//
$limit = 10;

$result = $KmsClient->listAliases([
    'Limit' => $limit,
]);

Node.js

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


// List the aliases in this AWS 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 AWS Tools for PowerShell, see Output Pagination with AWS Tools for PowerShell.


# List the aliases in this AWS account
$limit = 10

$result = Get-KMSAliasList | Select-Object -First $limit

To use the AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS 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 AWS KMS client object that you created in Creating a client.

Java

For details about the Java implementation, see the updateAlias method in the AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS 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 AWS KMS client object that you created in Creating a client.

Java

For details, see the deleteAlias method in the AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the AWS Tools for Windows PowerShell User Guide.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Working with keys

Encrypting and decrypting data keys