更改 AWS CloudHSM 客户端密钥持久性设置

密钥同步总体是一个自动过程，但您可以管理客户端密钥的耐久性设置。客户端 SDK 5 和客户端 SDK 3 中的客户端密钥持久性设置的工作方式不同。

• 在客户端 SDK 5 中，我们引入了密钥可用性法定人数的概念，它要求您运行至少为两个的集群。HSMs您可以使用客户端密钥持久性设置来选择退出这两个HSM要求。有关仲裁的更多信息，请参阅 客户端 SDK 5 个概念。

• 在客户端 SDK 3 中，您可以使用客户端密钥持久性设置来指定必须成功创建密钥的HSMs次数，才能将整个操作视为成功。

客户端 SDK 5 客户端密钥持久性设置

在客户端 SDK 5 中，密钥同步是一个全自动的过程。在密钥可用性法定人数下，新创建的密钥必须存在于集群HSMs中的两个上，然后您的应用程序才能使用该密钥。要使用密钥可用性法定人数，您的集群必须至少有两个。HSMs

如果您的集群配置不符合密钥持久性要求，则任何创建或使用令牌密钥的尝试都将失败，并在日志中显示以下错误消息：

Key <key handle> does not meet the availability requirements - The key must be available on at least 2 HSMs before being used.

您可以使用客户端配置设置选择退出密钥可用性仲裁。例如，您可能希望选择不使用单个HSM集群来运行集群。

客户端 SDK 5 个概念

密钥可用性仲裁

AWS CloudHSM 指定集群HSMs中必须存在密钥的数量，然后您的应用程序才能使用该密钥。需要至少有两个的集群HSMs。

管理客户端密钥持久性设置

要管理客户端密钥持久性设置，必须使用客户端 SDK 5 的配置工具。

PKCS #11 library

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check
              

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --disable-key-availability-check
              

OpenSSL Dynamic Engine

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-dyn --disable-key-availability-check
              

Key Storage Provider (KSP)

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-key-availability-check
              

JCE provider

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-jce --disable-key-availability-check
              

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-key-availability-check
              

CloudHSM CLI

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-cli --disable-key-availability-check
              

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --disable-key-availability-check
              

客户端 SDK 5 客户端密钥持久性设置

在客户端 SDK 5 中，密钥同步是一个全自动的过程。在密钥可用性法定人数下，新创建的密钥必须存在于集群HSMs中的两个上，然后您的应用程序才能使用该密钥。要使用密钥可用性法定人数，您的集群必须至少有两个。HSMs

如果您的集群配置不符合密钥持久性要求，则任何创建或使用令牌密钥的尝试都将失败，并在日志中显示以下错误消息：

Key <key handle> does not meet the availability requirements - The key must be available on at least 2 HSMs before being used.

您可以使用客户端配置设置选择退出密钥可用性仲裁。例如，您可能希望选择不使用单个HSM集群来运行集群。

客户端 SDK 5 个概念

密钥可用性仲裁

AWS CloudHSM 指定集群HSMs中必须存在密钥的数量，然后您的应用程序才能使用该密钥。需要至少有两个的集群HSMs。

管理客户端密钥持久性设置

要管理客户端密钥持久性设置，必须使用客户端 SDK 5 的配置工具。

PKCS #11 library

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check
              

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --disable-key-availability-check
              

OpenSSL Dynamic Engine

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-dyn --disable-key-availability-check
              

Key Storage Provider (KSP)

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-key-availability-check
              

JCE provider

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-jce --disable-key-availability-check
              

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-key-availability-check
              

CloudHSM CLI

在 Linux 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  $ sudo /opt/cloudhsm/bin/configure-cli --disable-key-availability-check
              

在 Windows 上禁用客户端 SDK 5 的客户端密钥持久性

• 使用配置工具禁用客户端密钥持久性设置。

  
  "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" --disable-key-availability-check
              

客户端 SDK 3 客户端密钥持久性设置

在客户端 SDK 3 中，密钥同步主要是一个自动过程，但您可以使用客户端密钥持久性设置来提高密钥的耐用性。您可以指定必须成功创建密钥的HSMs次数，才能将整个操作视为成功。无论您选择什么设置，客户端同步始终会尽最大努力将密钥克隆到集群HSM中的每个人。您的设置会强制根据HSMs您指定的数量创建密钥。如果您指定了一个值，但系统无法将该密钥复制到该数量的HSMs，则系统会自动清理所有不需要的密钥材料，您可以重试。

重要

如果您未设置客户端密钥持久性设置（或者使用默认值 1），则密钥很容易丢失。如果您的当前HSM密钥在服务器端服务将该密钥克隆到另一个密钥之前出现故障HSM，则密钥材料就会丢失。

为了最大限度地提高密钥的持久性，请考虑HSMs为客户端同步指定至少两个密钥。请记住，无论HSMs您指定多少，集群上的工作负载都保持不变。客户端同步总是尽最大努力将密钥克隆到集群HSM中的每个人。

建议

• 最少：HSMs每个集群两个

• 最大值：比集群HSMs中的总数少一个

如果客户端同步失败，则客户端服务会清理可能已创建且现在不需要的所有不需要的密钥。这种清理是尽力而为的应对措施，可能并不总是奏效。如果清理失败，则可能需要您删除不需要的密钥材料。有关更多信息，请参阅密钥同步故障。

