对自定义密钥存储进行故障排除

AWS CloudHSM 密钥存储被设计为可用且有弹性。不过，为了让 AWS CloudHSM 密钥存储正常运行，您必须修复存在的一些错误情况。

如何修复不可用的 KMS 密钥

AWS CloudHSM 密钥存储中 AWS KMS keys 的密钥状态通常为 Enabled。与所有 KMS 密钥相似，当您禁用 AWS CloudHSM 密钥存储中的 KMS 密钥或者计划删除这些密钥时，密钥状态会发生变化。但是，与其他 KMS 密钥不同，自定义密钥存储中的 KMS 密钥还可具有密钥状态 Unavailable。

密钥状态 Unavailable 表示 KMS 密钥位于被故意断开连接的自定义密钥存储中，并且尝试重新连接该集群（如果有）失败。当某个 KMS 密钥不可用时，您可以查看和管理该 KMS 密钥，但不能将其用于加密操作。

要查找 KMS 密钥的密钥状态，请在 Customer managed keys（客户托管密钥）页面上，查看 KMS 密钥的 Status（状态）字段。或者，使用 DescribeKey 操作并查看响应中的 KeyState 元素。有关更多信息，请参阅 识别和查看密钥。

已断开的自定义密钥存储中的 KMS 密钥的密钥状态将为 Unavailable 或 PendingDeletion。计划从自定义密钥存储中删除的 KMS 密钥的密钥状态为 Pending Deletion，即使自定义密钥存储已断开连接也是如此。这使您可以取消计划的密钥删除而无需重新连接自定义密钥存储。

要修复不可用的 KMS 密钥，请重新连接自定义密钥存储。重新连接自定义密钥存储后，自定义密钥存储中的 KMS 密钥的密钥状态将自动还原到之前的状态，例如 Enabled 或 Disabled。待删除的 KMS 密钥将保持 PendingDeletion 状态。但是，当问题仍然存在时，启用和禁用不可用的 KMS 密钥不会更改其密钥状态。仅当密钥变得可用时，启用或禁用操作才会生效。

如需帮助解决失败的连接，请参阅如何修复连接故障。

如何修复失败的 KMS 密钥

在 AWS CloudHSM 密钥存储中创建和使用 KMS 密钥的问题可能由 AWS CloudHSM 密钥存储、其关联的 AWS CloudHSM 集群、KMS 密钥或其密钥材料导致。

当某个 AWS CloudHSM 密钥存储与其 AWS CloudHSM 集群断开连接时，该自定义密钥存储中 KMS 密钥的密钥状态为 Unavailable。在断开的 AWS CloudHSM 密钥存储中创建 KMS 密钥的所有请求都将返回 CustomKeyStoreInvalidStateException 异常。所有加密、解密、重新加密或生成数据密钥的请求都将返回 KMSInvalidStateException 异常。要修复该问题，请重新连接 AWS CloudHSM 密钥存储。

但是，您使用 AWS CloudHSM 密钥存储 KMS 密钥进行加密操作的尝试可能会失败，即使其密钥状态为 Enabled 并且 AWS CloudHSM 密钥存储的连接状态为 Connected 也是如此。这可能由以下任一情况导致。

如何修复连接故障

如果您尝试连接 AWS CloudHSM 密钥存储到其 AWS CloudHSM 集群，但操作失败，则 AWS CloudHSM 密钥存储的连接状态将更改为 FAILED。要查找 AWS CloudHSM 密钥存储的连接状态，请使用 AWS KMS 控制台或 DescribeCustomKeyStores 操作。

另外，由于容易检测到集群配置错误，一些连接尝试会很快失败。在这种情况下，连接状态仍为 DISCONNECTED。这些失败将返回错误消息或例外来说明尝试失败的原因。查看例外描述和集群要求，纠正问题，更新 AWS CloudHSM 密钥存储（如有必要）并尝试重新连接。

当连接状态为 FAILED 时，运行 DescribeCustomKeyStores 操作并查看响应中的 ConnectionErrorCode 元素。

