文档 AWS SDK 示例 GitHub 存储库中还有更多 [S AWS DK 示例](https://github.com/awsdocs/aws-doc-sdk-examples)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS KMS 使用示例 AWS CLI
以下代码示例向您展示了如何使用with来执行操作和实现常见场景 AWS KMS。 AWS Command Line Interface
*操作*是大型程序的代码摘录，必须在上下文中运行。您可以通过操作了解如何调用单个服务函数，还可以通过函数相关场景的上下文查看操作。
每个示例都包含一个指向完整源代码的链接，您可以从中找到有关如何在上下文中设置和运行代码的说明。
**Topics**
+ [操作](#actions)
## 操作
### `cancel-key-deletion`
以下代码示例演示了如何使用 `cancel-key-deletion`。
**AWS CLI**
**取消对客户托管的 KMS 密钥的预定删除**
以下 `cancel-key-deletion` 示例取消对客户托管的 KMS 密钥的预定删除。
```
aws kms cancel-key-deletion \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
`cancel-key-deletion` 命令成功后，预定的删除即被取消。但是，KMS 密钥的密钥状态为 `Disabled`，因此您不能在加密操作中使用该 KMS 密钥。要恢复其功能，请使用 `enable-key` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[预定和取消密钥删除](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html#deleting-keys-scheduling-key-deletion)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[CancelKeyDeletion](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/cancel-key-deletion.html)*中的。
### `connect-custom-key-store`
以下代码示例演示了如何使用 `connect-custom-key-store`。
**AWS CLI**
**连接自定义密钥存储**
以下 `connect-custom-key-store` 示例重新连接指定的自定义密钥存储。您可以使用这样的命令首次连接自定义密钥存储，或重新连接已断连的密钥存储。
您可以使用此命令连接 AWS CloudHSM 密钥存储库或外部密钥存储库。
```
aws kms connect-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
此命令不返回任何输出。要验证命令是否有效，请使用 `describe-custom-key-stores` 命令。
*有关连接 AWS CloudHSM 密钥库的信息，[请参阅《密钥管理服务开发者指南》中的连接和断开 AWS CloudHSM 密钥存储库的连接](https://docs.aws.amazon.com/kms/latest/developerguide/disconnect-keystore.html)。AWS *
有关连接外部密钥存储的信息，请参阅《AWS 密钥管理服务开发人员指南》中的[连接和断开连接外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/xks-connect-disconnect.html)。**
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ConnectCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/connect-custom-key-store.html)*中的。
### `create-alias`
以下代码示例演示了如何使用 `create-alias`。
**AWS CLI**
**为 KMS 密钥创建别名**
以下 `create-alias` 命令为由密钥 ID `1234abcd-12ab-34cd-56ef-1234567890ab` 标识的 KMS 密钥创建名为 `example-alias` 的别名。
别名名称必须以 `alias/` 开头。请勿使用以开头的别名`alias/aws`；这些别名是保留给使用的 AWS。
```
aws kms create-alias \
--alias-name alias/example-alias \
--target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
此命令不返回任何输出。要查看新别名，请使用 `list-aliases` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[使用别名](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[CreateAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-alias.html)*中的。
### `create-custom-key-store`
以下代码示例演示了如何使用 `create-custom-key-store`。
**AWS CLI**
**示例 1：创建 AWS CloudHSM 密钥存储库**
以下`create-custom-key-store`示例使用所需参数创建由 AWS CloudHSM 集群支持的 C AWS loudHSM 密钥存储库。您也可以添加 `custom-key-store-type``parameter with the default value: ``AWS_CLOUDHSM`。
要在 AWS CLI 中为`trust-anchor-certificate`命令指定文件输入，需要`file://`使用前缀。
```
aws kms create-custom-key-store \
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate file://customerCA.crt
```
输出：
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
有关更多信息，请参阅《密钥*管理服务[开发者 AWS 指南》中的AWS 创建 CloudHSM 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html)*存储。
**示例 2：创建使用公有端点连接的外部密钥存储**
以下`create-custom-key-store`示例创建了通过互联网与 AWS KMS 通信的外部密钥存储库 (XKS)。
在此示例中，`XksProxyUriPath` 使用可选前缀 `example-prefix`。
注意：如果您使用的是 AWS CLI 版本 1.0，请在指定带有 HTTP 或 HTTPS 值的参数（例如 XksProxyUriEndpoint 参数）之前运行以下命令。
```
aws configure set cli_follow_urlparam false
```
否则， AWS CLI 版本 1.0 会将参数值替换为在该 URI 地址中找到的内容。
```
aws kms create-custom-key-store \
--custom-key-store-name ExamplePublicEndpointXKS \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity PUBLIC_ENDPOINT \
--xks-proxy-uri-endpoint "https://myproxy.xks.example.com" \
--xks-proxy-uri-path "/example-prefix/kms/xks/v1" \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
输出：
```
{
"CustomKeyStoreId": cks-2234567890abcdef0
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[创建外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystorecreate-xks-keystore.html)。
**示例 3：创建使用 VPC 端点服务连接的外部密钥存储**
以下`create-custom-key-store`示例创建了使用 Amazon VPC 终端节点服务与 KMS 通信的外部密钥存储 (X AWS KS)。
注意：如果您使用的是 AWS CLI 版本 1.0，请在指定带有 HTTP 或 HTTPS 值的参数（例如 XksProxyUriEndpoint 参数）之前运行以下命令。
```
aws configure set cli_follow_urlparam false
```
否则， AWS CLI 版本 1.0 会将参数值替换为在该 URI 地址中找到的内容。
```
aws kms create-custom-key-store \
--custom-key-store-name ExampleVPCEndpointXKS \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
--xks-proxy-uri-path "/kms/xks/v1" \
--xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example1" \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
输出：
```
{
"CustomKeyStoreId": cks-3234567890abcdef0
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[创建外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystorecreate-xks-keystore.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[CreateCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-custom-key-store.html)*中的。
### `create-grant`
以下代码示例演示了如何使用 `create-grant`。
**AWS CLI**
**创建授权**
以下 `create-grant` 示例将创建授权，以允许 `exampleUser` 用户对 `1234abcd-12ab-34cd-56ef-1234567890ab` KMS 密钥示例使用 `decrypt` 命令。停用主体是 `adminRole` 角色。该授权使用 `EncryptionContextSubset` 授权约束，以便仅在 `decrypt` 请求中的加密上下文包含 `"Department": "IT"` 键值对时才允许此权限。
```
aws kms create-grant \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--grantee-principal arn:aws:iam::123456789012:user/exampleUser \
--operations Decrypt \
--constraints EncryptionContextSubset={Department=IT} \
--retiring-principal arn:aws:iam::123456789012:role/adminRole
```
输出：
```
{
"GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
"GrantToken": ""
}
```
要查看有关授权的详细信息，请使用 `list-grants` 命令。
有关更多信息，请参阅《密*AWS 钥管理服务开发人员指南*》[中的 AWS KMS 中的授权](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[CreateGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-grant.html)*中的。
### `create-key`
以下代码示例演示了如何使用 `create-key`。
**AWS CLI**
**示例 1：在 KMS 中创建客户托管的 KM AWS S 密钥**
以下 `create-key` 示例创建对称加密 KMS 密钥。
要创建基本 KMS 密钥（对称加密密钥），您无需指定任何参数。这些参数的默认值会创建对称加密密钥。
由于此命令未指定密钥策略，因此，KMS 密钥将获得以编程方式创建的 KMS 密钥的[默认密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default)。要查看密钥策略，请使用 `get-key-policy` 命令。要更改密钥策略，请使用 `put-key-policy` 命令。
```
aws kms create-key
```
`create-key` 命令会返回密钥元数据，包括新 KMS 密钥的密钥 ID 和 ARN。在其他 KMS 操作中，您可以使用这些值来识别 AWS KMS 密钥。输出不包括标签。要查看 KMS 密钥的标签，请使用 `list-resource-tags command`。
输出：
```
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2017-07-05T14:04:55-07:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_KMS"
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
注意：`create-key` 命令不允许您指定别名。要为新 KMS 密钥创建别名，请使用 `create-alias` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[创建密钥](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。
**示例 2：创建用于加密和解密的非对称 RSA KMS 密钥**
以下 `create-key` 示例创建了一个 KMS 密钥，其中包含用于加密和解密的非对称 RSA 密钥对。创建密钥后，无法更改密钥规格和密钥用法：
```
aws kms create-key \
--key-spec RSA_4096 \
--key-usage ENCRYPT_DECRYPT
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2021-04-05T14:04:55-07:00",
"CustomerMasterKeySpec": "RSA_4096",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"RSAES_OAEP_SHA_1",
"RSAES_OAEP_SHA_256"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "RSA_4096",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_KMS"
}
}
```
有关更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密钥*。
**示例 3：创建用于签名和验证的非对称椭圆曲线 KMS 密钥**
创建用于签名和验证的非对称 KMS 密钥，其中包含非对称椭圆曲线（ECC）密钥对。尽管 `SIGN_VERIFY` 是 ECC KMS 密钥的唯一有效值，但 `--key-usage` 参数也是必需的。创建密钥后，无法更改密钥规格和密钥用法：
```
aws kms create-key \
--key-spec ECC_NIST_P521 \
--key-usage SIGN_VERIFY
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "ECC_NIST_P521",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "ECC_NIST_P521",
"KeyState": "Enabled",
"KeyUsage": "SIGN_VERIFY",
"MultiRegion": false,
"Origin": "AWS_KMS",
"SigningAlgorithms": [
"ECDSA_SHA_512"
]
}
}
```
有关更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密钥*。
**示例 4：创建用于签名和验证的非对称 ML-DSA KMS 密钥**
此示例创建了一个用于签名和验证的模格数字签名算法（ML-DSA）密钥。即使 `SIGN_VERIFY` 是 ML-DSA 密钥的唯一有效值，key-usage 参数也是必需的。
```
aws kms create-key \
--key-spec ML_DSA_65 \
--key-usage SIGN_VERIFY
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "ML_DSA_65",
"KeyState": "Enabled",
"KeyUsage": "SIGN_VERIFY",
"MultiRegion": false,
"Origin": "AWS_KMS",
"SigningAlgorithms": [
"ML_DSA_SHAKE_256"
]
}
}
```
有关更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密钥*。
**示例 5：创建 HMAC KMS 密钥**
以下 `create-key` 示例将创建 384 位 HMAC KMS 密钥。尽管 `--key-usage` 参数的 `GENERATE_VERIFY_MAC` 值是 HMAC KMS 密钥的唯一有效值，但该值也是必需的。
```
aws kms create-key \
--key-spec HMAC_384 \
--key-usage GENERATE_VERIFY_MAC
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2022-04-05T14:04:55-07:00",
"CustomerMasterKeySpec": "HMAC_384",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "HMAC_384",
"KeyState": "Enabled",
"KeyUsage": "GENERATE_VERIFY_MAC",
"MacAlgorithms": [
"HMAC_SHA_384"
],
"MultiRegion": false,
"Origin": "AWS_KMS"
}
}
```
有关更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的 HMA](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) *C AWS 密钥*。
**示例 6：创建多区域主 KMS 密钥**
以下 `create-key` 示例创建多区域主对称加密密钥。由于所有参数的默认值都会创建对称加密密钥，因此，此 KMS 密钥只需要 `--multi-region` 参数。在 AWS CLI 中，要指示布尔参数为真，只需指定参数名称即可。
```
aws kms create-key \
--multi-region
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
"AWSAccountId": "111122223333",
"CreationDate": "2021-09-02T016:15:21-09:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "mrk-1234abcd12ab34cd56ef12345678990ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": true,
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
"Region": "us-west-2"
},
"ReplicaKeys": []
},
"Origin": "AWS_KMS"
}
}
```
有关更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密钥*。
**示例 7：为导入的密钥材料创建 KMS 密钥**
以下 `create-key` 示例创建一个不带密钥材料的 KMS 密钥。操作完成后，您可以将自己的密钥材料导入 KMS 密钥。要创建此 KMS 密钥，请将 `--origin` 参数设置为 `EXTERNAL`。
```
aws kms create-key \
--origin EXTERNAL
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": false,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "PendingImport",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "EXTERNAL"
}
}
```
有关更多信息，请参阅《[密钥*管理服务开发人员指南》中的在 AWS KMS 密AWS 钥中导*入密钥材料](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)。
**示例 6：在 AWS CloudHSM 密钥存储库中创建 KMS 密钥**
以下`create-key`示例在指定的 AWS CloudHSM 密钥存储中创建一个 KMS 密钥。该操作在 KMS 中 AWS 创建 KMS 密钥及其元数据，并在与自定义密钥存储库关联的 AWS CloudHSM 集群中创建密钥材料。`--custom-key-store-id` 和 `--origin` 参数是必需的。
```
aws kms create-key \
--origin AWS_CLOUDHSM \
--custom-key-store-id cks-1234567890abcdef0
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_CLOUDHSM"
}
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的 [AWS CloudHSM 密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html)。
**示例 8：在外部密钥存储中创建 KMS 密钥**
以下 `create-key` 示例在指定的外部密钥存储中创建一个 KMS 密钥。在此命令中需要使用 `--custom-key-store-id`、`--origin` 和 `--xks-key-id` 参数。
`--xks-key-id` 参数指定外部密钥管理器中现有对称加密密钥的 ID。此密钥用作 KMS 密钥的外部密钥材料。`--origin` 参数的值必须为 `EXTERNAL_KEY_STORE`。`custom-key-store-id` 参数必须识别连接到其外部密钥存储代理的外部密钥存储。
```
aws kms create-key \
--origin EXTERNAL_KEY_STORE \
--custom-key-store-id cks-9876543210fedcba9 \
--xks-key-id bb8562717f809024
```
输出：
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2022-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"CustomKeyStoreId": "cks-9876543210fedcba9",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "EXTERNAL_KEY_STORE",
"XksKeyConfiguration": {
"Id": "bb8562717f809024"
}
}
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[CreateKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-key.html)*中的。
### `decrypt`
以下代码示例演示了如何使用 `decrypt`。
**AWS CLI**
**示例 1：使用对称 KMS 密钥解密加密消息（Linux 和 macOS）**
以下`decrypt`命令示例演示了使用 CLI AWS 解密数据的推荐方法。此版本演示了如何使用对称 KMS 密钥解密数据。
在文件中提供加密文字。在 `--ciphertext-blob` 参数的值中，使用 `fileb://` 前缀，它将指示 CLI 从二进制文件中读取数据。如果文件不在当前目录中，请键入文件的完整路径。有关从文件读取 AWS CLI 参数值的更多信息，请参阅*AWS 命令行界面用户指南中的从文件中加载 AWS CLI 参数 < https://docs.aws.amazon.com/cli/ latest/userguide/cli-usage-parameters-file .html> 和AWS 命令行**工具博客*中的本地文件参数最佳实践 < dev https://aws.amazon.com/blogs/ eloper/ best-practices-for-local-file-parameters/>。指定 KMS 密钥来解密密文。使用对称 KMS 密钥解密时不需要参数。`--key-id` AWS KMS 可以从密文中的元数据中获取用于加密数据的 KMS 密钥的密钥 ID。但是，指定您正在使用的 KMS 密钥始终是最佳实践。此做法可确保您使用预期的 KMS 密钥，并防止您意外使用不信任的 KMS 密钥解密加密文字。以文本值请求明文输出。`--query` 参数指示 CLI 仅从输出中获取 `Plaintext` 字段的值。`--output` 参数以 text.base64 解码格式返回明文输出并将其保存在文件中。以下示例将 `Plaintext` 参数的值传送（\$1）给 Base64 实用程序，该程序负责对其进行解码。然后，它将解码后的输出重定向（>）到 `ExamplePlaintext` 文件。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。
```
aws kms decrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text \
--query Plaintext | base64 \
--decode > ExamplePlaintextFile
```
此命令不生成任何输出。`decrypt` 命令的输出经过 base64 解码并保存在文件中。
有关更多信息，请参阅《AWS 密钥管理服务 API Reference》**中的[解密](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)。
**示例 2：使用对称 KMS 密钥解密加密消息（Windows 命令提示符）**
以下示例与前一个示例相同，不同之处在于，它使用 `certutil` 实用程序对明文数据进行 Base64 解码。此过程需要两个命令，如以下示例所示。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。
```
aws kms decrypt ^
--ciphertext-blob fileb://ExampleEncryptedFile ^
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
--output text ^
--query Plaintext > ExamplePlaintextFile.base64
```
运行 `certutil` 命令。
```
certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile
```
输出：
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
有关更多信息，请参阅《AWS 密钥管理服务 API Reference》**中的[解密](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)。
**示例 3：使用非对称 KMS 密钥解密加密消息（Linux 和 macOS）**
以下 `decrypt` 命令示例演示如何解密在 RSA 非对称 KMS 密钥下加密的数据。
使用非对称 KMS 密钥时，需要 `encryption-algorithm` 参数，以指定用于加密明文的算法。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。
```
aws kms decrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--encryption-algorithm RSAES_OAEP_SHA_256 \
--output text \
--query Plaintext | base64 \
--decode > ExamplePlaintextFile
```
此命令不生成任何输出。`decrypt` 命令的输出经过 base64 解码并保存在文件中。
有关更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密钥*。
+ 有关 API 详细信息，请参阅《AWS CLI 命令参考》**中的[解密](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/decrypt.html)。
### `delete-alias`
以下代码示例演示了如何使用 `delete-alias`。
**AWS CLI**
**删除 AWS KMS 别名**
以下 `delete-alias` 示例将删除别名 `alias/example-alias`。别名名称必须以 alias/ 开头。
```
aws kms delete-alias \
--alias-name alias/example-alias
```
此命令不生成任何输出。要查找别名，请使用 `list-aliases` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[删除别名](https://docs.aws.amazon.com/kms/latest/developerguide/alias-manage.html#alias-delete)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DeleteAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-alias.html)*中的。
### `delete-custom-key-store`
以下代码示例演示了如何使用 `delete-custom-key-store`。
**AWS CLI**
**删除自定义密钥存储**
以下 `delete-custom-key-store` 示例删除指定自定义密钥存储。
删除 AWS CloudHSM 密钥库不会对关联的 CloudHSM 集群产生任何影响。删除外部密钥存储不会影响关联的外部密钥存储代理、外部密钥管理器或外部密钥。
**注意：**要删除一个自定义密钥存储，必须先计划删除该自定义密钥存储中的所有 KMS 密钥，然后等待这些 KMS 密钥被删除。之后，必须断开连接该自定义密钥存储。有关在自定义密钥存储中查找 KMS 密钥的帮助，请参阅密钥*管理*服务开发者[AWS 指南中的AWS 删除 CloudHSM 密钥存储 (API](https://docs.aws.amazon.com/kms/latest/developerguide/delete-keystore.html#delete-keystore-api))。
```
delete-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
此命令不返回任何输出。要确认是否删除了该自定义密钥存储，请使用 `describe-custom-key-stores` 命令。
*有关删除 AWS CloudHSM 密钥库的信息，请参阅《密钥管理服务开发者指南》中的[删除 AWS CloudHSM 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/delete-keystore.html)存储库。AWS *
有关删除外部密钥存储的信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[删除外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/delete-xks.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DeleteCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-custom-key-store.html)*中的。
### `delete-imported-key-material`
以下代码示例演示了如何使用 `delete-imported-key-material`。
**AWS CLI**
**从 KMS 密钥中删除导入的密钥材料**
以下 `delete-imported-key-material` 示例删除导入到 KMS 密钥的密钥材料。
```
aws kms delete-imported-key-material \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
有关更多信息，请参阅《AWS Key Management Service Developer Guide》**中的 [Deleting imported key material](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-delete-key-material.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DeleteImportedKeyMaterial](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-imported-key-material.html)*中的。
### `derive-shared-secret`
以下代码示例演示了如何使用 `derive-shared-secret`。
**AWS CLI**
**派生共享密钥**
以下 `derive-shared-secret` 示例使用密钥协议算法派生共享密钥。
您必须使用 NIST 推荐的非对称椭圆曲线 (ECC) 或（仅限 SM2 中国区域）KMS 密钥对，其值为to call。`KeyUsage` `KEY_AGREEMENT` DeriveSharedSecret
```
aws kms derive-shared-secret \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-agreement-algorithm ECDH \
--public-key "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvH3Yj0wbkLEpUl95Cv1cJVjsVNSjwGq3tCLnzXfhVwVvmzGN8pYj3U8nKwgouaHbBWNJYjP5VutbbkKS4Kv4GojwZBJyHN17kmxo8yTjRmjR15SKIQ8cqRA2uaERMLnpztIXdZp232PQPbWGxDyXYJ0aJ5EFSag"
```
输出：
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"SharedSecret": "MEYCIQCKZLWyTk5runarx6XiAkU9gv3lbwPO/pHa+DXFehzdDwIhANwpsIV2g/9SPWLLsF6p/hiSskuIXMTRwqrMdVKWTMHG",
"KeyAgreementAlgorithm": "ECDH",
"KeyOrigin": "AWS_KMS"
}
```
有关更多信息，请参阅《*AWS 密钥管理服务 API 参考*》[DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html)中的。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DeriveSharedSecret](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/derive-shared-secret.html)*中的。
### `describe-custom-key-stores`
以下代码示例演示了如何使用 `describe-custom-key-stores`。
**AWS CLI**
**示例 1：获取有关 AWS CloudHSM 密钥存储库的详细信息**
以下`describe-custom-key-store`示例显示了有关指定 AWS CloudHSM 密钥库的详细信息。该命令对于所有类型的自定义密钥存储都是一样的，只是输出因密钥存储类型而异，并且对于外部密钥存储来说，还因其连接选项而异。
默认情况下，该命令显示有关账户和区域中的所有自定义密钥存储的信息。要显示有关特定自定义密钥存储的信息，请使用 `custom-key-store-name` 或 `custom-key-store-id` 参数。
```
aws kms describe-custom-key-stores \
--custom-key-store-name ExampleCloudHSMKeyStore
```
此命令的输出包括有关 AWS CloudHSM 密钥库的有用详细信息，包括其连接状态 ()。`ConnectionState`如果连接状态为 `FAILED`，则输出中还包含描述问题的 `ConnectionErrorCode` 字段。
输出：
```
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-04-05T14:04:55-07:00",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleExternalKeyStore",
"TrustAnchorCertificate": ""
}
]
}
```
有关更多信息，请参阅《密钥*管理服务[开发者 AWS 指南》中的AWS 查看 CloudHSM 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/view-keystore.html)*存储区。
**示例 2：获取使用公有端点连接的外部密钥存储的详细信息**
以下 `describe-custom-key-store` 示例显示有关指定外部密钥存储的详细信息。该命令对于所有类型的自定义密钥存储都是一样的，只是输出因密钥存储类型而异，并且对于外部密钥存储来说，还因其连接选项而异。
默认情况下，该命令显示有关账户和区域中的所有自定义密钥存储的信息。要显示有关特定自定义密钥存储的信息，请使用 `custom-key-store-name` 或 `custom-key-store-id` 参数。
```
aws kms describe-custom-key-stores \
--custom-key-store-id cks-9876543210fedcba9
```
该命令的输出中包括有关外部密钥存储的有用详细信息，包括其连接状态（`ConnectionState`）。如果连接状态为 `FAILED`，则输出中还包含描述问题的 `ConnectionErrorCode` 字段。
输出：
```
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXKS",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-02T07:48:55-07:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "PUBLIC_ENDPOINT",
"UriEndpoint": "https://myproxy.xks.example.com",
"UriPath": "/example-prefix/kms/xks/v1"
}
}
]
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[查看外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/view-xks-keystore.html)。
**示例 3：获取使用 VPC 端点服务连接的外部密钥存储的详细信息**
以下 `describe-custom-key-store` 示例显示有关指定外部密钥存储的详细信息。该命令对于所有类型的自定义密钥存储都是一样的，只是输出因密钥存储类型而异，并且对于外部密钥存储来说，还因其连接选项而异。
默认情况下，该命令显示有关账户和区域中的所有自定义密钥存储的信息。要显示有关特定自定义密钥存储的信息，请使用 `custom-key-store-name` 或 `custom-key-store-id` 参数。
```
aws kms describe-custom-key-stores \
--custom-key-store-id cks-2234567890abcdef0
```
该命令的输出中包括有关外部密钥存储的有用详细信息，包括其连接状态（`ConnectionState`）。如果连接状态为 `FAILED`，则输出中还包含描述问题的 `ConnectionErrorCode` 字段。
输出：
```
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-3234567890abcdef0",
"CustomKeyStoreName": "ExampleVPCExternalKeyStore",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-22T07:48:55-07:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://myproxy-private.xks.example.com",
"UriPath": "/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example1"
}
}
]
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[查看外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/view-xks-keystore.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DescribeCustomKeyStores](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/describe-custom-key-stores.html)*中的。
### `describe-key`
以下代码示例演示了如何使用 `describe-key`。
**AWS CLI**
**示例 1：查找有关 KMS 密钥的详细信息**
以下`describe-key`示例在示例账户和区域中获取有关 Amazon S3 AWS 托管密钥的详细信息。您可以使用此命令来查找有关 AWS 托管密钥和客户托管密钥的详细信息。
要指定 KMS 密钥，请使用 `key-id` 参数。此示例使用别名名称值，但您可以在此命令中使用密钥 ID、密钥 ARN、别名名称或别名 ARN。
```
aws kms describe-key \
--key-id alias/aws/s3
```
输出：
```
{
"KeyMetadata": {
"AWSAccountId": "846764612917",
"KeyId": "b8a9477d-836c-491f-857e-07937918959b",
"Arn": "arn:aws:kms:us-west-2:846764612917:key/b8a9477d-836c-491f-857e-07937918959b",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CreationDate": 2017-06-30T21:44:32.140000+00:00,
"Enabled": true,
"Description": "Default KMS key that protects my S3 objects when no other key is defined",
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "AWS",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[查看密钥](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html)。
**示例 2：获取有关 RSA 非对称 KMS 密钥的详细信息**
以下 `describe-key` 示例获取有关用于签名和验证的非对称 RSA KMS 密钥的详细信息。
```
aws kms describe-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2019-12-02T19:47:14.861000+00:00",
"CustomerMasterKeySpec": "RSA_2048",
"Enabled": false,
"Description": "",
"KeyState": "Disabled",
"Origin": "AWS_KMS",
"MultiRegion": false,
"KeyManager": "CUSTOMER",
"KeySpec": "RSA_2048",
"KeyUsage": "SIGN_VERIFY",
"SigningAlgorithms": [
"RSASSA_PKCS1_V1_5_SHA_256",
"RSASSA_PKCS1_V1_5_SHA_384",
"RSASSA_PKCS1_V1_5_SHA_512",
"RSASSA_PSS_SHA_256",
"RSASSA_PSS_SHA_384",
"RSASSA_PSS_SHA_512"
]
}
}
```
**示例 3：获取有关多区域副本密钥的详细信息**
以下 `describe-key` 示例获取多区域副本密钥的元数据。此多区域密钥是对称加密密钥。任何多区域密钥的 `describe-key` 命令输出都会返回有关主密钥及其所有副本的信息。
```
aws kms describe-key \
--key-id arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
```
输出：
```
{
"KeyMetadata": {
"MultiRegion": true,
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"CreationDate": "2021-06-28T21:09:16.114000+00:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"Description": "",
"Enabled": true,
"KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "AWS_KMS",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "us-west-2"
},
"ReplicaKeys": [
{
"Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "eu-west-1"
},
{
"Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "ap-northeast-1"
},
{
"Arn": "arn:aws:kms:sa-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "sa-east-1"
}
]
}
}
}
```
**示例 4：获取有关 HMAC KMS 密钥的详细信息**
以下 `describe-key` 示例获取有关 HMAC KMS 密钥的详细信息。
```
aws kms describe-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"KeyMetadata": {
"AWSAccountId": "123456789012",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2022-04-03T22:23:10.194000+00:00",
"Enabled": true,
"Description": "Test key",
"KeyUsage": "GENERATE_VERIFY_MAC",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "CUSTOMER",
"CustomerMasterKeySpec": "HMAC_256",
"MacAlgorithms": [
"HMAC_SHA_256"
],
"MultiRegion": false
}
}
```
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DescribeKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/describe-key.html)*中的。
### `disable-key-rotation`
以下代码示例演示了如何使用 `disable-key-rotation`。
**AWS CLI**
**禁用自动轮换 KMS 密钥**
以下 `disable-key-rotation` 示例禁用自动轮换客户托管的 KMS 密钥。要重新启用自动轮换，请使用 `enable-key-rotation` 命令。
```
aws kms disable-key-rotation \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
此命令不生成任何输出。要验证是否对 KMS 密钥禁用自动轮换，请使用 `get-key-rotation-status` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[轮换密钥](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DisableKeyRotation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disable-key-rotation.html)*中的。
### `disable-key`
以下代码示例演示了如何使用 `disable-key`。
**AWS CLI**
**暂时禁用 KMS 密钥**
以下 `disable-key` 命令禁用客户自主管理型 KMS 密钥。要重新启用 KMS 密钥，请使用 `enable-key` 命令。
```
aws kms disable-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
此命令不生成任何输出。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[启用和禁用密钥](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DisableKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disable-key.html)*中的。
### `disconnect-custom-key-store`
以下代码示例演示了如何使用 `disconnect-custom-key-store`。
**AWS CLI**
**断开连接自定义密钥存储**
以下`disconnect-custom-key-store`示例断开自定义密钥库与其 Clou AWS dHSM 集群的连接。您可以断开连接一个密钥存储，以便解决问题、更新其设置或防止该密钥存储中的 KMS 密钥被用于加密操作。
此命令适用于所有自定义密钥存储库，包括 AWS CloudHSM 密钥存储库和外部密钥存储库。
在运行此命令之前，请将示例自定义密钥存储 ID 替换为有效 ID。
```
$ aws kms disconnect-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
此命令不生成任何输出。要验证命令是否有效，请使用 `describe-custom-key-stores` 命令。
*有关断开 Cloud AWS HSM 密钥库连接的更多信息，[请参阅《密钥管理服务开发者指南》中的连接和断开 AWS CloudHSM](https://docs.aws.amazon.com/kms/latest/developerguide/disconnect-keystore.html) 密钥存储库的连接。AWS *
有关断开连接外部密钥存储的更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[连接和断开连接外部密钥存储](https://docs.aws.amazon.com/kms/latest/developerguide/xks-connect-disconnect.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[DisconnectCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disconnect-custom-key-store.html)*中的。
### `enable-key-rotation`
以下代码示例演示了如何使用 `enable-key-rotation`。
**AWS CLI**
**启用自动轮换 KMS 密钥**
以下 `enable-key-rotation` 示例启用自动轮换客户托管的 KMS 密钥，轮换周期为 180 天。KMS 密钥将自该命令完成之日起一年（大约 365 天）以及此后每年进行轮换。
`--key-id` 参数标识 KMS 密钥。此示例使用密钥 ARN 值，但您可以使用 KMS 密钥的密钥 ID 或 ARN。`--rotation-period-in-days` 参数指定每次轮换日期之间的天数。可指定 90 到 2560 天之间的值。如果未指定值，则默认值为 365 天。
```
aws kms enable-key-rotation \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--rotation-period-in-days 180
```
此命令不生成任何输出。要验证 KMS 密钥是否已启用，请使用 `get-key-rotation-status` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[轮换密钥](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[EnableKeyRotation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/enable-key-rotation.html)*中的。
### `enable-key`
以下代码示例演示了如何使用 `enable-key`。
**AWS CLI**
**启用 KMS 密钥**
以下 `enable-key` 示例启用客户托管密钥。您可以使用类似的命令来启用您通过 `disable-key` 命令暂时禁用的 KMS 密钥。您还可以使用它来启用已被禁用的 KMS 密钥，因为已计划删除该密钥且删除已取消。
要指定 KMS 密钥，请使用 `key-id` 参数。此示例使用密钥 ID 值，但您可以在此命令中使用密钥 ID 或密钥 ARN 值。
在运行此命令之前，将密钥 ID 示例替换为有效 ID。
```
aws kms enable-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
此命令不生成任何输出。要验证 KMS 密钥是否已启用，请使用 `describe-key` 命令。查看 `describe-key` 输出中 `KeyState` 和 `Enabled` 字段的值。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[启用和禁用密钥](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[EnableKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/enable-key.html)*中的。
### `encrypt`
以下代码示例演示了如何使用 `encrypt`。
**AWS CLI**
**示例 1：在 Linux 或 macOS 上对文件内容进行加密**
以下`encrypt`命令演示了使用 AWS CLI 加密数据的推荐方法。
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
该命令可以执行以下几项操作：
使用 `--plaintext` 参数来指示要加密的数据。此参数值必须采用 Base64 编码。该`plaintext`参数的值必须采用 base64 编码，或者必须使用前缀`fileb://`，它指示 CL AWS I 从文件中读取二进制数据。如果文件不在当前目录中，请键入文件的完整路径。例如：`fileb:///var/tmp/ExamplePlaintextFile` 或 `fileb://C:\Temp\ExamplePlaintextFile`。[有关从文件读取 AWS CLI 参数值的更多信息，请参阅《*AWS 命令行界面用户指南》*中的 “[从文件加载参数](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-file)[” 和 “ AWS 命令行工具博客” 上的 “本地文件参数最佳实践](https://blogs.aws.amazon.com/cli/post/TxLWWN1O25V1HE/Best-Practices-for-Local-File-Parameters)”。使用`--output`和`--query`参数控制命令的输出。这些参数从命令的输出中提取加密数据（称为*密文*）。有关控制输出的更多信息，请参阅控制命令*AWS 命令行界面用户指南*中的输出](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html)。使用该`base64`实用程序将提取的输出解码为二进制数据。成功命令返回的密文是 base64 编码的文本。`encrypt`必须先解码此文本，然后才能使用 AWS CLI 对其进行解密。将二进制密文保存到文件中。命令 (`> ExampleEncryptedFile`) 的最后一部分将二进制密文保存到文件中，以便于解密。有关使用 AWS CLI 解密数据的命令示例，请参阅解密示例。
**示例 2：使用 AWS CLI 在 Windows 上加密数据**
此示例与前一个示例相同，不同之处在于，它使用 `certutil` 工具代替 `base64`。此过程需要两个命令，如以下示例所示。
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob > C:\Temp\ExampleEncryptedFile.base64
certutil -decode C:\Temp\ExampleEncryptedFile.base64 C:\Temp\ExampleEncryptedFile
```
**示例 3：使用非对称 KMS 密钥进行加密**
以下 `encrypt` 命令显示如何使用非对称 KMS 密钥加密明文。`--encryption-algorithm` 参数是必需的。与所有 `encrypt` CLI 命令一样，该`plaintext`参数必须采用 base64 编码，或者必须使用`fileb://`前缀，它告诉 CL AWS I 从文件中读取二进制数据。
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encryption-algorithm RSAES_OAEP_SHA_256 \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
此命令不生成任何输出。
+ 有关 API 详细信息，请参阅《AWS CLI 命令参考》**中的 [Encrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/encrypt.html)。
### `generate-data-key-pair-without-plaintext`
以下代码示例演示了如何使用 `generate-data-key-pair-without-plaintext`。
**AWS CLI**
**生成 ECC NIST P384 非对称数据密钥对**
以下`generate-data-key-pair-without-plaintext`示例请求一个 ECC NIST P384 密钥对以外使用。 AWS
该命令在指定 KMS 密钥下返回一个明文公钥和一个加密私钥副本。它不返回明文私钥。您可以安全地将加密的私钥与加密数据一起存储，并在需要时调用 AWS KMS 解密私钥。
要请求 ECC NIST P384 非对称数据密钥对，请使用 `key-pair-spec` 参数且值设为 `ECC_NIST_P384`。
您指定的 KMS 密钥必须是对称加密 KMS 密钥，即 `KeySpec` 值为 `SYMMETRIC_DEFAULT` 的 KMS 密钥。
注意：本示例输出中的值被截断，便于显示。
```
aws kms generate-data-key-pair-without-plaintext \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-pair-spec ECC_NIST_P384
```
输出：
```
{
"PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
"PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"KeyPairSpec": "ECC_NIST_P384"
}
```
`PublicKey` 和 `PrivateKeyCiphertextBlob` 以 base64 编码的格式返回。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[数据密钥对](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-key-pairs)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GenerateDataKeyPairWithoutPlaintext](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-pair-without-plaintext.html)*中的。
### `generate-data-key-pair`
以下代码示例演示了如何使用 `generate-data-key-pair`。
**AWS CLI**
**生成 2048 位 RSA 非对称数据密钥对**
以下`generate-data-key-pair`示例请求一个 2048 位 RSA 非对称数据密钥对，以便在之外使用。 AWS该命令在指定 KMS 密钥下返回一个明文公钥和一个明文私钥以供立即使用和删除，另外还返回一个加密私钥的副本。您可以安全地将加密私钥与加密数据一起存储。
要请求 2048 位 RSA 非对称数据密钥对，请使用 `key-pair-spec` 参数且值设为 `RSA_2048`。
您指定的 KMS 密钥必须是对称加密 KMS 密钥，即 `KeySpec` 值为 `SYMMETRIC_DEFAULT` 的 KMS 密钥。
注意：本示例输出中的值被截断，便于显示。
```
aws kms generate-data-key-pair \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-pair-spec RSA_2048
```
输出：
```
{
"PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
"PrivateKeyPlaintext": "MIIG/QIBADANBgkqhkiG9w0BAQEFAASCBucwggbjAgEAAoIBgQDcDd4YzI+u9Kfv4t2UkTWhShBXkekS4cBVt07I0P42ZgMf+YvU5IgS4ut...",
"PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
"KeyPairSpec": "RSA_2048"
}
```
`PublicKey`、`PrivateKeyPlaintext` 和 `PrivateKeyCiphertextBlob` 以 base64 编码的格式返回。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[数据密钥对](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-key-pairs)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GenerateDataKeyPair](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-pair.html)*中的。
### `generate-data-key-without-plaintext`
以下代码示例演示了如何使用 `generate-data-key-without-plaintext`。
**AWS CLI**
**生成不带明文密钥的 256 位对称数据密钥**
以下 `generate-data-key-without-plaintext` 示例请求 256 位对称数据密钥的加密副本以供在 AWS外部使用。准备好使用数据密钥时，可以调用 AWS KMS 对其进行解密。
要请求 256 位数据密钥，请使用值为 `AES_256` 的 `key-spec` 参数。要请求 128 位数据密钥，请使用值为 `AES_128` 的 `key-spec` 参数。对于所有其他数据密钥长度，请使用 `number-of-bytes` 参数。
您指定的 KMS 密钥必须是对称加密 KMS 密钥，即 KeySpec 值为 SYMMETRIC\$1DEFAULT 的 KMS 密钥。
```
aws kms generate-data-key-without-plaintext \
--key-id "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--key-spec AES_256
```
输出：
```
{
"CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogL",
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
`CiphertextBlob`（加密数据密钥）以 base64 编码的格式返回。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[数据密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GenerateDataKeyWithoutPlaintext](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-without-plaintext.html)*中的。
### `generate-data-key`
以下代码示例演示了如何使用 `generate-data-key`。
**AWS CLI**
**示例 1：生成 256 位对称数据密钥**
以下`generate-data-key`示例请求一个 256 位的对称数据密钥以供外部使用。 AWS该命令返回一个明文数据密钥以供立即使用和删除，以及以指定 KMS 密钥加密的该数据密钥的副本。您可以安全地将加密的数据密钥与加密的数据一起存储。
要请求 256 位数据密钥，请使用值为 `AES_256` 的 `key-spec` 参数。要请求 128 位数据密钥，请使用值为 `AES_128` 的 `key-spec` 参数。对于所有其他数据密钥长度，请使用 `number-of-bytes` 参数。
您指定的 KMS 密钥必须是对称加密 KMS 密钥，即 KeySpec 值为 SYMMETRIC\$1DEFAULT 的 KMS 密钥。
```
aws kms generate-data-key \
--key-id alias/ExampleAlias \
--key-spec AES_256
```
输出：
```
{
"Plaintext": "VdzKNHGzUAzJeRBVY+uUmofUGGiDzyB3+i9fVkh3piw=",
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogLqPWZconQhwHAIBEIA7d9AC7GeJJM34njQvg4Wf1d5sw0NIo1MrBqZa+YdhV8MrkBQPeac0ReRVNDt9qleAt+SHgIRF8P0H+7U="
}
```
`Plaintext`（明文数据密钥）和 `CiphertextBlob`（加密数据密钥）均以 base64 编码的格式返回。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[数据密钥](https://docs.aws.amazon.com/kms/latest/developerguide/data-keys.html)。**示例 2：生成 512 位对称数据密钥**
以下 `generate-data-key` 示例请求用于加密和解密的 512 位对称数据密钥。该命令返回一个明文数据密钥以供立即使用和删除，以及以指定 KMS 密钥加密的该数据密钥的副本。您可以安全地将加密的数据密钥与加密的数据一起存储。
要请求 128 或 256 位以外的密钥长度，请使用 `number-of-bytes` 参数。为了请求 512 位数据密钥，以下示例使用值为 64（字节）的 `number-of-bytes` 参数。
您指定的 KMS 密钥必须是对称加密 KMS 密钥，即密钥规格值为 SYMMETRIC\$1DEFAULT 的 KMS 密钥。
注意：本示例输出中的值被截断，便于显示。
```
aws kms generate-data-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--number-of-bytes 64
```
输出：
```
{
"CiphertextBlob": "AQIBAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAEnX/QQNmMwDfg2korNMEc8AAACaDCCAmQGCSqGSIb3DQEHBqCCAlUwggJRAgEAMIICSgYJKoZ...",
"Plaintext": "ty8Lr0Bk6OF07M2BWt6qbFdNB+G00ZLtf5MSEb4al3R2UKWGOp06njAwy2n72VRm2m7z/Pm9Wpbvttz6a4lSo9hgPvKhZ5y6RTm4OovEXiVfBveyX3DQxDzRSwbKDPk/...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
`Plaintext`（明文数据密钥）和 `CiphertextBlob`（加密数据密钥）均以 base64 编码的格式返回。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[数据密钥](https://docs.aws.amazon.com/kms/latest/developerguide/data-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GenerateDataKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key.html)*中的。
### `generate-mac`
以下代码示例演示了如何使用 `generate-mac`。
**AWS CLI**
**示例 1：为消息生成 HMAC**
以下 `generate-mac` 命令为消息、HMAC KMS 密钥和 MAC 算法生成 HMAC。该算法必须受指定的 HMAC KMS 密钥支持。
在 AWS CLI v2 中，`message`参数的值必须采用 Base64 编码。或者，您可以将消息保存在文件中并使用`fileb://`前缀，它告诉 AWS CLI 从文件中读取二进制数据。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。密钥 ID 必须表示密钥用法为 `GENERATE_VERIFY_MAC` 的 HMAC KMS 密钥。
```
msg=(echo 'Hello World' | base64)
aws kms generate-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://Message \
--mac-algorithm HMAC_SHA_384
```
输出：
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Mac": "",
"MacAlgorithm": "HMAC_SHA_384"
}
```
有关在 AWS KMS 中使用 HMAC KMS 密钥的更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的 HMA](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) *C AWS 密*钥。
**示例 2：将 HMAC 保存在文件中（Linux 和 macOs）**
以下 `generate-mac` 示例为一条存储在本地文件中的短消息生成 HMAC。该命令还会从响应中获取`Mac`属性，Base64 对其进行解码并将其保存在文件中。 ExampleMac 您可以在验证 MAC 的 `verify-mac` 命令中使用该 MAC 文件。
`generate-mac` 命令需要一条以 Base64 编码的消息和您的 HMAC KMS 密钥支持的 MAC 算法。要获取 KMS 密钥支持的 MAC 算法，请使用 `describe-key` 命令。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。密钥 ID 必须表示密钥用法为 GENERATE\$1VERIFY\$1MAC 的非对称 KMS 密钥。
```
echo 'hello world' | base64 > EncodedMessage
aws kms generate-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--mac-algorithm HMAC_SHA_384 \
--output text \
--query Mac | base64 --decode > ExampleMac
```
此命令不生成任何输出。此示例提取输出的 `Mac` 属性并将其保存在文件中。
有关在 AWS KMS 中使用 HMAC KMS 密钥的更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的 HMA](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) *C AWS 密*钥。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GenerateMac](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-mac.html)*中的。
### `generate-random`
以下代码示例演示了如何使用 `generate-random`。
**AWS CLI**
**示例 1：生成 256 位随机字节字符串（Linux 或 macOS）**
以下 `generate-random` 示例生成 256 位（32 字节）、以 base64 编码的随机字节字符串。该示例对字节字符串进行解码并将其保存在随机文件中。
运行此命令时，您必须使用 `number-of-bytes` 参数指定随机值的长度（以字节为单位）。
在运行此命令时，无需指定 KMS 密钥。随机字节字符串与任何 KMS 密钥无关。
默认情况下， AWS KMS 会生成随机数。但是，如果您指定[自定义密钥存储库](https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)，则随机字节字符串将在与该自定义密钥库关联的 AWS CloudHSM 集群中生成。
本示例使用以下参数和值：
它使用值为的必需`--number-of-bytes`参数`32`来请求一个 32 字节（256 位）的字符串。它使用值为的`--output`参数指示 CL AWS I 将输出作为文本返回，而不是 JSON。它使用从响应中提取`Plaintext`属性的值。它使用重定`--query parameter`向运算符 (>) 从响应中提取的字符串中提取出来。它使用重定向运算符 (>) 来保存解码后的字节字符串到文件。它使用重定向运算符 (>) `text` `base64` `ExampleRandom`将二进制密文保存到文件中。
```
aws kms generate-random \
--number-of-bytes 32 \
--output text \
--query Plaintext | base64 --decode > ExampleRandom
```
此命令不生成任何输出。
有关更多信息，请参阅《*AWS 密钥管理服务 API 参考*》[GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html)中的。
**示例 2：生成 256 位随机数（Windows 命令提示符）**
以下示例使用 `generate-random` 命令生成 256 位（32 字节）、以 base64 编码的随机字节字符串。该示例对字节字符串进行解码并将其保存在随机文件中。此示例与前面的示例相同，不同之处在于：它在将随机字节字符串保存到文件之前，使用 Windows 中的 `certutil` 实用工具对随机字节字符串进行 base64 解码。
首先，生成一个 base64 编码的随机字节字符串并将其保存在临时文件 `ExampleRandom.base64` 中。
```
aws kms generate-random \
--number-of-bytes 32 \
--output text \
--query Plaintext > ExampleRandom.base64
```
由于 `generate-random` 命令的输出保存在文件中，因此，此示例不生成任何输出。
现在，使用 `certutil -decode` 命令解码 `ExampleRandom.base64` 文件中以 base64 编码的字节字符串。然后，它将解码后的字节字符串保存在 `ExampleRandom` 文件中。
```
certutil -decode ExampleRandom.base64 ExampleRandom
```
输出：
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
有关更多信息，请参阅《*AWS 密钥管理服务 API 参考*》[GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html)中的。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GenerateRandom](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-random.html)*中的。
### `get-key-policy`
以下代码示例演示了如何使用 `get-key-policy`。
**AWS CLI**
**将密钥策略从一个 KMS 密钥复制到另一个 KMS 密钥**
以下 `get-key-policy` 示例从一个 KMS 密钥获取密钥策略并将其保存在文本文件中。然后，它使用文本文件作为策略输入替换其他 KMS 密钥的策略。
由于 `put-key-policy` 的 `--policy` 参数需要字符串，因此，您必须使用 `--output text` 选项将输出作为文本字符串（而不是 JSON）返回。
```
aws kms get-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--query Policy \
--output text > policy.txt
aws kms put-key-policy \
--policy-name default \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--policy file://policy.txt
```
此命令不生成任何输出。
有关更多信息，请参阅 *AWS KMS API 参考[PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html)*中的。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GetKeyPolicy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-key-policy.html)*中的。
### `get-key-rotation-status`
以下代码示例演示了如何使用 `get-key-rotation-status`。
**AWS CLI**
**检索 KMS 密钥的轮换状态**
以下 `get-key-rotation-status` 示例返回有关指定 KMS 密钥轮换状态的信息，包括是否启用自动轮换、轮换周期以及下个预定轮换日期。您可以对客户托管的 KMS 密钥和 AWS 托管 KMS 密钥使用此命令。但是，所有 AWS 托管的 KMS 密钥每年都会自动轮换。
```
aws kms get-key-rotation-status \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyRotationEnabled": true,
"NextRotationDate": "2024-02-14T18:14:33.587000+00:00",
"RotationPeriodInDays": 365
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[轮换密钥](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GetKeyRotationStatus](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-key-rotation-status.html)*中的。
### `get-parameters-for-import`
以下代码示例演示了如何使用 `get-parameters-for-import`。
**AWS CLI**
**获取将密钥材料导入 KMS 密钥所需的事项**
以下 `get-parameters-for-import` 示例获取将密钥材料导入 KMS 密钥所需的公钥和导入令牌。在使用 `import-key-material` 命令时，请务必使用同一 `get-parameters-for-import` 命令中返回的导入令牌和由公钥加密的密钥材料。此外，您在此命令中指定的包装算法必须和使用公钥加密密钥材料的算法一样。
要指定 KMS 密钥，请使用 `key-id` 参数。此示例使用密钥 ID，但您可以在此命令中使用密钥 ID 或密钥 ARN。
```
aws kms get-parameters-for-import \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-algorithm RSAES_OAEP_SHA_256 \
--wrapping-key-spec RSA_2048
```
输出：
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"PublicKey": "",
"ImportToken": "",
"ParametersValidTo": 1593893322.32
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[下载公钥和导入令牌](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GetParametersForImport](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-parameters-for-import.html)*中的。
### `get-public-key`
以下代码示例演示了如何使用 `get-public-key`。
**AWS CLI**
**示例 1：下载非对称 KMS 密钥的公钥**
以下 `get-public-key` 示例下载非对称 KMS 密钥的公钥。
除了返回公钥外，输出还包括在 AWS KMS 之外安全使用公钥所需的信息，包括密钥使用情况和支持的加密算法。
```
aws kms get-public-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"PublicKey": "jANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAl5epvg1/QtJhxSi2g9SDEVg8QV/...",
"CustomerMasterKeySpec": "RSA_4096",
"KeyUsage": "ENCRYPT_DECRYPT",
"EncryptionAlgorithms": [
"RSAES_OAEP_SHA_1",
"RSAES_OAEP_SHA_256"
]
}
```
有关在 AWS KMS 中使用非对称 KMS 密钥的更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密*钥。**示例 2：将公钥转换为 DER 格式（Linux 和 macOS）**
以下 `get-public-key` 示例下载非对称 KMS 密钥的公钥并将其保存在 DER 文件中。
当你在 AWS CLI 中使用该`get-public-key`命令时，它会返回一个经过 Base64 编码的 DER 编码的 X.509 公钥。此示例获取文本形式的 `PublicKey` 属性的值。它对 `PublicKey` 进行 Base64 解码并将其保存在 `public_key.der` 文件中。`output` 参数返回文本形式的输出，而不是 JSON。该`--query`参数仅获取`PublicKey`属性，而不是在 AWS KMS 之外安全使用公钥所需的属性。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。
```
aws kms get-public-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text \
--query PublicKey | base64 --decode > public_key.der
```
此命令不生成任何输出。
有关在 AWS KMS 中使用非对称 KMS 密钥的更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密*钥。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[GetPublicKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-public-key.html)*中的。
### `import-key-material`
以下代码示例演示了如何使用 `import-key-material`。
**AWS CLI**
**将密钥材料导入 KMS 密钥**
以下 `import-key-material` 示例将密钥材料上传到创建时不含任何密钥材料的 KMS 密钥中。KMS 密钥的密钥状态必须为 `PendingImport`。
此命令使用的密钥材料是您用 `get-parameters-for-import` 命令返回的公钥加密过的材料。它还使用来自同一 `get-parameters-for-import` 命令的导入令牌。
`expiration-model` 参数表示密钥材料会在 `valid-to` 参数指定的日期和时间自动过期。密钥材料到期后， AWS KMS 会删除密钥材料，KMS 密钥的密钥状态更改为`Pending import`，KMS 密钥将无法使用。要还原 KMS 密钥，您必须重新导入这一密钥材料。要使用不同的密钥材料，您必须创建新的 KMS 密钥。
在运行此命令之前，请将示例密钥 ID 替换为您 AWS 账户中的有效密钥 ID 或密钥 ARN。
```
aws kms import-key-material \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://ImportToken.bin \
--expiration-model KEY_MATERIAL_EXPIRES \
--valid-to 2021-09-21T19:00:00Z
```
输出：
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
有关导入密钥材料的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的[导入密钥材料](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)**。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ImportKeyMaterial](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/import-key-material.html)*中的。
### `list-aliases`
以下代码示例演示了如何使用 `list-aliases`。
**AWS CLI**
**示例 1：列出 AWS 账户和区域中的所有别名**
以下示例使用`list-aliases`命令列出 AWS 账户默认区域中的所有别名。输出包括与 AWS 托管 KMS 密钥和客户托管的 KMS 密钥关联的别名。
```
aws kms list-aliases
```
输出：
```
{
"Aliases": [
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/testKey",
"AliasName": "alias/testKey",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/FinanceDept",
"AliasName": "alias/FinanceDept",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb",
"AliasName": "alias/aws/dynamodb",
"TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs",
"AliasName": "alias/aws/ebs",
"TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef"
},
...
]
}
```
**示例 2：列出特定 KMS 密钥的所有别名**
以下示例使用 `list-aliases` 命令及其 `key-id` 参数列出与特定 KMS 密钥关联的所有别名。
每个别名都仅与一个 KMS 密钥关联，但一个 KMS 密钥可以有多个别名。此命令非常有用，因为 AWS KMS 控制台仅列出每个 KMS 密钥的一个别名。要查找 KMS 密钥的所有别名，您必须使用 `list-aliases` 命令。
此示例使用 KMS 密钥的密钥 ID 作为 `--key-id` 参数，但您可以在此命令中使用密钥 ID、密钥 ARN、别名名称或别名 ARN。
```
aws kms list-aliases --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"Aliases": [
{
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/oregon-test-key",
"AliasName": "alias/oregon-test-key"
},
{
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/project121-test",
"AliasName": "alias/project121-test"
}
]
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[使用别名](https://docs.aws.amazon.com/kms/latest/developerguide/programming-aliases.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ListAliases](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-aliases.html)*中的。
### `list-grants`
以下代码示例演示了如何使用 `list-grants`。
**AWS CLI**
**查看 AWS KMS 密钥的授权**
以下`list-grants`示例显示了您的账户中针对亚马逊 DynamoDB 的指定 AWS 托管 KMS 密钥的所有授权。该授权允许 DynamoDB 在将 DynamoDB 表写入磁盘之前代表您使用 KMS 密钥对其进行加密。您可以使用这样的命令来查看 AWS 账户和区域中 AWS 托管 KMS 密钥和客户托管 KMS 密钥的授权。
此命令使用带有密钥 ID 的 `key-id` 参数来识别 KMS 密钥。您可以使用密钥 ID 或密钥 ARN 来识别 KMS 密钥。要获取 AWS 托管 KMS 密钥的密钥 ID 或密钥 ARN，请使用`list-keys`或`list-aliases`命令。
```
aws kms list-grants \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出显示，该授权向 Amazon DynamoDB 授予了使用 KMS 密钥进行加密操作的权限，并向其授予了查看有关 KMS 密钥的详细信息（`DescribeKey`）和停用授权（`RetireGrant`）的权限。`EncryptionContextSubset` 约束将这些权限限制为包含指定加密上下文对的请求。因此，授权中的权限仅对指定账户和 DynamoDB 表有效。
```
{
"Grants": [
{
"Constraints": {
"EncryptionContextSubset": {
"aws:dynamodb:subscriberId": "123456789012",
"aws:dynamodb:tableName": "Services"
}
},
"IssuingAccount": "arn:aws:iam::123456789012:root",
"Name": "8276b9a6-6cf0-46f1-b2f0-7993a7f8c89a",
"Operations": [
"Decrypt",
"Encrypt",
"GenerateDataKey",
"ReEncryptFrom",
"ReEncryptTo",
"RetireGrant",
"DescribeKey"
],
"GrantId": "1667b97d27cf748cf05b487217dd4179526c949d14fb3903858e25193253fe59",
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"RetiringPrincipal": "dynamodb.us-west-2.amazonaws.com",
"GranteePrincipal": "dynamodb.us-west-2.amazonaws.com",
"CreationDate": "2021-05-13T18:32:45.144000+00:00"
}
]
}
```
有关更多信息，请参阅《密*AWS 钥管理服务开发人员指南*》[中的 AWS KMS 中的授权](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ListGrants](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-grants.html)*中的。
### `list-key-policies`
以下代码示例演示了如何使用 `list-key-policies`。
**AWS CLI**
**获取 KMS 密钥的密钥策略名称**
以下 `list-key-policies` 示例获取示例账户和区域中客户托管密钥的密钥策略名称。您可以使用此命令查找托管密钥和客户 AWS 托管密钥的密钥策略名称。
由于唯一有效的密钥策略名称是 `default`，因此，此命令没有用。
要指定 KMS 密钥，请使用 `key-id` 参数。此示例使用密钥 ID 值，但您可以在此命令中使用密钥 ID 或密钥 ARN。
```
aws kms list-key-policies \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"PolicyNames": [
"default"
]
}
```
有关 AWS KMS 密钥策略的更多信息，请参阅《[密钥*管理服务开发人员指南》中的在 AWS KMS 中使用AWS 密钥*策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ListKeyPolicies](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-key-policies.html)*中的。
### `list-key-rotations`
以下代码示例演示了如何使用 `list-key-rotations`。
**AWS CLI**
**检索有关所有已完成的密钥材料轮换的信息**
以下 `list-key-rotations` 示例列出指定 KMS 密钥的所有已完成密钥材料轮换的信息。
```
aws kms list-key-rotations \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"Rotations": [
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"RotationDate": "2024-03-02T10:11:36.564000+00:00",
"RotationType": "AUTOMATIC"
},
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"RotationDate": "2024-04-05T15:14:47.757000+00:00",
"RotationType": "ON_DEMAND"
}
],
"Truncated": false
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[轮换密钥](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ListKeyRotations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-key-rotations.html)*中的。
### `list-keys`
以下代码示例演示了如何使用 `list-keys`。
**AWS CLI**
**获取账户和区域中的 KMS 密钥**
以下 `list-keys` 示例获取账户和区域中的 KMS 密钥。此命令同时返回 AWS 托管密钥和客户托管密钥。
```
aws kms list-keys
```
输出：
```
{
"Keys": [
{
"KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
},
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
"KeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
}
]
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[查看密钥](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ListKeys](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-keys.html)*中的。
### `list-resource-tags`
以下代码示例演示了如何使用 `list-resource-tags`。
**AWS CLI**
**获取 KMS 密钥上的标签**
以下 `list-resource-tags` 示例获取一个 KMS 密钥的标签。要在 KMS 密钥上添加或更换资源标签，请使用 `tag-resource` 命令。输出中显示此 KMS 密钥有两个资源标签，每个标签都有一个键和值。
要指定 KMS 密钥，请使用 `key-id` 参数。此示例使用密钥 ID 值，但您可以在此命令中使用密钥 ID 或密钥 ARN。
```
aws kms list-resource-tags \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"Tags": [
{
"TagKey": "Dept",
"TagValue": "IT"
},
{
"TagKey": "Purpose",
"TagValue": "Test"
}
],
"Truncated": false
}
```
有关在 AWS KMS 中使用标签的更多信息，请参阅《[密钥*管理服务开发人员指南》中的为密AWS 钥*添加](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html)标签。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ListResourceTags](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-resource-tags.html)*中的。
### `list-retirable-grants`
以下代码示例演示了如何使用 `list-retirable-grants`。
**AWS CLI**
**查看主体可以停用的授权**
以下`list-retirable-grants`示例显示了`ExampleAdmin`用户可以停用 AWS 账户和区域中的 KMS 密钥的所有授权。您可以使用类似这样的命令来查看任何账户委托人可以停用 AWS 账户和区域中的 KMS 密钥的授权。
`retiring-principal` 参数为必需的，且其值必须是账户、用户或角色的 Amazon 资源名称（ARN）。
即使服务可以是停用主体，您也不能在此命令中指定服务作为 `retiring-principal` 的值。要查找在哪些授权中特定服务为停用主体，请使用 `list-grants` 命令。
输出显示在该账户和区域中，`ExampleAdmin` 用户有权停用两个不同 KMS 密钥的授权。除了停用主体外，该账户还有权停用账户中的任何授权。
```
aws kms list-retirable-grants \
--retiring-principal arn:aws:iam::111122223333:user/ExampleAdmin
```
输出：
```
{
"Grants": [
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"GrantId": "156b69c63cb154aa21f59929ff19760717be8d9d82b99df53e18b94a15a5e88e",
"Name": "",
"CreationDate": 2021-01-14T20:17:36.419000+00:00,
"GranteePrincipal": "arn:aws:iam::111122223333:user/ExampleUser",
"RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
"IssuingAccount": "arn:aws:iam::111122223333:root",
"Operations": [
"Encrypt"
],
"Constraints": {
"EncryptionContextSubset": {
"Department": "IT"
}
}
},
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"GrantId": "8c94d1f12f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
"Name": "",
"CreationDate": "2021-02-02T19:49:49.638000+00:00",
"GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
"RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
"IssuingAccount": "arn:aws:iam::111122223333:root",
"Operations": [
"Decrypt"
],
"Constraints": {
"EncryptionContextSubset": {
"Department": "IT"
}
}
}
],
"Truncated": false
}
```
有关更多信息，请参阅《密*AWS 钥管理服务开发人员指南*》[中的 AWS KMS 中的授权](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ListRetirableGrants](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-retirable-grants.html)*中的。
### `put-key-policy`
以下代码示例演示了如何使用 `put-key-policy`。
**AWS CLI**
**更改 KMS 密钥的密钥策略**
以下 `put-key-policy` 示例更改客户托管密钥的密钥策略。
首先，创建密钥策略并将其保存在本地 JSON 文件中。在本示例中，该文件为 `key_policy.json`。您也可以将密钥策略指定为 `policy` 参数的字符串值。
此密钥策略中的第一条语句允许 AWS 账户使用 IAM 策略来控制对 KMS 密钥的访问。第二条语句向 `test-user` 用户授予针对 KMS 密钥运行 `describe-key` 和 `list-keys` 命令的权限。
`key_policy.json` 的内容：
```
{
"Version":"2012-10-17",
"Id" : "key-default-1",
"Statement" : [
{
"Sid" : "Enable IAM User Permissions",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : "kms:*",
"Resource" : "*"
},
{
"Sid" : "Allow Use of Key",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:user/test-user"
},
"Action" : [
"kms:DescribeKey",
"kms:ListKeys"
],
"Resource" : "*"
}
]
}
```
为了标识 KMS 密钥，此示例使用了密钥 ID，但您也可以使用密钥 ARN。为了指定密钥策略，该命令使用 `policy` 参数。为了表示策略位于文件中，它使用所需的 `file://` 前缀。需要使用此前缀来识别所有受支持操作系统上的文件。最后，该命令使用值为 `default` 的 `policy-name` 参数。如果未指定策略名称，则默认值为 `default`。唯一有效值为 `default`。
```
aws kms put-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--policy file://key_policy.json
```
此命令不生成任何输出。要验证命令是否有效，请使用 `get-key-policy` 命令。以下示例命令获取相同 KMS 密钥的密钥策略。值为 `text` 的 `output` 参数返回一种易于读取的文本格式。
```
aws kms get-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text
```
输出：
```
{
"Version":"2012-10-17",
"Id" : "key-default-1",
"Statement" : [
{
"Sid" : "Enable IAM User Permissions",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : "kms:*",
"Resource" : "*"
},
{
"Sid" : "Allow Use of Key",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:user/test-user"
},
"Action" : [ "kms:Describe", "kms:List" ],
"Resource" : "*"
}
]
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[更改密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[PutKeyPolicy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/put-key-policy.html)*中的。
### `re-encrypt`
以下代码示例演示了如何使用 `re-encrypt`。
**AWS CLI**
**示例 1：使用不同的对称 KMS 密钥重新加密加密消息（Linux 和 macOS）。**
以下`re-encrypt`命令示例演示了使用 AWS CLI 重新加密数据的推荐方法。
在文件中提供加密文字。在 `--ciphertext-blob` 参数的值中，使用 `fileb://` 前缀，它将指示 CLI 从二进制文件中读取数据。如果文件不在当前目录中，请键入文件的完整路径。有关从文件读取 AWS CLI 参数值的更多信息，请参阅《*AWS 命令行界面用户指南》中的[从文件加载 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html) 参数和AWS 命令行**工具博客*中的[本地文件参数最佳实践。指定源 KMS 密钥，用于](https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/)解密密文。使用对称加密 KMS 密钥进行解密时不需要`--source-key-id`参数。 AWS KMS 可以从密文 blob 中的元数据中获取用于加密数据的 KMS 密钥。但是，指定您正在使用的 KMS 密钥始终是最佳实践。此做法可确保您使用预期的 KMS 密钥，并防止您意外使用不信任的 KMS 密钥解密加密文字。指定目标 KMS 密钥来重新加密数据。`--destination-key-id` 参数始终为必需项。此示例使用密钥 ARN，但您可以使用任何有效的密钥标识符。将明文输出请求为文本值。`--query` 参数指示 CLI 仅从输出中获取 `Plaintext` 字段的值。`--output` 参数以 text.base64 解码格式返回明文输出并将其保存在文件中。以下示例将 `Plaintext` 参数的值传送（\$1）给 Base64 实用工具，该程序负责对其进行解码。然后，它将解码后的输出重定向（>）到 `ExamplePlaintext` 文件。
在运行此命令之前，请将示例密钥 IDs 替换为 AWS 账户中的有效密钥标识符。
```
aws kms re-encrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--query CiphertextBlob \
--output text | base64 --decode > ExampleReEncryptedFile
```
此命令不生成任何输出。`re-encrypt` 命令的输出经过 base64 解码并保存在文件中。
有关更多信息，请参阅《*AWS 密钥管理服务 API 参考*》[ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html)中的。
**示例 2：使用不同的对称 KMS 密钥重新加密加密消息（Windows 命令提示符）。**
以下 `re-encrypt` 命令示例与前一个示例相同，不同之处在于，它使用 `certutil` 实用工具对明文数据进行 Base64 解码。此过程需要两个命令，如以下示例所示。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。
```
aws kms re-encrypt ^
--ciphertext-blob fileb://ExampleEncryptedFile ^
--source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
--destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 ^
--query CiphertextBlob ^
--output text > ExampleReEncryptedFile.base64
```
然后使用 `certutil` 实用工具
```
certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile
```
输出：
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
有关更多信息，请参阅《*AWS 密钥管理服务 API 参考*》[ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html)中的。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ReEncrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/re-encrypt.html)*中的。
### `retire-grant`
以下代码示例演示了如何使用 `retire-grant`。
**AWS CLI**
**停用对客户主密钥的授权**
以下 `retire-grant` 示例从 KMS 密钥中删除授权。
以下示例命令指定 `grant-id` 和 `key-id` 参数。`key-id` 参数值必须为 KMS 密钥的密钥 ARN。
```
aws kms retire-grant \
--grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
此命令不生成任何输出。要确认授权是否已停用，请使用 `list-grants` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[停用和撤销授权](https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[RetireGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/retire-grant.html)*中的。
### `revoke-grant`
以下代码示例演示了如何使用 `revoke-grant`。
**AWS CLI**
**撤销对客户主密钥的授权**
以下 `revoke-grant` 示例从 KMS 密钥中删除授权。以下示例命令指定 `grant-id` 和 `key-id` 参数。`key-id` 参数的值可以是 KMS 密钥的密钥 ID 或密钥 ARN。
```
aws kms revoke-grant \
--grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
此命令不生成任何输出。要确认授权是否已撤销，请使用 `list-grants` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[停用和撤销授权](https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[RevokeGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/revoke-grant.html)*中的。
### `rotate-key-on-demand`
以下代码示例演示了如何使用 `rotate-key-on-demand`。
**AWS CLI**
**执行按需轮换 KMS 密钥**
以下 `rotate-key-on-demand` 示例立即启动指定 KMS 密钥的密钥材料轮换。
```
aws kms rotate-key-on-demand \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
输出：
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[如何执行按需密钥轮换](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotating-keys-on-demand)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[RotateKeyOnDemand](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/rotate-key-on-demand.html)*中的。
### `schedule-key-deletion`
以下代码示例演示了如何使用 `schedule-key-deletion`。
**AWS CLI**
**计划删除客户托管的 KMS 密钥**
以下 `schedule-key-deletion` 示例计划在 15 天后删除指定的客户托管 KMS 密钥。
`--key-id` 参数识别 KMS 密钥。此示例使用密钥 ARN 值，但您可以使用 KMS 密钥的密钥 ID 或 ARN。`--pending-window-in-days` 参数指定 7-30 天的等待期限。默认的等待期限为 30 天。此示例指定的值为 15，表示在命令完成 15 天后永久删除 KMS 密钥。 AWS
```
aws kms schedule-key-deletion \
--key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--pending-window-in-days 15
```
响应包括密钥 ARN、密钥状态、等待期（`PendingWindowInDays`）和删除日期（以 Unix 时间表示）。要以当地时间查看删除日期，请使用 AWS KMS 控制台。无法在加密操作中使用密钥状态为 `PendingDeletion` 的 KMS 密钥。
```
{
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"DeletionDate": "2022-06-18T23:43:51.272000+00:00",
"KeyState": "PendingDeletion",
"PendingWindowInDays": 15
}
```
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[删除密钥](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[ScheduleKeyDeletion](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/schedule-key-deletion.html)*中的。
### `sign`
以下代码示例演示了如何使用 `sign`。
**AWS CLI**
**示例 1：为消息生成数字签名**
以下 `sign` 示例为一条短消息生成加密签名。该命令的输出包括一个 base-64 编码的 `Signature` 字段，您可以使用 `verify` 命令对其进行验证。
您必须指定要签名的消息以及您的非对称 KMS 密钥支持的签名算法。要获取 KMS 密钥的签名算法，请使用 `describe-key` 命令。
在 AWS CLI v2 中，`message`参数的值必须采用 Base64 编码。或者，您可以将消息保存在文件中并使用`fileb://`前缀，它告诉 AWS CLI 从文件中读取二进制数据。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。密钥 ID 必须表示密钥用法为 SIGN\$1VERIFY 的非对称 KMS 密钥。
```
msg=(echo 'Hello World' | base64)
aws kms sign \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://UnsignedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256
```
输出：
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Signature": "ABCDEFhpyVYyTxbafE74ccSvEJLJr3zuoV1Hfymz4qv+/fxmxNLA7SE1SiF8lHw80fKZZ3bJ...",
"SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}
```
有关在 AWS KMS 中使用非对称 KMS 密钥的更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密*钥。
**示例 2：将数字签名保存在文件中（Linux 和 macOS）**
以下 `sign` 示例为一条存储在本地文件中的短消息生成加密签名。该命令还会从响应中获取`Signature`属性，Base64 对其进行解码并将其保存在文件中。 ExampleSignature 您可以在验证签名的 `verify` 命令中使用该签名文件。
`sign` 命令需要一条 Base64 编码的消息和您的非对称 KMS 密钥支持的签名算法。要获取 KMS 密钥支持的签名算法，请使用 `describe-key` 命令。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。密钥 ID 必须表示密钥用法为 SIGN\$1VERIFY 的非对称 KMS 密钥。
```
echo 'hello world' | base64 > EncodedMessage
aws kms sign \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
--output text \
--query Signature | base64 --decode > ExampleSignature
```
此命令不生成任何输出。此示例提取输出的 `Signature` 属性并将其保存在文件中。
有关在 AWS KMS 中使用非对称 KMS 密钥的更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的非对称AWS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)*密*钥。
+ 有关 API 详细信息，请参阅《AWS CLI 命令参考》**中的 [Sign](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/sign.html)。
### `tag-resource`
以下代码示例演示了如何使用 `tag-resource`。
**AWS CLI**
**为 KMS 密钥添加标签**
以下 `tag-resource` 示例为客户托管的 KMS 密钥添加 `"Purpose":"Test"` 和 `"Dept":"IT"` 标签。您可以使用此类标签来标记 KMS 密钥并创建 KMS 密钥类别以进行权限管理和审计。
要指定 KMS 密钥，请使用 `key-id` 参数。此示例使用密钥 ID 值，但您可以在此命令中使用密钥 ID 或密钥 ARN。
```
aws kms tag-resource \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--tags TagKey='Purpose',TagValue='Test' TagKey='Dept',TagValue='IT'
```
此命令不生成任何输出。要查看 AWS KMS KMS 密钥上的标签，请使用`list-resource-tags`命令。
有关在 AWS KMS 中使用标签的更多信息，请参阅《[密钥*管理服务开发人员指南》中的为密AWS 钥*添加](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html)标签。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[TagResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/tag-resource.html)*中的。
### `untag-resource`
以下代码示例演示了如何使用 `untag-resource`。
**AWS CLI**
**从 KMS 密钥中删除标签**
以下 `untag-resource` 示例从客户托管的 KMS 密钥中删除具有 `"Purpose"` 键的标签。
要指定 KMS 密钥，请使用 `key-id` 参数。此示例使用密钥 ID 值，但您可以在此命令中使用密钥 ID 或密钥 ARN。在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。
```
aws kms untag-resource \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--tag-key 'Purpose'
```
此命令不生成任何输出。要查看 AWS KMS KMS 密钥上的标签，请使用`list-resource-tags`命令。
有关在 AWS KMS 中使用标签的更多信息，请参阅《[密钥*管理服务开发人员指南》中的为密AWS 钥*添加](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html)标签。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[UntagResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/untag-resource.html)*中的。
### `update-alias`
以下代码示例演示了如何使用 `update-alias`。
**AWS CLI**
**将别名与其他 KMS 密钥关联**
以下 `update-alias` 示例将别名 `alias/test-key` 与其他 KMS 密钥关联起来。
`--alias-name` 参数指定别名。别名名称值必须以 `alias/` 开头。`--target-key-id` 参数指定要与别名关联的 KMS 密钥。您不需要为别名指定当前 KMS 密钥。
```
aws kms update-alias \
--alias-name alias/test-key \
--target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
此命令不生成任何输出。要查找别名，请使用 `list-aliases` 命令。
有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[更新别名](https://docs.aws.amazon.com/kms/latest/developerguide/alias-manage.html#alias-update)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[UpdateAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-alias.html)*中的。
### `update-custom-key-store`
以下代码示例演示了如何使用 `update-custom-key-store`。
**AWS CLI**
**示例 1：编辑自定义密钥存储的友好名称**
以下 `update-custom-key-store` 示例更改自定义密钥存储的名称。此示例适用于 AWS CloudHSM 密钥存储库或外部密钥存储库。
使用 `custom-key-store-id` 来标识密钥存储。使用 `new-custom-key-store-name` 参数指定新的友好名称。
要更新 AWS CloudHSM 密钥库的友好名称，必须先断开密钥库的连接，例如使用命令。`disconnect-custom-key-store`在连接或断连外部密钥存储的情况下，都可以更新其友好名称。要查找自定义密钥存储的连接状态，请使用 `describe-custom-key-store` 命令。
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--new-custom-key-store-name ExampleKeyStore
```
此命令不返回任何数据。要验证此命令是否有效，请使用 `describe-custom-key-stores` 命令。
*有关更新 AWS CloudHSM 密钥库的更多信息，请参阅《密钥管理服务开发者指南》中的[编辑 AWS CloudHSM 密钥库](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html)设置。AWS *
有关更新外部密钥存储的更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[编辑外部密钥存储属性](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html)。
**示例 2：编辑 CloudH AWS SM 密钥库的 kmsuser 密码**
以下 `update-custom-key-store` 示例将 `kmsuser` 密码的值更新为与指定密钥存储关联的 CloudHSM 集群中 `kmsuser` 的当前密码。此命令不会更改集群的 `kmsuser` 密码。它只是告诉 AWS KMS 当前的密码。如果 KMS 没有当前`kmsuser`密码，则无法连接到 AWS CloudHSM 密钥存储库。
**注意：**在更新 AWS CloudHSM 密钥库之前，必须将其断开连接。使用 `disconnect-custom-key-store` 命令。命令完成后，您可以重新连接 Cloud AWS HSM 密钥存储库。使用 `connect-custom-key-store` 命令。
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--key-store-password ExamplePassword
```
此命令不返回任何输出。要验证更改是否生效，请使用 `describe-custom-key-stores` 命令。
*有关更新 AWS CloudHSM 密钥库的更多信息，请参阅《密钥管理服务开发者指南》中的[编辑 AWS CloudHSM 密钥库](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html)设置。AWS *
**示例 3：编辑 AWS CloudHSM 密钥库的 CloudHSM 集群 AWS **
以下示例将与 AWS CloudHSM 密钥库关联的 AWS CloudHSM 集群更改为相关集群，例如同一集群的不同备份。
**注意：**在更新 AWS CloudHSM 密钥库之前，必须将其断开连接。使用 `disconnect-custom-key-store` 命令。命令完成后，您可以重新连接 Cloud AWS HSM 密钥存储库。使用 `connect-custom-key-store` 命令。
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--cloud-hsm-cluster-id cluster-1a23b4cdefg
```
此命令不返回任何输出。要验证更改是否生效，请使用 `describe-custom-key-stores` 命令。
*有关更新 AWS CloudHSM 密钥库的更多信息，请参阅《密钥管理服务开发者指南》中的[编辑 AWS CloudHSM 密钥库](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html)设置。AWS *
**示例 4：编辑外部密钥存储的代理身份验证凭证**
以下示例更新您的外部密钥存储的代理身份验证凭证。您必须同时指定 `raw-secret-access-key` 和 `access-key-id`，即使只是更改其中一个值。您可以使用此功能修复无效凭证，或者在外部密钥存储代理轮换凭证时更改凭证。
在您的外部密钥存储上建立 AWS KMS 的代理身份验证凭据。然后使用此命令向 AWS KMS 提供凭证。 AWS KMS 使用此凭证对您的外部密钥存储代理的请求进行签名。
在连接或断开连接外部密钥存储的情况下，都可以更新代理身份验证凭证。要查找自定义密钥存储的连接状态，请使用 `describe-custom-key-store` 命令。
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
此命令不返回任何输出。要验证更改是否生效，请使用 `describe-custom-key-stores` 命令。
有关更新外部密钥存储的更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[编辑外部密钥存储属性](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html)。
**示例 5：编辑外部密钥存储的代理连接**
以下示例将外部密钥存储代理连接选项从公有端点连接更改为 VPC 端点服务连接。除了更改 `xks-proxy-connectivity` 值外，您还必须更改 `xks-proxy-uri-endpoint` 值，以反映与 VPC 端点服务关联的私有 DNS 名称。您还必须添加一个 `xks-proxy-vpc-endpoint-service-name` 值。
**注意：**在更新一个外部存储的代理连接之前，必须断开其连接。使用 `disconnect-custom-key-store` 命令。命令完成后，您可以使用 `connect-custom-key-store` 命令重新连接该外部密钥存储。
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
--xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example"
```
此命令不返回任何输出。要验证更改是否生效，请使用 `describe-custom-key-stores` 命令。
有关更新外部密钥存储的更多信息，请参阅《AWS 密钥管理服务开发人员指南》**中的[编辑外部密钥存储属性](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html)。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[UpdateCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-custom-key-store.html)*中的。
### `update-key-description`
以下代码示例演示了如何使用 `update-key-description`。
**AWS CLI**
**示例 1：为客户托管的 KMS 密钥添加或更改描述**
以下 `update-key-description` 示例为客户托管的 KMS 密钥添加描述。您可以使用同样的命令更改现有描述。
`--key-id` 参数在该命令中标识 KMS 密钥。此示例使用密钥 ARN 值，但您可以使用 KMS 密钥的密钥 ID 或密钥 ARN。`--description` 参数指定新的描述。此参数的值替换 KMS 密钥的当前描述（如有）。
```
aws kms update-key-description \
--key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--description "IT Department test key"
```
此命令不生成任何输出。要查看 KMS 密钥的描述，请使用 `describe-key` 命令。
有关更多信息，请参阅《*AWS 密钥管理服务 API 参考*》[UpdateKeyDescription](https://docs.aws.amazon.com/cli/latest/reference/kms/update-key-description.html)中的。
**示例 2：删除客户托管的 KMS 密钥的描述**
以下 `update-key-description` 示例删除客户托管的 KMS 密钥的描述。
`--key-id` 参数在该命令中标识 KMS 密钥。此示例使用密钥 ID 值，但您可以使用 KMS 密钥的密钥 ID 或密钥 ARN。采用空字符串值（''）的 `--description` 参数会删除现有描述。
```
aws kms update-key-description \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--description ''
```
此命令不生成任何输出。要查看 KMS 密钥的描述，请使用 describe-key 命令。
有关更多信息，请参阅《*AWS 密钥管理服务 API 参考*》[UpdateKeyDescription](https://docs.aws.amazon.com/cli/latest/reference/kms/update-key-description.html)中的。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[UpdateKeyDescription](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-key-description.html)*中的。
### `verify-mac`
以下代码示例演示了如何使用 `verify-mac`。
**AWS CLI**
**示例 1：验证 HMAC**
以下 `verify-mac` 命令验证特定消息、HMAC KMS 密钥和 MAC 算法的 HMAC。响应中的值为 “true” 表示 HMAC 有效。 MacValid
在 AWS CLI v2 中，`message`参数的值必须采用 Base64 编码。或者，您可以将消息保存在文件中并使用`fileb://`前缀，它告诉 AWS CLI 从文件中读取二进制数据。
您指定的 MAC 不得采用 base64 编码。如需解码 `generate-mac` 命令返回的 MAC 的帮助，请参阅 `generate-mac` 命令示例。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。密钥 ID 必须表示密钥用法为 `GENERATE_VERIFY_MAC` 的 HMAC KMS 密钥。
```
msg=(echo 'Hello World' | base64)
aws kms verify-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://Message \
--mac-algorithm HMAC_SHA_384 \
--mac fileb://ExampleMac
```
输出：
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"MacValid": true,
"MacAlgorithm": "HMAC_SHA_384"
}
```
有关在 AWS KMS 中使用 HMAC KMS 密钥的更多信息，请参阅《[密钥管理服务开发人员指南》中的 AWS KMS 中的 HMA](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) *C AWS 密*钥。
+ 有关 API 的详细信息，请参阅*AWS CLI 命令参考[VerifyMac](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/verify-mac.html)*中的。
### `verify`
以下代码示例演示了如何使用 `verify`。
**AWS CLI**
**验证数字签名**
以下 `verify` 命令验证一条 Base64 编码短消息的加密签名。密钥 ID、消息、消息类型和签名算法必须与用于签名该消息的相同。
在 AWS CLI v2 中，`message`参数的值必须采用 Base64 编码。或者，您可以将消息保存在文件中并使用`fileb://`前缀，它告诉 AWS CLI 从文件中读取二进制数据。
您指定的签名不得采用 base64 编码。如需解码 `sign` 命令返回的签名的帮助，请参阅 `sign` 命令示例。
该命令的输出包括一个布尔 `SignatureValid` 字段，表示签名已通过验证。如果签名验证失败，`verify` 命令也会失败。
在运行此命令之前，请将示例密钥 ID 替换为 AWS 账户中的有效密钥 ID。
```
aws kms verify \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
--signature fileb://ExampleSignature
```
输出：
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"SignatureValid": true,
"SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}
```
有关在 KMS 中 AWS 使用非对称 KMS 密钥的更多信息，请参阅[密钥*管理服务开发人员*指南中的AWS 使用非对称密钥](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)。
+ 有关 API 详细信息，请参阅《AWS CLI 命令参考》**中的 [Verify](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/verify.html)。