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

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

unWrapKey

key_mgmt_util 工具中的 unWrapKey 命令将已包装（已加密）对称密钥或私有密钥从文件导入到 HSM 中。它旨在导入由 key_mgmt_util 中的 wrapKey 命令封装的加密密钥，但它也可以用来解开用其他工具封装的密钥。不过，在这些情况下，我们建议使用 PKCS#11 或 JCE 软件库来解开包装密钥。

导入的密钥的工作原理与生成的密钥类似 AWS CloudHSM。但是，其 OBJ_ATTR_LOCAL attribute 值为零，这表示它们不是在本地生成的。

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

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

语法

unWrapKey -h

unWrapKey -f <key-file-name> 
          -w <wrapping-key-handle> 
          [-sess]
          [-min_srv <minimum-number-of-HSMs>]          
          [-timeout <number-of-seconds>]
          [-aad <additional authenticated data filename>]
          [-tag_size <tag size>]
          [-iv_file <IV file>]
          [-attest]
          [-m <wrapping-mechanism>]
          [-t <hash-type>]
          [-nex]
          [-u <user id list>]
          [-m_value <number of users needed for approval>]
          [-noheader]
          [-l <key-label>]
          [-id <key-id>]
          [-kt <key-type>]
          [-kc <key-class]
          [-i <unwrapping-IV>]

示例

这些示例说明如何使用 unWrapKey 将包装密钥从文件导入 HSM 中。在第一个例子中，我们解开了使用 wrapKey key_mgmt_util 命令包装的密钥，因此该密钥有一个标头。在第二个例子中，我们解开了包装在 key_mgmt_util 之外的密钥，因此没有标头。

例 ：解开包装密钥（带标头）

此命令将 3DES 对称密钥的包装副本导入 HSM 中。该密钥用带有标签 6 的 AES 密钥解开包装，后者与用于包装 3DES 密钥的密钥的加密方式相同。输出显示已解开包装并导入文件中的密钥，并且已导入密钥的句柄是 29。

        Command:  unWrapKey -f 3DES.key -w 6 -m 4

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Key Unwrapped.  Key Handle: 29

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
例 ：解开包装密钥（不带标头）

此命令将 3DES 对称密钥的包装副本导入 HSM 中。该密钥用带有标签 6 的 AES 密钥解开包装，后者与用于包装 3DES 密钥的密钥的加密方式相同。由于未用 key_mgmt_util 包装此 3DES 密钥，因此指定了 noheader 参数及其所需的附加参数：密钥标签 (unwrapped3DES)、密钥类 (4) 和密钥类型 (21)。输出显示已解开包装并导入文件中的密钥，并且已导入密钥的句柄是 8。

Command: unWrapKey -f 3DES.key -w 6 -noheader -l unwrapped3DES -kc 4 -kt 21 -m 4
      
      Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS
       Cfm2UnWrapWithTemplate3 returned: 0x00 : HSM Return: SUCCESS

       Key Unwrapped. Key Handle: 8

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

参数

-h

显示该命令的帮助信息。

必需：是

-f

包含包装密钥的文件的路径和名称。

必需：是

-w

指定包装密钥。在 HSM 上输入 AES 密钥或 RSA 密钥的密钥句柄。此参数为必需参数。要查找密钥句柄，请使用 findKey 命令。

要创建包装密钥，请使用genSymKey生成 AES 密钥（类型 31）或使用 GenrSA KeyPair 生成 RSA 密钥对（类型 0）。如果您使用的是 RSA 密钥对，请确保用其中的一个密钥包装密钥，然后用另一个密钥解包。要验证某个密钥是否可以用作包装密钥，请使用 getAttribute 获取 OBJ_ATTR_WRAP 属性的值，该值由常量 262 表示。

必需：是

-sess

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

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

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

默认：密钥永久有效。

必需：否

-min_srv

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

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

默认值：1

必需：否

-timeout

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

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

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

必需：否

-attest

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

默认：不执行认证检查。

必需：否

-nex

使密钥无法提取。生成的私有密钥无法从 HSM 导出。

默认：密钥可提取。

必需：否

-m

表示包装机制的值。CloudHSM 支持以下机制：

机制 值
AES_KEY_WRAP_PAD_PKCS5 4
NIST_AES_WRAP_NO_PAD 5
NIST_AES_WRAP_PAD 6
RSA_AES 7
RSA_OAEP（有关最大数据大小，请参阅本节后面的说明） 8
AES_GCM 10
CLOUDHSM_AES_GCM 11
RSA_PKCS（有关最大数据大小，请参阅本节后面的说明）。有关即将发生的更改，请参阅下面的注释 1。 12

必需：是

注意

使用RSA_OAEP包装机制时，可以封装的最大密钥大小由 RSA 密钥的模数和指定哈希的长度决定，如下所示：最大密钥大小 = modulusLengthIn Bytes-(2* Byt hashLengthIn es) -2。

使用 RSA_PKCS 封装机制时，可以封装的最大密钥大小由 RSA 密钥的模数决定，如下所示：最大密钥大小 =（字节 -11）。modulusLengthIn

-t
哈希算法 值
SHA1 2
SHA256 3
SHA384 4
SHA512 5
SHA224（对 RSA_AES 和 RSA_OAEP 有效） 6

必需：否

-noheader

如果要解开包装在 key_mgmt_util 之外的密钥，您必须指定此参数以及所有其他关联的参数。

必需：否

注意

如果您指定此参数，则还必须指定以下 -noheader 参数：

  • -l

    指定要添加到解开包装的密钥的标签。

    必需：是

  • -kc

    指定要解开包装的密钥的类。以下是可接受的值：

    3 = 公有-私有密钥对中的私有密钥

    4 = 私有（对称）密钥

    必需：是

  • -kt

    指定要解开包装的密钥的类型。以下是可接受的值：

    0 = RSA

    1 = DSA

    3 = ECC

    16 = GENERIC_SECRET

    21 = DES3

    31 = AES

    必需：是

您还可以选择指定以下 -noheader 参数：

  • -id

    要添加到解开包装的密钥的 ID。

    必需：否

  • -i

    要使用的解开包装初始化向量 (IV)。

    必需：否

[1] 根据 NIST 的指导方针，2023 年之后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群，2023 年之后仍允许这样做。有关详细信息，请参阅 FIPS 140 合规：2024 年机制弃用。

相关 主题