使用 AWS CLI 的 AWS KMS示例

取消对客户托管的 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 密钥管理服务开发人员指南》中的预定和取消密钥删除。

连接自定义密钥存储

以下 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 密钥管理服务开发人员指南》中的连接和断开连接 AWS CloudHSM 密钥存储。

有关连接外部密钥存储的信息，请参阅《AWS 密钥管理服务开发人员指南》中的连接和断开连接外部密钥存储。

为 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 密钥管理服务开发人员指南》中的使用别名。

示例 1：创建 AWS CloudHSM 密钥存储

以下 create-custom-key-store 示例使用所需参数创建由 AWS CloudHSM 集群支持的 AWS CloudHSM 密钥存储。您也可以添加 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 密钥存储。

示例 2：创建使用公有端点连接的外部密钥存储

以下 create-custom-key-store 示例创建一个外部密钥存储（XKS），它通过互联网与 AWS KMS 通信。

在此示例中，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 密钥管理服务开发人员指南》中的创建外部密钥存储。

示例 3：创建使用 VPC 端点服务连接的外部密钥存储

以下 create-custom-key-store 示例创建一个外部密钥存储（XKS），它使用 Amazon VPC 端点服务与 AWS KMS 通信。

注意：如果使用 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 密钥管理服务开发人员指南》中的创建外部密钥存储。

创建授权

以下 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": "<grant token here>"
}

要查看有关授权的详细信息，请使用 list-grants 命令。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的 AWS KMS 中的授权。

示例 1：在 AWS KMS 中创建客户托管 KMS 密钥

以下 create-key 示例创建对称加密 KMS 密钥。

要创建基本 KMS 密钥（对称加密密钥），您无需指定任何参数。这些参数的默认值会创建对称加密密钥。

由于此命令未指定密钥策略，因此，KMS 密钥将获得以编程方式创建的 KMS 密钥的默认密钥策略。要查看密钥策略，请使用 get-key-policy 命令。要更改密钥策略，请使用 put-key-policy 命令。

aws kms create-key

create-key 命令会返回密钥元数据，包括新 KMS 密钥的密钥 ID 和 ARN。您可以使用这些值来识别其他 AWS KMS 操作中的 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",
        "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 密钥管理服务开发人员指南》中的创建密钥。

示例 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 密钥管理服务开发人员指南》中的 AWS KMS 中的非对称密钥。

示例 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 密钥管理服务开发人员指南》中的 AWS KMS 中的非对称密钥。

示例 4：创建 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 密钥管理服务开发人员指南》中的 AWS KMS 中的 HMAC 密钥。

示例 4：创建多区域主 KMS 密钥

以下 create-key 示例创建多区域主对称加密密钥。由于所有参数的默认值都会创建对称加密密钥，因此，此 KMS 密钥只需要 --multi-region 参数。在 AWS CLI 中，要指示布尔参数为 true，只需指定参数名称即可。

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",
        "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 密钥管理服务开发人员指南》中的 AWS KMS 中的非对称密钥。

示例 5：为导入的密钥材料创建 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 密钥管理服务开发人员指南》中的将密钥材料导入到 AWS KMS 密钥中。

示例 6：在 AWS CloudHSM 密钥存储中创建 KMS 密钥

以下 create-key 示例在指定的 AWS CloudHSM 密钥存储中创建一个 KMS 密钥。该操作在 AWS KMS 中创建 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 密钥存储。

示例 7：在外部密钥存储中创建 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 密钥管理服务开发人员指南》中的外部密钥存储。

示例 1：使用对称 KMS 密钥解密加密消息（Linux 和 macOS）

以下 decrypt 命令示例演示了使用 AWS CLI 解密数据的推荐方法。此版本演示了如何使用对称 KMS 密钥解密数据。