为客户端密钥持久性设置配置文件

要指定客户端密钥持久性设置，必须编辑 cloudhsm_client.cfg。

编辑客户端配置文件

1. 打开 cloudhsm_client.cfg。

   Linux：

   /opt/cloudhsm/etc/cloudhsm_client.cfg

   Windows:

   C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg

2. 在文件client节点中，添加create_object_minimum_nodes并指定一个值，指定 AWS CloudHSM 必须成功创建密钥才能成功创建密钥才能成功创建密钥的最小数量。HSMs

   "create_object_minimum_nodes" : 2

   注意

   key_mgmt_util (KMU) 命令行工具对客户端密钥的持久性进行了额外设置。有关更多信息，请参阅 KMU和客户端同步

配置参考

以下是客户端同步属性，如以下 cloudhsm_client.cfg 的摘录所示：

{
    "client": {
        "create_object_minimum_nodes" : 2,
        ...
    },
    
    ...
}

create_object_minimum_nodes

指定认为密钥生成、密钥导入或密钥解包操作成功HSMs所需的最小数量。如果已设置，默认为“1”。这意味着，对于每个密钥创建操作，客户端服务都会尝试在集群HSM中的每个密钥上创建密钥，但要返回成功，只需要在集群HSM中的一个密钥上创建一个密钥即可。

KMU和客户端同步

如果使用 key_mgmt_util (KMU) 命令行工具创建密钥，则使用可选的命令行参数 (-min_srv) 来限制克隆密钥的数量。HSMs如果您在配置文件中指定命令行参数和值， AWS CloudHSM 则使用这两个值中的一个。LARGER

有关更多信息，请参阅以下主题：

• genDSAKey配对

• genECCKey配对

• genRSAKey配对

• genSymKey

• importPrivateKey

• importPubKey

• imSymKey

• insertMaskedObject

• unWrapKey

客户端 SDK 3 客户端密钥持久性设置

在客户端 SDK 3 中，密钥同步主要是一个自动过程，但您可以使用客户端密钥持久性设置来提高密钥的耐用性。您可以指定必须成功创建密钥的HSMs次数，才能将整个操作视为成功。无论您选择什么设置，客户端同步始终会尽最大努力将密钥克隆到集群HSM中的每个人。您的设置会强制根据HSMs您指定的数量创建密钥。如果您指定了一个值，但系统无法将该密钥复制到该数量的HSMs，则系统会自动清理所有不需要的密钥材料，您可以重试。

重要

如果您未设置客户端密钥持久性设置（或者使用默认值 1），则密钥很容易丢失。如果您的当前HSM密钥在服务器端服务将该密钥克隆到另一个密钥之前出现故障HSM，则密钥材料就会丢失。

为了最大限度地提高密钥的持久性，请考虑HSMs为客户端同步指定至少两个密钥。请记住，无论HSMs您指定多少，集群上的工作负载都保持不变。客户端同步总是尽最大努力将密钥克隆到集群HSM中的每个人。

建议

• 最少：HSMs每个集群两个

• 最大值：比集群HSMs中的总数少一个

如果客户端同步失败，则客户端服务会清理可能已创建且现在不需要的所有不需要的密钥。这种清理是尽力而为的应对措施，可能并不总是奏效。如果清理失败，则可能需要您删除不需要的密钥材料。有关更多信息，请参阅密钥同步故障。

为客户端密钥持久性设置配置文件

要指定客户端密钥持久性设置，必须编辑 cloudhsm_client.cfg。

编辑客户端配置文件

1. 打开 cloudhsm_client.cfg。

   Linux：

   /opt/cloudhsm/etc/cloudhsm_client.cfg

   Windows:

   C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg

2. 在文件client节点中，添加create_object_minimum_nodes并指定一个值，指定 AWS CloudHSM 必须成功创建密钥才能成功创建密钥才能成功创建密钥的最小数量。HSMs

   "create_object_minimum_nodes" : 2

   注意

   key_mgmt_util (KMU) 命令行工具对客户端密钥的持久性进行了额外设置。有关更多信息，请参阅 KMU和客户端同步

配置参考

以下是客户端同步属性，如以下 cloudhsm_client.cfg 的摘录所示：

{
    "client": {
        "create_object_minimum_nodes" : 2,
        ...
    },
    
    ...
}

create_object_minimum_nodes

指定认为密钥生成、密钥导入或密钥解包操作成功HSMs所需的最小数量。如果已设置，默认为“1”。这意味着，对于每个密钥创建操作，客户端服务都会尝试在集群HSM中的每个密钥上创建密钥，但要返回成功，只需要在集群HSM中的一个密钥上创建一个密钥即可。

KMU和客户端同步

如果使用 key_mgmt_util (KMU) 命令行工具创建密钥，则使用可选的命令行参数 (-min_srv) 来限制克隆密钥的数量。HSMs如果您在配置文件中指定命令行参数和值， AWS CloudHSM 则使用这两个值中的一个。LARGER

有关更多信息，请参阅以下主题：

• genDSAKey配对

• genECCKey配对

• genRSAKey配对

• genSymKey

• importPrivateKey

• importPubKey

• imSymKey

• insertMaskedObject

• unWrapKey