AWS Key Management Service
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用别名

本主题中的示例使用 AWS KMS API 创建、查看、更新和删除别名。

别名客户主密钥 (CMK) 的可选显示名称。每个 CMK 都可以有多个别名,但每个别名仅指向一个 CMK。别名名称在 AWS 账户和所在区域中必须是唯一的。为简化在多个区域中运行的代码,您可以使用相同的别名名称,但需要使其指向每个区域中不同的 CMK。

您可以使用 AWS KMS API 操作来列出、创建和删除别名。您也可以更新别名,将现有别名与其他 CMK 相关联。没有编辑或更改别名名称的操作。如果您为已有别名的 CMK 创建别名,该操作为同一 CMK 创建另一个别名。要更改别名名称,请删除当前别名,然后为 CMK 创建新的别名。

由于别名不是 CMK 的属性,它可以与现有 CMK 关联和取消关联,而无需更改 CMK 的属性。删除别名不会删除底层 CMK。

您只能在以下操作中将别名用作 KeyId 参数的值:

  • DescribeKey

  • Encrypt

  • GenerateDataKey

  • GenerateDataKeyWithoutPlaintext

  • ReEncrypt

别名在 AWS 账户中创建,只能供创建它们的账户使用。您不能使用别名名称或别名 ARN 来识别不同 AWS 账户中的 CMK。

要指定别名,请使用别名名称或别名 ARN,如以下示例所示。在这两种情况下,请确保在别名名称前加上 "alias/"

// Fully specified ARN arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias

创建别名

要创建别名,请使用 CreateAlias 操作。别名在账户和所在区域中必须是唯一的。如果您为已有别名的 CMK 创建别名,CreateAlias 会为同一 CMK 创建另一个别名。它不会替换现有别名。

您无法创建以 aws/ 开头的别名。aws/ 前缀由 Amazon Web Services 保留用于 AWS 托管 CMK

此示例使用您在AWS KMS中创建的 创建客户端 客户端对象。

JavaC#PythonRubyPHPNode.js
Java

有关详细信息,请参阅 AWS SDK for Java API Reference 中的 createAlias 方法

// Create an alias for a CMK // String aliasName = "alias/projectKey1"; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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#

有关详细信息,请参阅 适用于 .NET 的 AWS 开发工具包 中的 CreateAlias 方法

// Create an alias for a CMK // String aliasName = "alias/projectKey1"; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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

有关详细信息,请参阅 适用于 Python 的 AWS 开发工具包 (Boto3) 中的 create_alias 方法

# Create an alias for a CMK alias_name = 'alias/projectKey1' # 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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

有关详细信息,请参阅 适用于 Ruby 的 AWS 开发工具包 中的 create_alias 实例方法。

# Create an alias for a CMK aliasName = 'alias/projectKey1' # 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN targetKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.create_alias({ alias_name: aliasName, target_key_id: targetKeyId })
PHP

有关详细信息,请参阅 适用于 PHP 的 AWS 开发工具包 中的 CreateAlias 方法

// Create an alias for a CMK // $aliasName = "alias/projectKey1"; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $result = $KmsClient->createAlias([ 'AliasName' => $aliasName, 'TargetKeyId' => $keyId, ]);
Node.js

有关详细信息,请参阅 AWS SDK for JavaScript in Node.js 中的 createAlias 属性

// Create an alias for a CMK // const AliasName = 'alias/projectKey1'; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN const TargetKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; kmsClient.createAlias({ AliasName, TargetKeyId }, (err, data) => { ... });

列出别名

要列出账户和区域中的别名,请使用 ListAliases 操作。

默认情况下,ListAliases 命令会返回账户和区域中的所有别名。这包括您创建并与您的客户托管 CMK 关联的别名,以及 AWS 创建并与您的 AWS 托管 CMK 关联的别名。该响应可能还包括没有 TargetKeyId 字段的别名。这些是 AWS 已创建但尚未与 CMK 关联的预定义别名。

此示例使用您在AWS KMS中创建的 创建客户端 客户端对象。

JavaC#PythonRubyPHPNode.js
Java

有关 Java 实施的详细信息,请参阅 AWS SDK for Java API Reference 中的 listAliases 方法

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

有关详细信息,请参阅 适用于 .NET 的 AWS 开发工具包 中的 ListAliases 方法

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

有关详细信息,请参阅 适用于 Python 的 AWS 开发工具包 (Boto3) 中的 list_aliases 方法

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