在文件中提供加密文字。在 --ciphertext-blob 参数的值中，使用 fileb:// 前缀，它将指示 CLI 从二进制文件中读取数据。如果文件不在当前目录中，请键入文件的完整路径。有关从文件读取 AWS CLI 参数值的更多信息，请参阅以下内容：《AWS 命令行界面用户指南》中的“从文件中加载 AWS CLI 参数”<https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html>，以及《AWS 命令行工具博客》中的“本地文件参数最佳实践”<https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/>。指定 KMS 密钥来解密加密文字。使用对称 KMS 密钥进行解密时不需要 --key-id参数。AWSKMS 可以获取用于加密加密文字元数据中数据的 KMS 密钥的密钥 ID。但是，指定您正在使用的 KMS 密钥始终是最佳实践。此做法可确保您使用预期的 KMS 密钥，并防止您意外使用不信任的 KMS 密钥解密加密文字。以文本值请求明文输出。--query 参数指示 CLI 仅从输出中获取 Plaintext 字段的值。--output 参数以 text.base64 解码格式返回明文输出并将其保存在文件中。以下示例将 Plaintext 参数的值传送（|）给 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 参考》中的解密。

示例 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 参考》中的解密。

示例 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 密钥管理服务开发人员指南》中的 AWS KMS 中的非对称密钥。

删除 AWS KMS 别名

以下 delete-alias 示例将删除别名 alias/example-alias。别名名称必须以 alias/ 开头。

aws kms delete-alias \
    --alias-name alias/example-alias

此命令不生成任何输出。要查找别名，请使用 list-aliases 命令。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的删除别名。

删除自定义密钥存储

以下 delete-custom-key-store 示例删除指定自定义密钥存储。

删除 AWS CloudHSM 密钥存储不会影响关联的 CloudHSM 集群。删除外部密钥存储不会影响关联的外部密钥存储代理、外部密钥管理器或外部密钥。

注意：要删除一个自定义密钥存储，必须先计划删除该自定义密钥存储中的所有 KMS 密钥，然后等待这些 KMS 密钥被删除。之后，必须断开连接该自定义密钥存储。有关在自定义密钥存储中查找 KMS 密钥的帮助，请参阅《AWS 密钥管理服务开发人员指南》中的删除 AWS CloudHSM 密钥存储（API）。

delete-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

此命令不返回任何输出。要确认是否删除了该自定义密钥存储，请使用 describe-custom-key-stores 命令。

有关删除 AWS CloudHSM 密钥存储的信息，请参阅《AWS 密钥管理服务开发人员指南》中的删除 AWS CloudHSM 密钥存储。

有关删除外部密钥存储的信息，请参阅《AWS 密钥管理服务开发人员指南》中的删除外部密钥存储。

从 KMS 密钥中删除导入的密钥材料

以下 delete-imported-key-material 示例删除导入到 KMS 密钥的密钥材料。

aws kms delete-imported-key-material \
   --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

此命令不生成任何输出。要验证密钥材料是否已被删除，请使用 describe-key 命令查找密钥状态 PendingImport 或 PendingDeletion。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的“删除导入的密钥材料”<https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-delete-key-material.html>。

派生共享密钥

以下 derive-shared-secret 示例使用密钥协议算法派生共享密钥。

您必须使用 NIST 推荐的非对称椭圆曲线（ECC）或 SM2（仅限中国区域）KMS 密钥对且 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。

示例 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": "<certificate appears here>"
        }
    ]
}

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的查看 AWS CloudHSM 密钥存储。

示例 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 密钥管理服务开发人员指南》中的查看外部密钥存储。

示例 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 密钥管理服务开发人员指南》中的查看外部密钥存储。

示例 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",
        "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 密钥管理服务开发人员指南》中的查看密钥。

示例 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",
        "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
    }
}

禁用自动轮换 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 密钥管理服务开发人员指南》中的轮换密钥。

暂时禁用 KMS 密钥

以下示例使用 disable-key 命令禁用客户托管的 KMS 密钥。要重新启用 KMS 密钥，请使用 enable-key 命令。

aws kms disable-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

此命令不生成任何输出。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的启用和禁用密钥。

断开连接自定义密钥存储

以下 disconnect-custom-key-store 示例断开一个自定义密钥存储与其 AWS CloudHSM 集群的连接。您可以断开连接一个密钥存储，以便解决问题、更新其设置或防止该密钥存储中的 KMS 密钥被用于加密操作。

此命令对于所有自定义密钥存储都是一样的，包括 AWS CloudHSM 密钥存储和外部密钥存储。

在运行此命令之前，请将示例自定义密钥存储 ID 替换为有效 ID。

