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

# 使用 AWS CloudHSM KMU 解开密钥
<a name="key_mgmt_util-unwrapKey"></a>

使用 AWS CloudHSM key\_mgmt\_util 工具中的**unWrapKey**命令将封装（加密）的对称密钥或私钥从文件导入 HSM。它旨在导入由 key\_mgmt\_util 中的 [wrapKey](key_mgmt_util-wrapKey.md) 命令封装的加密密钥，但它也可以用来解开用其他工具封装的密钥。不过，在这些情况下，我们建议使用 [PKCS\#11](pkcs11-library.md) 或 [JCE](java-library.md) 软件库来解开包装密钥。

导入的密钥的工作原理与生成的密钥类似 AWS CloudHSM。但是，其 [OBJ\_ATTR\_LOCAL attribute](key-attribute-table.md) 值为零，这表示它们不是在本地生成的。

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

在运行任何 key\_mgmt\_util 命令之前，您必须[启动 key\_mgmt\_util](key_mgmt_util-setup.md#key_mgmt_util-start) 并以加密用户（CU）身份[登录](key_mgmt_util-log-in.md)到 HSM。

## 语法
<a name="unwrapKey-syntax"></a>

```
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>}}]
```

## 示例
<a name="unwrapKey-examples"></a>

这些示例说明**unWrapKey**如何使用将封装后的密钥从文件导入到 HSMs。在第一个例子中，我们解开了使用 **[wrapKey](key_mgmt_util-wrapKey.md)** key\_mgmt\_util 命令包装的密钥，因此该密钥有一个标头。在第二个例子中，我们解开了包装在 key\_mgmt\_util 之外的密钥，因此没有标头。

**Example ：解开包装密钥（带标头）**  
此命令将 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
```

**Example ：解开包装密钥（不带标头）**  
此命令将 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
```

## 参数
<a name="unwrapKey-params"></a>

**-h**  
显示该命令的帮助信息。  
是否必需：是

**-f**  
包含包装密钥的文件的路径和名称。  
是否必需：是

**-w**  
指定包装密钥。在 HSM 上输入 AES 密钥或 RSA 密钥的密钥句柄。此参数为必需参数。要查找密钥句柄，请使用 [findKey](key_mgmt_util-findKey.md) 命令。  
要创建封装密钥，请使用[genSymKey](key_mgmt_util-genSymKey.md)生成 AES 密钥（类型 31），或者使用生成[RSAKey一代 Pair](key_mgmt_util-genRSAKeyPair.md) 来生成 RSA 密钥对（类型 0）。如果您使用的是 RSA 密钥对，请确保用其中的一个密钥包装密钥，然后用另一个密钥解包。要验证某个密钥是否可以用作包装密钥，请使用 [getAttribute](key_mgmt_util-getAttribute.md) 获取 `OBJ_ATTR_WRAP` 属性的值，该值由常量 `262` 表示。  
是否必需：是

**-sess**  
创建仅在当前会话中存在的密钥。会话结束后，密钥无法恢复。  
如果您只需要一个短暂的密钥，例如用于加密然后快速解密另一个密钥的包装密钥，请使用此参数。对于会话结束后可能需要解密的加密数据，切勿使用会话密钥。  
若要将会话密钥更改为永久（令牌）密钥，请使用 [setAttribute](key_mgmt_util-setAttribute.md)。  
默认：密钥永久有效。  
必需：否

**-min\_srv**  
指定 HSMs 在`-timeout`参数值到期之前同步密钥的最小数量。如果密钥在分配的时间内未同步到指定数量的服务器，则不会创建它。  
AWS CloudHSM 自动将每个密钥同步到集群中的每个 HSM。要加快处理速度，请将的值设置`min_srv`为小于群集 HSMs 中的数量，并设置一个较低的超时值。但请注意，一些请求可能无法生成密钥。  
默认：1  
必需：否

**-timeout**  
指定命令等待密钥同步到`min_srv`参数所 HSMs 指定数量的时间（以秒为单位）。  
仅当 `min_srv` 参数也用于此命令时，该参数才有效。  
默认：没有超时 该命令无限期等待，仅当密钥同步至最少数量的服务器时才返回。  
必需：否

**-attest**  
运行完整性检查，以验证运行集群的固件是否被篡改。  
默认：不执行认证检查。  
必需：否

**-nex**  
使密钥无法提取。生成的私有密钥无法[从 HSM 导出](export-keys.md)。  
默认：密钥可提取。  
必需：否

**-m**  
表示包装机制的值。CloudHSM 支持以下机制：      
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/key_mgmt_util-unwrapKey.html)
是否必需：是  
使用`RSA_OAEP`包装机制时，可以封装的最大密钥大小由 RSA 密钥的模数和指定哈希的长度决定，如下所示：最大密钥大小 = modulusLengthIn Bytes-(2\* Byt hashLengthIn es) -2。  
使用 RSA\_PKCS 封装机制时，可以封装的最大密钥大小由 RSA 密钥的模数决定，如下所示：最大密钥大小 =（字节 -11）。modulusLengthIn

**-t**      
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/cloudhsm/latest/userguide/key_mgmt_util-unwrapKey.html)
必需：否

**-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 年机制弃用](compliance-dep-notif.md#compliance-dep-notif-1)。

## 相关主题
<a name="unwrapKey-seealso"></a>
+ [wrapKey](key_mgmt_util-wrapKey.md)
+ [exSymKey](key_mgmt_util-exSymKey.md)
+ [imSymKey](key_mgmt_util-imSymKey.md)