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

# 使用 KMU 导入纯文本对称密钥 AWS CloudHSM
<a name="key_mgmt_util-imSymKey"></a>

使用 AWS CloudHSM key\_mgmt\_util 工具中的**imSymKey**命令将对称密钥的纯文本副本从文件导入硬件安全模块 (HSM)。您可以使用它来导入通过 HSM 之外的任何方法生成的密钥以及从 HSM 导出的密钥，例如命令写入文件的密钥。[exSymKey](key_mgmt_util-exSymKey.md)

在导入过程中，**imSymKey** 将您选择的 AES 密钥（*包装密钥*）用于*包装*（加密），然后*解包*（解密）要导入的密钥。但是，**imSymKey** 仅适用于包含纯文本密钥的文件。要导出和导入加密密钥，请使用 [WrapKey 和命令](key_mgmt_util-wrapKey.md)。[unWrapKey](key_mgmt_util-unwrapKey.md)

此外，**imSymKey** 命令仅导入对称密钥。要导入公有密钥，请使用 [importPubKey](key_mgmt_util-importPubKey.md)。要导入私钥，请使用[importPrivateKey](key_mgmt_util-importPrivateKey.md)或 [wrap](key_mgmt_util-wrapKey.md) Key。

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

导入的密钥在工作方式方面与在 HSM 中生成的密钥非常相似。但是，[OBJ\_ATTR\_LOCAL 属性](key-attribute-table.md)的值为零，这表示该属性不是本地生成的。您可以在导入对称密钥时，使用以下命令共享该密钥。导入密钥后，您可以在 `shareKey`cloudhsm\_mgmt\_util[ 中使用 ](cloudhsm_mgmt_util.md) 命令来共享它。

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

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

在运行任何 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="imSymKey-syntax"></a>

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

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

这些示例说明如何使用**imSymKey**将对称密钥导入 HSMs到。

**Example ：导入 AES 对称密钥**  
此示例用于**imSymKey**将 AES 对称密钥导入。 HSMs  
第一条命令使用 OpenSSL 生成随机 256 位 AES 对称密钥。它将密钥保存在 `aes256.key` 文件中。  

```
$  openssl rand -out aes256.key 32
```
第二个命令用于**imSymKey**将 AES 密钥从`aes256.key`文件导入 HSMs。它使用密钥 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](key_mgmt_util-getAttribute.md) 获取新导入密钥的 OBJ\_ATTR\_LOCAL 属性 ([属性 355](key-attribute-table.md)) 并将它写入 `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
```

**Example ：在集群之间移动对称密钥**  
此示例说明如何使用 [exSymKey](key_mgmt_util-exSymKey.md) 和 **imSymKey** 在群集之间移动纯文本 AES 密钥。你可以使用这样的过程来创建 HSMs 两个集群上都存在的 AES 包装。共享包装密钥到位后，您可以使用 [wrapKey and](key_mgmt_util-wrapKey.md) 在集[unWrapKey](key_mgmt_util-unwrapKey.md)群之间移动加密密钥。  
执行此操作的 CU 用户必须具有登录两个集群 HSMs 的权限。  
第一条命令使用 [exSymKey](key_mgmt_util-exSymKey.md) 将群集 1 的密钥 14 (一个 32 位 AES 密钥) 导出到 `aes.key` 文件中。它使用密钥 6（集群 1 HSMs 中的 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**命令将文件中的密钥导入到集群 2 中的`aes.key`。 HSMs 此命令使用密钥 252152（群集 2 HSMs 中的 AES 密钥）作为包装密钥。  
由于 [exSymKey](key_mgmt_util-exSymKey.md) 和 **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](key_mgmt_util-getAttribute.md) 将密钥 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](key_mgmt_util-getAttribute.md) 将密钥 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 值相同，这证明密钥材料相同。  
由于两个集群中存在相同的密钥材料，因此您现在可以在集群之间共享加密密钥，而无需暴露纯文本密钥。 HSMs 例如，您可以将 `wrapKey` 命令与包装密钥 14 结合使用以导出群集 1 中的已加密密钥，然后将 `unWrapKey` 与包装密钥 21 结合使用以将已加密密钥导入群集 2 中。