$ aws kms disconnect-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

此命令不生成任何输出。要验证命令是否有效，请使用 describe-custom-key-stores 命令。

有关断开连接 AWS CloudHSM 密钥存储的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的连接和断开连接 AWS CloudHSM 密钥存储。

有关断开连接外部密钥存储的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的连接和断开连接外部密钥存储。

启用自动轮换 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 密钥管理服务开发人员指南》中的轮换密钥。

启用 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 密钥管理服务开发人员指南》中的启用和禁用密钥。

示例 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://，以指示 AWS CLI 从文件中读取二进制数据。如果文件不在当前目录中，请键入文件的完整路径。例如：fileb:///var/tmp/ExamplePlaintextFile 或 fileb://C:\Temp\ExamplePlaintextFile。有关从文件读取 AWS CLI 参数值的更多信息，请参阅以下内容：《AWS 命令行界面用户指南》中的从文件加载参数，以及 AWS 命令行工具博客上的本地文件参数最佳实践。使用 --output 和 --query 参数控制命令的输出。这些参数从命令的输出中提取称为加密文字 的加密数据。有关控制输出的更多信息，请参阅《AWS 命令行界面用户指南》中的控制命令输出。使用 base64 实用程序将提取的输出解码为二进制数据。成功的 encrypt 命令返回的加密文字是 base64 编码的文本。必须先解码此文本，然后才能使用 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:// 前缀，因为它指示 AWS CLI 从文件中读取二进制数据。

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

此命令不生成任何输出。

生成 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",
    "KeyPairSpec": "ECC_NIST_P384"
}

PublicKey 和 PrivateKeyCiphertextBlob 以 base64 编码的格式返回。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的数据密钥对。

生成 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",
    "KeyPairSpec": "RSA_2048"
}

PublicKey、PrivateKeyPlaintext 和 PrivateKeyCiphertextBlob 以 base64 编码的格式返回。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的数据密钥对。

生成不带明文密钥的 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_DEFAULT 的 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"
}

CiphertextBlob（加密数据密钥）以 base64 编码的格式返回。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的数据密钥。

示例 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_DEFAULT 的 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",
    "CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogLqPWZconQhwHAIBEIA7d9AC7GeJJM34njQvg4Wf1d5sw0NIo1MrBqZa+YdhV8MrkBQPeac0ReRVNDt9qleAt+SHgIRF8P0H+7U="
}

Plaintext（明文数据密钥）和 CiphertextBlob（加密数据密钥）均以 base64 编码的格式返回。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的“数据密钥”<https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys>。

示例 2：生成 512 位对称数据密钥

以下 generate-data-key 示例请求用于加密和解密的 512 位对称数据密钥。该命令返回一个明文数据密钥以供立即使用和删除，以及以指定 KMS 密钥加密的该数据密钥的副本。您可以安全地将加密的数据密钥与加密的数据一起存储。

要请求 128 或 256 位以外的密钥长度，请使用 number-of-bytes 参数。为了请求 512 位数据密钥，以下示例使用值为 64（字节）的 number-of-bytes 参数。

您指定的 KMS 密钥必须是对称加密 KMS 密钥，即密钥规格值为 SYMMETRIC_DEFAULT 的 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"
}

Plaintext（明文数据密钥）和 CiphertextBlob（加密数据密钥）均以 base64 编码的格式返回。

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的“数据密钥”<https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys>。

示例 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 集群中生成。

本示例使用以下参数和值：

它使用值为 32 的必需 --number-of-bytes 参数来请求 32 字节（256 位）字符串。它使用值为 text 的 --output 参数来指示 AWS CLI 将输出作为文本（而不是 JSON）返回。它使用 --query parameter 从响应中提取 Plaintext 属性的值。它将命令的输出传送（|）到 base64 实用程序，该程序负责对提取的输出进行解码。它使用重定向运算符（>）将解码后的字节字符串保存到 ExampleRandom 文件中。它使用重定向运算符（>）将二进制加密文字保存到文件。

aws kms generate-random \
    --number-of-bytes 32 \
    --output text \
    --query Plaintext | base64 --decode > ExampleRandom

此命令不生成任何输出。