如何响应加密操作失败

在自定义密钥存储中使用 KMS 密钥的加密操作可能会失败，并显示 KMSInvalidStateException。以下错误消息可能附带 KMSInvalidStateException。

如何修复无效的 kmsuser 凭证

连接 AWS CloudHSM 密钥存储时，AWS KMS 会以 kmsuser 加密用户（CU）身份登录到关联的 AWS CloudHSM 集群。在 AWS CloudHSM 密钥存储断开之前，它将保持登录状态。DescribeCustomKeyStores 响应将显示 ConnectionState FAILED 和 ConnectionErrorCode 值 INVALID_CREDENTIALS，如以下示例所示。

如果您断开 AWS CloudHSM 密钥存储并更改 kmsuser 密码，AWS KMS 将无法使用 kmsuser CU 账户的凭证登录到 AWS CloudHSM 集群。因此，所有连接 AWS CloudHSM 密钥存储的尝试都将失败。DescribeCustomKeyStores 响应显示 ConnectionState 值 FAILED 以及 ConnectionErrorCode 值 INVALID_CREDENTIALS，如以下示例中所示。

$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
   "CustomKeyStores": [
      "CloudHsmClusterId": "cluster-1a23b4cdefg",
      "ConnectionErrorCode": "INVALID_CREDENTIALS"
      "CustomKeyStoreId": "cks-1234567890abcdef0",
      "CustomKeyStoreName": "ExampleKeyStore",
      "TrustAnchorCertificate": "<certificate string appears here>",
      "CreationDate": "1.499288695918E9",
      "ConnectionState": "FAILED"
   ],
}

此外，在使用不正确的密码登录到集群的尝试失败五次后，AWS CloudHSM 将锁定用户账户。要登录到集群，您必须更改账户密码。

如果 AWS KMS 在尝试以 kmsuser CU 身份登录到集群时获得锁定响应，连接 AWS CloudHSM 密钥存储的请求将失败。DescribeCustomKeyStores 响应包含 ConnectionState FAILED 和 ConnectionErrorCode 值 USER_LOCKED_OUT，如以下示例所示。

$ aws kms describe-custom-key-stores --custom-key-store-name ExampleKeyStore
{
   "CustomKeyStores": [
      "CloudHsmClusterId": "cluster-1a23b4cdefg",
      "ConnectionErrorCode": "USER_LOCKED_OUT"
      "CustomKeyStoreId": "cks-1234567890abcdef0",
      "CustomKeyStoreName": "ExampleKeyStore",
      "TrustAnchorCertificate": "<certificate string appears here>",
      "CreationDate": "1.499288695918E9",
      "ConnectionState": "FAILED"
   ],
}

要修复上述任一状况，请使用以下过程。

如何删除孤立密钥材料

在计划从 AWS CloudHSM 密钥存储中删除 KMS 密钥后，您可能需要从关联的 AWS CloudHSM 集群中手动删除对应的密钥材料。

当您在 AWS CloudHSM 密钥存储中创建 KMS 密钥时，AWS KMS 将在 AWS KMS 中创建 KMS 密钥元数据并在关联的 AWS CloudHSM 集群中生成密钥材料。当您计划在 AWS CloudHSM 密钥存储中删除 KMS 密钥时，在等待期过后，AWS KMS 将删除 KMS 密钥元数据。然后，AWS KMS 将尽可能从 AWS CloudHSM 集群中删除对应的密钥材料。如果 AWS KMS 无法访问集群（例如与 AWS CloudHSM 密钥存储断开连接或 kmsuser 密码更改），尝试可能会失败。AWS KMS 不会尝试从集群备份中删除密钥材料。

AWS KMS 会报告其尝试从 AWS CloudTrail 日志 DeleteKey 事件条目中的集群中删除密钥材料的结果。它会在 additionalEventData 元素的 backingKeysDeletionStatus 元素中显示，如以下示例条目所示。该条目还包含 KMS 密钥 ARN、AWS CloudHSM 集群 ID 和密钥材料的ID（backing-key-id）。

