imSymKey - AWS CloudHSM
语法示例参数相关 主题

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

imSymKey

key_mgmt_util 工具中的 imSymKey 命令将文件中对称密钥的明文副本导入 HSM 中。您可以使用它来导入通过 HSM 之外的任何方法生成的密钥以及从 HSM 导出的密钥，例如命令写入文件的密钥。exSymKey

在导入过程中，imSymKey 将您选择的 AES 密钥（包装密钥）用于包装（加密），然后解开包装（解密）要导入的密钥。但是，imSymKey 仅适用于包含纯文本密钥的文件。要导出和导入加密密钥，请使用 WrapKey 和命令。unWrapKey

此外，imSymKey 命令仅导入对称密钥。要导入公有密钥，请使用 importPubKey。要导入私钥，请使用importPrivateKey或 wrap Key。

注意

您不能使用对称密钥或私有密钥导入受密码保护的 PEM 密钥。

导入的密钥在工作方式方面与在 HSM 中生成的密钥非常相似。但是，OBJ_ATTR_LOCAL 属性的值为零，这表示该属性不是本地生成的。您可以在导入对称密钥时，使用以下命令共享该密钥。导入密钥后，您可以在 shareKeycloudhsm_mgmt_util 中使用 命令来共享它。

imSymKey -l aesShared -t 31 -f kms.key -w 3296 -u 5

导入密钥后，请确保标记或删除密钥文件。此命令不会阻止您多次导入相同密钥材料。因此，具有不同密钥句柄和相同密钥材料的多个密钥会让跟踪密钥材料的使用情况变得困难并防止超出其加密限制。

在运行任何 key_mgmt_util 命令之前，您必须启动 key_mgmt_util 并以加密用户（CU）身份登录到 HSM。

语法

imSymKey -h

imSymKey -f <key-file>
         -w <wrapping-key-handle>  
         -t <key-type>
         -l <label>
         [-id <key-ID>]
         [-sess]
         [-wk <wrapping-key-file> ]
         [-attest]
         [-min_srv <minimum-number-of-servers>]
         [-timeout <number-of-seconds> ]
         [-u <user-ids>]

示例

这些示例说明如何使用 imSymKey 将对称密钥导入您的 HSM 中。

例 ：导入 AES 对称密钥

此示例使用 imSymKey 将 AES 对称密钥导入 HSM 中。

第一条命令使用 OpenSSL 生成随机 256 位 AES 对称密钥。它将密钥保存在 aes256.key 文件中。

$  openssl rand -out aes256-forImport.key 32

第二条命令使用 imSymKey 将 aes256.key 文件中的 AES 密钥导入 HSM 中。它使用密钥 20 (HSM 中的 AES 密钥) 作为包装密钥并指定 imported 的标签。与 ID 不同，标签无需在群集中是唯一的。-t (类型) 参数的值为 31，该值表示 AES。

输出表明，文件中的密钥已经过包装和解开包装，然后导入 HSM 中，其中为密钥分配了密钥句柄 262180。

Command:  imSymKey -f aes256.key -w 20 -t 31 -l imported

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262180

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

下一条命令使用 getAttribute 获取新导入密钥的 OBJ_ATTR_LOCAL 属性 (属性 355) 并将它写入 attr_262180 文件中。

Command:  getAttribute -o 262180 -a 355 -out attributes/attr_262180
Attributes dumped into attributes/attr_262180_imported file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS

在您检查属性文件时，您会看到 OBJ_ATTR_LOCAL 属性的值为零，这指示 HSM 中未生成密钥材料。

$  cat attributes/attr_262180_local
OBJ_ATTR_LOCAL
0x00000000
例 ：在集群之间移动对称密钥

此示例说明如何在集群之间使用exSymKey和imSymKey移动纯文本 AES 密钥。您可使用与此类似的过程，创建两个集群中的 HSM 上存在的 AES 包装密钥。共享包装密钥到位后，您可以使用 wrapKey and 在集unWrapKey群之间移动加密密钥。