有关更多信息，请参阅《AWS 密钥管理服务 API 参考》中的 GenerateRandom。

示例 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。

将密钥策略从一个 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。

检索 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 密钥管理服务开发人员指南》中的轮换密钥。

获取将密钥材料导入 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": "<public key base64 encoded data>",
    "ImportToken": "<import token base64 encoded data>",
    "ParametersValidTo": 1593893322.32
}

有关更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的下载公钥和导入令牌。

示例 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 密钥管理服务 API 参考》中的使用对称和非对称密钥。

示例 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 密钥管理服务 API 参考》中的使用对称和非对称密钥。

将密钥材料导入 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

此命令不生成任何输出。

有关导入密钥材料的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的导入密钥材料。

示例 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 密钥管理服务开发人员指南》中的使用别名。

查看 AWS KMS 密钥的授权

以下 list-grants 示例显示了您账户中针对 Amazon 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 中的授权。

获取 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 密钥管理服务开发人员指南》中的在 AWS KMS 中使用密钥策略。

检索有关所有已完成的密钥材料轮换的信息

以下 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 密钥管理服务开发人员指南》中的轮换密钥。

获取账户和区域中的 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 密钥管理服务开发人员指南》中的查看密钥。

获取 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 密钥管理服务开发人员指南》中的标记密钥。

查看主体可以停用的授权

以下 list-retirable-grants 示例显示在一个 AWS 账户和区域中，ExampleAdmin 用户可以停用的 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 中的授权。

更改 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 密钥管理服务开发人员指南》中的更改密钥策略。

示例 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 命令行工具博客》中的“本地文件参数最佳实践”<https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/>。指定源 KMS 密钥来解密加密文字。使用对称加密 KMS 密钥进行解密时不需要 --source-key-id 参数。AWSKMS 可以获取用于加密加密文字 Blob 元数据中数据的 KMS 密钥。但是，指定您正在使用的 KMS 密钥始终是最佳实践。此做法可确保您使用预期的 KMS 密钥，并防止您意外使用不信任的 KMS 密钥解密加密文字。指定目标 KMS 密钥来重新加密数据。--destination-key-id 参数始终为必需项。此示例使用密钥 ARN，但您可以使用任何有效的密钥标识符。将明文输出请求为文本值。--query 参数指示 CLI 仅从输出中获取 Plaintext 字段的值。--output 参数以 text.base64 解码格式返回明文输出并将其保存在文件中。以下示例将 Plaintext 参数的值传送（|）给 Base64 实用工具，该程序负责对其进行解码。然后，它将解码后的输出重定向（>）到 ExamplePlaintext 文件。

在运行此命令之前，将示例密钥 ID 替换为您 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>。

停用对客户主密钥的授权

以下 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 密钥管理服务开发人员指南》中的停用和撤销授权。

撤销对客户主密钥的授权

以下 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 密钥管理服务开发人员指南》中的停用和撤销授权。

执行按需轮换 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 密钥管理服务开发人员指南》中的如何执行按需密钥轮换。

计划删除客户托管的 KMS 密钥

以下 schedule-key-deletion 示例计划在 15 天后删除指定的客户托管 KMS 密钥。

--key-id 参数识别 KMS 密钥。此示例使用密钥 ARN 值，但您可以使用 KMS 密钥的密钥 ID 或 ARN。--pending-window-in-days 参数指定 7-30 天的等待期限。默认的等待期限为 30 天。此示例指定的值为 15，用于指示 AWS 在命令完成 15 天后永久删除 KMS 密钥。

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 密钥管理服务开发人员指南》中的删除密钥。

示例 1：为消息生成数字签名

以下 sign 示例为一条短消息生成加密签名。该命令的输出包括一个 base-64 编码的 Signature 字段，您可以使用 verify 命令对其进行验证。

您必须指定要签名的消息以及您的非对称 KMS 密钥支持的签名算法。要获取 KMS 密钥的签名算法，请使用 describe-key 命令。

在 AWS CLI 2.0 中，message 参数的值必须采用 Base64 编码。或者，您可以将消息保存在文件中并使用 fileb:// 前缀，它告诉 AWS CLI 从文件中读取二进制数据。