{
    "eventVersion": "1.08",
    "userIdentity": {
        "accountId": "111122223333",
        "invokedBy": "AWS Internal"
    },
    "eventTime": "2021-12-10T14:23:51Z",
    "eventSource": "kms.amazonaws.com",
    "eventName": "DeleteKey",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "AWS Internal",
    "requestParameters": null,
    "responseElements":  {
        "keyId":"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    },
    "additionalEventData": {
        "customKeyStoreId": "cks-1234567890abcdef0",
        "clusterId": "cluster-1a23b4cdefg",
        "backingKeys": "[{\"backingKeyId\":\"backing-key-id\"}]",
        "backingKeysDeletionStatus": "[{\"backingKeyId\":\"backing-key-id\",\"deletionStatus\":\"FAILURE\"}]"
    },
    "eventID": "c21f1f47-f52b-4ffe-bff0-6d994403cf40",
    "readOnly": false,
    "resources": [
        {
            "accountId": "111122223333",
            "type": "AWS::KMS::Key",
            "ARN": "arn:aws:kms:eu-west-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ],
    "eventType": "AwsServiceEvent",
    "recipientAccountId": "111122223333",
    "managementEvent": true,
    "eventCategory": "Management"
}

以下过程演示如何从关联的 AWS CloudHSM 集群中删除孤立密钥材料。

如何恢复 KMS 密钥的已删除密钥材料

如果删除了 AWS KMS key 的密钥材料，则 KMS 密钥不可用，并且在 KMS 密钥下加密的所有密文都无法解密。如果从关联的 AWS CloudHSM 集群中删除了 AWS CloudHSM 密钥存储中的 KMS 密钥的密钥材料，则会出现这种情况。但是，可以恢复该密钥材料。

当您在 AWS CloudHSM 密钥存储中创建 AWS KMS key（KMS 密钥）时，AWS KMS 将登录到关联的 AWS CloudHSM 集群并创建 KMS 密钥的密钥材料。它还会将密码更改为只有它知道的值，并且只要连接了 AWS CloudHSM 密钥存储，它就会保持登录状态。由于只有密钥所有者（即创建密钥的 CU）才能删除密钥，因此不太可能意外地从 HSM 中删除密钥。

但是，如果从集群内的 HSM 中删除 KMS 密钥的密钥材料，KMS 密钥的密钥状态最终将变为 UNAVAILABLE。如果您尝试使用 KMS 密钥进行加密操作，该操作将失败并出现 KMSInvalidStateException 异常。最重要的是，在 KMS 密钥下加密的任何数据都无法解密。

在某些情况下，您可以通过从包含密钥材料的备份创建集群来恢复已删除的密钥材料。仅当在密钥存在且未被删除的情况下创建了一个备份时，此策略才有效。

使用以下过程恢复密钥材料。

如何以 kmsuser 身份登录

为了创建和管理 AWS CloudHSM 密钥存储的 AWS CloudHSM 集群中的密钥材料，AWS KMS 将使用 kmsuser 加密用户（CU）账户。您在集群中创建 kmsuser CU 账户并在创建 AWS CloudHSM 密钥存储时将该账户的密码提供给 AWS KMS。

一般而言，AWS KMS 将管理 kmsuser 账户。但是，对于某些任务，您需要断开 AWS CloudHSM 密钥存储，以 kmsuser CU 身份登录到集群，并使用 CloudHSM 命令行界面（CLI）。

本主题介绍了如何断开 AWS CloudHSM 密钥存储并以 kmsuser 身份登录、运行 AWS CloudHSM 命令行工具以及注销并重新连接 AWS CloudHSM 密钥存储。

如何断开和登录

每当需要以 kmsuser 加密用户身份登录到关联的集群时，请使用以下过程。

如何注销并重新连接

每次需要以 kmsuser 加密用户身份注销并重新连接密钥存储时，请按以下步骤操作。