AWS Key Management Service Adds Support for Updating Key Aliases

August 31, 2021: AWS KMS is replacing the term customer master key (CMK) with AWS KMS key and KMS key. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term. More info.

In November 2014, AWS launched Key Management Service (KMS), a managed service that makes it easy for you to create and control the encryption keys used to encrypt your data managed by AWS services and within your own applications. One of the features KMS offers is the key alias, an arbitrary string that can be associated with a cryptographic key in a region.

In this blog post, Anders Joergensen, a KMS developer, explains the ways in which you can use key aliases and describes the new UpdateAlias API we’ve launched to allow you to update the association of a key alias from one key to another within a region.

Key aliases are useful in three ways when using KMS:

1. You can manage keys by using human readable display names instead of relying on a 32-character key ID for each key. A key with an alias of CriticalDataKey is easier to identify in a returned list than 12345678-1234-1234-1234-123456789012.
2. You can refer to a key in your applications that operate cross-region by using a single key alias rather than using the regionally specific key ID. This lets you deploy and manage the same application code to multiple regions, potentially minimizing errors in your deployments.
3. You can effectively rotate an AWS KMS key in KMS by changing the mapping of a key alias to a different key. Future Encrypt API calls using a given alias will be performed under the new key ID. Ciphertexts previously encrypted under the same alias with a previous key ID can still be decrypted because the required key ID is included in the ciphertext. This prevents you from having to keep track of which key ID was used when for encryption operations.

Use of aliases for key rotation differs from the built-in automatic annual rotation method available in KMS today. With automatic annual rotation, the key ID and any associated aliases stay the same—only the underlying key material version changes.

Before today, customers who wanted to perform manual rotation using aliases needed to separately delete the key alias and recreate it, mapping it to a different key. This left the alias unusable for a brief period of time between the time when the alias was deleted and when it was recreated and mapped to the new key. The introduction of the UpdateAlias API simplifies this letting you change the mapping of an alias safely to a different key with one API call.

Usage example

In this example we will assume you have the alias CriticalDataKey in your account 123456789012 that maps to a key ID of 87654321-4321-4321-4321-210987654321 in the us-east-1 region. You want to update this alias to map to a new key in your account with key ID 12345678-1234-1234-1234-123456789012. The UpdateAliasRequest type requires you to specify the name of the alias to update and the target key ID, either as a key ID or as the full Amazon Resource Name (ARN), as shown in the following example. You do not have to define the current key ID to which the alias is mapped; you have to define only the target key ID. The UpdateAlias call doesn’t return a result; however, you can call the ListAliases API to see evidence that the CriticalDataKey alias is in fact now mapped to key ID 12345678-1234-1234-1234-123456789012. In the following example, we assume you have instantiated an AWSKMSClient in the AWS SDK as kms.

String aliasName = "alias/CriticalDataKey";	
String targetKeyId = "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012";
 
UpdateAliasRequest updateAliasRequest =
new UpdateAliasRequest().withAliasName(aliasName).withTargetKeyId(targetKeyId);
 
kms.updateAlias(updateAliasRequest);

To verify that the alias-to-key ID mapping happened, you can call ListAliases.

ListAliasesRequest listAliasesRequest = new ListAliasesRequest();
kms.listAliases(listAliasesRequest);

The following is the response syntax.

{
    "Aliases": [
        {
            "AliasArn": "arn:aws:kms:us-east-1:123456789012:alias/CriticalDataKey",
            "AliasName": "CriticalDataKey",
            "TargetKeyId": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
        }
    ]
}

It might take a moment for the update to show due to eventual consistency.

If your application relied on the CriticalDataKey in multiple regions, you would need to make the UpdateAlias call in each region to remap the alias to a new key. Note that the 32-character key ID is unique in each region, so the syntax of your UpdateAlias call will change from region to region in order to reflect the uniqueness of the key ID.

If you have questions about using the UpdateAlias API or any other questions about KMS, please post them on the KMS Forum.

– Anders