在运行此命令之前，请将例子中的密钥 ID 替换为您的 AWS 账户中的有效密钥 ID。密钥 ID 必须表示密钥用法为 SIGN_VERIFY 的非对称 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 密钥管理服务开发人员指南》中的 AWS KMS 中的非对称密钥。

示例 2：将数字签名保存在文件中（Linux 和 macOS）

以下 sign 示例为一条存储在本地文件中的短消息生成加密签名。该命令还从响应中获取 Signature 属性，对其进行 Base64 解码并将其保存在 ExampleSignature 文件中。您可以在验证签名的 verify 命令中使用该签名文件。

sign 命令需要一条 Base64 编码的消息和您的非对称 KMS 密钥支持的签名算法。要获取 KMS 密钥支持的签名算法，请使用 describe-key 命令。

在运行此命令之前，请将例子中的密钥 ID 替换为您的 AWS 账户中的有效密钥 ID。密钥 ID 必须表示密钥用法为 SIGN_VERIFY 的非对称 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 密钥管理服务开发人员指南》中的 AWS KMS 中的非对称密钥。

为 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 密钥上的标签，请使用 list-resource-tags 命令。

有关在 AWS KMS 中使用标签的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的标记密钥。

从 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 密钥上的标签，请使用 list-resource-tags 命令。

有关在 AWS KMS 中使用标签的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的标记密钥。

将别名与其他 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 密钥管理服务开发人员指南》中的更新别名。

示例 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 密钥管理服务开发人员指南》中的编辑 AWS CloudHSM 密钥存储设置。

有关更新外部密钥存储的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的编辑外部密钥存储属性。

示例 2：编辑 AWS CloudHSM 密钥存储的 kmsuser 密码

以下 update-custom-key-store 示例将 kmsuser 密码的值更新为与指定密钥存储关联的 CloudHSM 集群中 kmsuser 的当前密码。此命令不会更改集群的 kmsuser 密码。它只是告知 AWS KMS 当前的密码。如果 KMS 没有当前 kmsuser 密码，则无法连接到 AWS CloudHSM 密钥存储。

注意：在更新一个 AWS CloudHSM 密钥存储之前，必须先将其断开连接。使用 disconnect-custom-key-store 命令。命令完成后，您可以重新连接该 AWS CloudHSM 密钥存储。使用 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 密钥管理服务开发人员指南》中的编辑 AWS CloudHSM 密钥存储设置。

示例 3：编辑 AWS CloudHSM 密钥存储的 AWS CloudHSM 集群

以下示例将与一个 AWS CloudHSM 密钥存储关联的 AWS CloudHSM 集群更改为一个相关集群，例如同一集群的其他备份。

注意：在更新一个 AWS CloudHSM 密钥存储之前，必须先将其断开连接。使用 disconnect-custom-key-store 命令。命令完成后，您可以重新连接该 AWS CloudHSM 密钥存储。使用 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 密钥管理服务开发人员指南》中的编辑 AWS CloudHSM 密钥存储设置。

示例 4：编辑外部密钥存储的代理身份验证凭证

以下示例更新您的外部密钥存储的代理身份验证凭证。您必须同时指定 raw-secret-access-key 和 access-key-id，即使只是更改其中一个值。您可以使用此功能修复无效凭证，或者在外部密钥存储代理轮换凭证时更改凭证。

在外部密钥存储上为 AWS KMS 建立代理身份验证凭证。然后使用此命令向 AWS KMS 提供凭证。AWSKMS 使用此凭证来签署其对于您的外部密钥存储代理的请求。

在连接或断开连接外部密钥存储的情况下，都可以更新代理身份验证凭证。要查找自定义密钥存储的连接状态，请使用 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 密钥管理服务开发人员指南》中的编辑外部密钥存储属性。

示例 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 密钥管理服务开发人员指南》中的编辑外部密钥存储属性。

示例 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。

示例 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。

验证数字签名

以下 verify 示例验证一条 Base64 编码短消息的加密签名。密钥 ID、消息、消息类型和签名算法必须与用于签名该消息的相同。您指定的签名不得采用 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"
}

有关在 AWS KMS 中使用非对称 KMS 密钥的更多信息，请参阅《AWS 密钥管理服务开发人员指南》中的使用非对称密钥。