执行此操作的 CU 用户必须有权登录这两个集群上的 HSM。

第一个命令用于exSymKey将密钥 14（一个 32 位 AES 密钥）从集群 1 导出到aes.key文件中。它使用密钥 6（集群 1 中的 HSM 上的 AES 密钥）作为包装密钥。

Command: exSymKey -k 14 -w 6 -out aes.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes.key"

随后，用户登录集群 2 中的 key_mgmt_util 并运行 imSymKey 命令以将 aes.key 文件中的密钥导入集群 2 中的 HSM 中。此命令使用密钥 252152（集群 2 中 HSM 上的 AES 密钥）作为包装密钥。

由于exSymKey和imSymKey使用的包装密钥会包装并立即解开目标密钥，因此不同集群上的封装密钥不必相同。

输出表明，此密钥已成功导入集群 2 中并已获得密钥句柄 21。

Command:  imSymKey -f aes.key -w 262152 -t 31 -l xcluster

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 21

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

要证明群集 1 的密钥 14 和群集 2 中的密钥 21 具有相同的密钥材料，请获取每个密钥的密钥检查值 (KCV)。如果 KCV 值相同，则密钥材料相同。

以下命令使用群集 1 中的 getAttribute 将密钥 14 的 KCV 属性 (属性 371) 的值写入 attr_14_kcv 文件中。然后，它使用 cat 命令获取 attr_14_kcv 文件的内容。

Command:  getAttribute -o 14 -a 371 -out attr_14_kcv
Attributes dumped into attr_14_kcv file

$  cat attr_14_kcv
OBJ_ATTR_KCV
0xc33cbd

此类似命令使用群集 2 中的 getAttribute 将密钥 21 的 KCV 属性 (属性 371) 的值写入 attr_21_kcv 文件中。然后，它使用 cat 命令获取 attr_21_kcv 文件的内容。

Command:  getAttribute -o 21 -a 371 -out attr_21_kcv
Attributes dumped into attr_21_kcv file

$  cat attr_21_kcv
OBJ_ATTR_KCV
0xc33cbd

输出表明，两个密钥的 KCV 值相同，这证明密钥材料相同。

由于两个群集的 HSM 中存在相同的密钥材料，因此，您现在可以在群集之间共享已加密密钥，而无需公开纯文本密钥。例如，您可以将 wrapKey 命令与包装密钥 14 结合使用以导出群集 1 中的已加密密钥，然后将 unWrapKey 与包装密钥 21 结合使用以将已加密密钥导入群集 2 中。

例 ：导入会话密钥

此命令使用 imSymKey 的 -sess 参数导入仅在当前会话中有效的 192 位三重 DES 密钥。

此命令使用 -f 参数指定包含要导入的密钥的文件，使用 -t 参数指定密钥类型，并使用 -w 参数指定包装密钥。它使用 -l 参数指定用于对密钥进行分类的标签，并使用 -id 参数为密钥创建友好的唯一标识符。它还使用 -attest 参数验证导入密钥的固件。

输出表明，密钥已成功包装和解开包装，导入 HSM 中，并且分配有密钥句柄 37。此外，通过了鉴证检查，这指示固件未遭篡改。

Command:  imSymKey -f 3des192.key -w 6 -t 21 -l temp -id test01 -sess -attest

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 37

        Attestation Check : [PASS]

        Cluster Error Status
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

接下来，您可以使用 getAttribute 或 findKey 命令验证新导入密钥的属性。以下命令使用 findKey 验证密钥 37 是否具有此命令指定的类型、标签和 ID，并验证此密钥是否为会话密钥。如输出的第 5 行所示，findKey 报告，与所有属性匹配的唯一密钥为密钥 37。

Command:  findKey -t 21 -l temp -id test01 -sess 1
Total number of keys present 1

 number of keys matched from start index 0::0
37

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

        Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

参数

-attest

运行完整性检查，以验证运行集群的固件是否被篡改。

默认：不执行认证检查。

必需：否

-f

指定包含要导入的密钥的文件。