有关详细信息,请参阅 适用于 Ruby 的 AWS 开发工具包 中的 list_aliases 实例方法。

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

有关详细信息,请参阅 适用于 PHP 的 AWS 开发工具包 中的 List Aliases 方法

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

有关详细信息,请参阅 AWS SDK for JavaScript in Node.js 中的 listAliases 属性

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

要仅列出与特定 CMK 关联的别名,请使用 KeyId 参数。其值可以是区域中任何 CMK 的 ID 或 Amazon 资源名称 (ARN)。您不能指定别名名称或别名 ARN。

JavaC#PythonRubyPHPNode.js
Java

有关 Java 实施的详细信息,请参阅 AWS SDK for Java API Reference 中的 listAliases 方法

// List the aliases for one CMK // // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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#

有关详细信息,请参阅 适用于 .NET 的 AWS 开发工具包 中的 ListAliases 方法

// List the aliases for one CMK // // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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

有关详细信息,请参阅 适用于 Python 的 AWS 开发工具包 (Boto3) 中的 list_aliases 方法

# List the aliases for one CMK # 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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

有关详细信息,请参阅 适用于 Ruby 的 AWS 开发工具包 中的 list_aliases 实例方法。

# List the aliases for one CMK # 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.list_aliases({ key_id: keyId })
PHP

有关详细信息,请参阅 适用于 PHP 的 AWS 开发工具包 中的 List Aliases 方法

// List the aliases for one CMK // // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $result = $KmsClient->listAliases([ 'KeyId' => $keyId, ]);
Node.js

有关详细信息,请参阅 AWS SDK for JavaScript in Node.js 中的 listAliases 属性

// List the aliases for one CMK // // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; kmsClient.listAliases({ KeyId }, (err, data) => { ... });

更新别名

要将现有别名与其他 CMK 关联,请使用 UpdateAlias 操作。

此示例使用您在AWS KMS中创建的 创建客户端 客户端对象。

JavaC#PythonRubyPHPNode.js
Java

有关 Java 实施的详细信息,请参阅 AWS SDK for Java API Reference 中的 updateAlias 方法

// Updating an alias // String aliasName = "alias/projectKey1"; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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#

有关详细信息,请参阅 适用于 .NET 的 AWS 开发工具包 中的 UpdateAlias 方法

// Updating an alias // String aliasName = "alias/projectKey1"; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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

有关详细信息,请参阅 适用于 Python 的 AWS 开发工具包 (Boto3) 中的 update_alias 方法

# Updating an alias alias_name = 'alias/projectKey1' # 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK 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

有关详细信息,请参阅 适用于 Ruby 的 AWS 开发工具包 中的 update_alias 实例方法。

# Updating an alias aliasName = 'alias/projectKey1' # 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN keyId = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321' response = kmsClient.update_alias({ alias_name: aliasName, target_key_id: keyId })
PHP

有关详细信息,请参阅 适用于 PHP 的 AWS 开发工具包 中的 UpdateAlias 方法

// Updating an alias // $aliasName = "alias/projectKey1"; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'; $result = $KmsClient->updateAlias([ 'AliasName' => $aliasName, 'TargetKeyId' => $keyId, ]);
Node.js

有关详细信息,请参阅 AWS SDK for JavaScript in Node.js 中的 updateAlias 属性

// Updating an alias // const AliasName = 'alias/projectKey1'; // 使用有效的 CMK ID 或 ARN 替换以下虚拟 CMK ARN const TargetKeyId = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'; kmsClient.updateAlias({ AliasName, TargetKeyId }, (err, data) => { ... });

删除别名

要删除别名,请使用 DeleteAlias 操作。删除别名不会影响底层 CMK。

此示例使用您在AWS KMS中创建的 创建客户端 客户端对象。

JavaC#PythonRubyPHPNode.js
Java

有关详细信息,请参阅 AWS SDK for Java API Reference 中的 deleteAlias 方法

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

有关详细信息,请参阅 适用于 .NET 的 AWS 开发工具包 中的 DeleteAlias 方法

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

有关详细信息,请参阅 适用于 Python 的 AWS 开发工具包 (Boto3) 中的 delete_alias 方法

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

有关详细信息,请参阅 适用于 Ruby 的 AWS 开发工具包 中的 delete_alias 实例方法。

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

有关详细信息,请参阅 适用于 PHP 的 AWS 开发工具包 中的 DeleteAlias 方法

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

有关详细信息,请参阅 AWS SDK for JavaScript in Node.js 中的 deleteAlias 属性

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