**Example ：导入会话密钥**  
此命令使用 **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](key_mgmt_util-getAttribute.md) 或 [findKey](key_mgmt_util-findKey.md) 命令验证新导入密钥的属性。以下命令使用 **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
```

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

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

**-f**  
指定包含要导入的密钥的文件。  
该文件必须包含指定长度的 AES 或 Triple DES 密钥的纯文本副本。 RC4 而且 DES 密钥在 FIP HSMs S 模式下无效。  
+ **AES**：16、24 或 32 个字节
+ **三重 DES (3DES)**：24 个字节
是否必需：是

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

**-id**  
为密钥指定用户定义标识符。在集群中键入唯一字符串。默认值是空字符串。  
默认值：无 ID 值。  
必需：否

**-l**  
指定用户定义的密钥标签。键入字符串。  
您可使用任何短语，以帮助您识别密钥。由于标签并非唯一，因此您可将其用于分组和分类密钥。  
是否必需：是

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

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

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

**-t**  
指定对称密钥的类型。输入表示密钥类型的常量。例如，要创建 AES 密钥，请输入 `-t 31`。  
有效值：  
+ 21：[三重 DES (3DES)](https://en.wikipedia.org/wiki/Triple_DES)。
+ 31：[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
是否必需：是

**-u**  
与指定用户共享导入的密钥。此参数授予其他 HSM 加密用户 (CUs) 在加密操作中使用此密钥的权限。  
键入一个 ID 或以逗号分隔的 HSM 用户列表 IDs，例如-u。`5,6`请勿包括当前用户的 HSM 用户 ID。要查找 ID，您可以使用 cloudhsm\_mgmt\_util 命令行工具中的 [listUsers](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_mgmt_util-listUsers.html) 命令或 key\_mgmt\_util 命令行工具中的 [listUsers](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-listUsers.html) 命令。  
必需：否

**-w**  
指定包装密钥的密钥句柄。此参数为必需参数。要查找密钥句柄，请使用 [findKey](key_mgmt_util-findKey.md) 命令。  
*包装密钥* 是 HSM 中的密钥，在导入过程中用于依次加密 (“包装”) 和解密 (“解开包装”) 密钥。只有 AES 密钥才能用作包装密钥。  
您可以使用任何 AES 密钥 (任何大小) 作为包装密钥。由于包装密钥将对目标密钥进行包装，然后紧接着将其解开包装，因此您可以使用仅会话型 AES 密钥作为包装密钥。要确定密钥是否可用作包装密钥，请使用 [getAttribute](key_mgmt_util-getAttribute.md) 获取 `OBJ_ATTR_WRAP` 属性 (262) 的值。要创建包装密钥，请使用 [genSymKey](key_mgmt_util-genSymKey.md) 创建 AES 密钥（类型 31）。  
如果您使用 `-wk` 参数指定外部包装密钥，则 `-w` 包装密钥用于解开包装，而不是包装正在导入的密钥。  
密钥 4 是不受支持的内部密钥。建议您使用作为包装密钥创建和管理的 AES 密钥。
是否必需：是

**-wk**  
使用指定文件中的 AES 密钥包装正在导入的密钥。输入包含明文 AES 密钥的文件的路径和名称。  
当您包含此参数时。**imSymKey** 使用 `-wk` 文件中的密钥包装导入的密钥，并使用 HSM 中由 `-w` 参数指定的密钥对导入的密钥解开包装。`-w` 和 `-wk` 参数值必须解析为相同的明文密钥。  
默认：在 HSM 上使用包装密钥解开包装。  
必需：否

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