该文件必须包含指定长度的 AES 或三重 DES 密钥的纯文本副本。RC4 和 DES 密钥在 FIPS 模式的 HSM 上无效。

  • AES：16、24 或 32 个字节

  • 三重 DES (3DES)：24 个字节

必需：是

-h

显示该命令的帮助信息。

必需：是

-id

为密钥指定用户定义标识符。在集群中键入唯一字符串。默认值是空字符串。

默认值：无 ID 值。

必需：否

-l

指定用户定义的密钥标签。键入字符串。

您可使用任何短语，以帮助您识别密钥。由于标签并非唯一，因此您可将其用于分组和分类密钥。

必需：是

-min_srv

指定在 -timeout 参数的值到期之前密钥在其上同步的 HSM 数量的最小值。如果密钥在分配的时间内未同步到指定数量的服务器，则不会创建它。

AWS CloudHSM 自动将每个密钥同步到集群中的每个 HSM。要加快此过程，请将 min_srv 的值设置为小于集群中的 HSM 数，并设置一个较低的超时值。但请注意，一些请求可能无法生成密钥。

默认值：1

必需：否

-sess

创建仅在当前会话中存在的密钥。会话结束后，密钥无法恢复。

如果您只需要一个短暂的密钥，例如用于加密然后快速解密另一个密钥的包装密钥，请使用此参数。对于会话结束后可能需要解密的加密数据，切勿使用会话密钥。

若要将会话密钥更改为永久（令牌）密钥，请使用 setAttribute。

默认：密钥永久有效。

必需：否

-timeout

指定命令等待密钥同步到 min_srv 参数指定数量的 HSM 所需的时间（以秒为单位）。

仅当 min_srv 参数也用于此命令时，该参数才有效。

默认：没有超时 该命令无限期等待，仅当密钥同步至最少数量的服务器时才返回。

必需：否

-t

指定对称密钥的类型。输入表示密钥类型的常量。例如，要创建 AES 密钥，请输入 -t 31。

有效值：

必需：是

-u

与指定用户共享导入的密钥。此参数向其他 HSM 加密用户 (CU) 授予在加密操作中使用此密钥的权限。

键入一个 ID 或逗号分隔的 HSM 用户 ID 列表，如 5,6。请勿包括当前用户的 HSM 用户 ID。要查找 ID，您可以使用 cloudhsm_mgmt_util 命令行工具中的 listUsers 命令或 key_mgmt_util 命令行工具中的 listUsers 命令。

必需：否

-w

指定包装密钥的密钥句柄。此参数为必需参数。要查找密钥句柄，请使用 findKey 命令。

包装密钥 是 HSM 中的密钥，在导入过程中用于依次加密 (“包装”) 和解密 (“解开包装”) 密钥。只有 AES 密钥才能用作包装密钥。

您可以使用任何 AES 密钥 (任何大小) 作为包装密钥。由于包装密钥将对目标密钥进行包装，然后紧接着将其解开包装，因此您可以使用仅会话型 AES 密钥作为包装密钥。要确定密钥是否可用作包装密钥，请使用 getAttribute 获取 OBJ_ATTR_WRAP 属性 (262) 的值。要创建包装密钥，genSymKey请使用创建 AES 密钥（类型 31）。

如果您使用 -wk 参数指定外部包装密钥，则 -w 包装密钥用于解开包装，而不是包装正在导入的密钥。

注意

密钥 4 是不受支持的内部密钥。建议您使用作为包装密钥创建和管理的 AES 密钥。

必需：是

-wk

使用指定文件中的 AES 密钥包装正在导入的密钥。输入包含明文 AES 密钥的文件的路径和名称。

当您包含此参数时。imSymKey 使用 -wk 文件中的密钥包装导入的密钥，并使用 HSM 中由 -w 参数指定的密钥对导入的密钥解开包装。-w 和 -wk 参数值必须解析为相同的明文密钥。

默认：在 HSM 上使用包装密钥解开包装。

必需：否

相关 主题