exSymKey

key_mgmt_util 工具中的 exSymKey 命令从 HSM 中导出对称密钥的明文副本并将其保存在磁盘上的文件中。要导出密钥的加密 (已包装) 副本，请使用 wrapKey。要导入明文密钥，如 exSymKey 导出的密钥，请使用 imSymKey。

在导出过程中，exSymKey 使用您指定的 AES 密钥（包装密钥）进行包装（加密），然后将要导出的密钥解开包装（解密）。然而，导出操作的结果是磁盘上的明文 (解开包装) 密钥。

只有密钥的所有者 (即创建该密钥的 CU 用户) 才能导出它。共享密钥的用户可以在加密操作中使用密钥，但无法导出它。

exSymKey 操作将密钥材料复制到您指定的文件，但它不会从 HSM 中删除密钥，不会更改其密钥属性，也不会阻止您在加密操作中使用密钥。您可以多次导出相同的密钥。

exSymKey 仅导出对称密钥。要导出公有密钥，请使用 exportPubKey。要导出私有密钥，请使用 exportPrivateKey。

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

语法

exSymKey -h

exSymKey -k <key-to-export>
         -w <wrapping-key>
         -out <key-file>
         [-m 4] 
         [-wk <unwrapping-key-file> ]

示例

这些示例演示如何使用 exSymKey 从您的 HSM 中导出您拥有的对称密钥。

例 ：导出 3DES 对称密钥

此命令将导出三重 DES (3DES) 对称密钥 (密钥句柄 7)。它使用 HSM 中的现有 AES 密钥 (密钥句柄 6) 作为包装密钥。然后，它将 3DES 明文密钥写入 3DES.key 文件。

输出显示密钥 7 (3DES 密钥) 已成功包装和解开包装，然后写入 3DES.key 文件。

警告

尽管输出表明“包装的对称密钥”已写入输出文件，但输出文件包含明文 (解开包装的) 密钥。

        Command: exSymKey -k 7 -w 6 -out 3DES.key

       Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "3DES.key"

例 ：导出仅会话型包装密钥

此示例显示如何使用仅存在于会话中的密钥作为包装密钥。由于要导出的密钥会进行包装、立即解开包装并以明文形式提供，因此无需保留包装密钥。

此系列命令从 HSM 中导出密钥句柄为 8 的 AES 密钥。它使用专为该用途创建的 AES 会话密钥。

第一个命令使用 genSymKey 创建 256 位 AES 密钥。它使用 -sess 参数创建仅在当前会话中存在的密钥。

输出显示 HSM 创建密钥 262168。

        Command:  genSymKey -t 31 -s 32 -l AES-wrapping-key -sess

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 262168

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

然后，此示例验证密钥 8 (要导出的密钥) 是否为可提取的对称密钥。它还会验证包装密钥 (密钥 262168) 是否为仅在会话中存在的 AES 密钥。您可以使用 findKey 命令，但此示例会将两个密钥的属性都导出到文件，然后使用 grep 在文件中查找相关属性值。

这些命令使用 -a 值为 512 (全部) 的 getAttribute 来获取密钥 8 和 262168 的所有属性。有关密钥属性的信息，请参阅密钥属性引用。

getAttribute -o 8 -a 512 -out attributes/attr_8
getAttribute -o 262168 -a 512 -out attributes/attr_262168

这些命令使用 grep 验证要导出的密钥 (密钥 8) 和仅会话型包装密钥 (密钥 262168) 的属性。

    // Verify that the key to be exported is a symmetric key.
    $  grep -A 1 "OBJ_ATTR_CLASS" attributes/attr_8    
    OBJ_ATTR_CLASS
    0x04
   
    // Verify that the key to be exported is extractable.
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_8
    OBJ_ATTR_EXTRACTABLE
    0x00000001

    // Verify that the wrapping key is an AES key
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_262168
    OBJ_ATTR_KEY_TYPE
    0x1f

    // Verify that the wrapping key is a session key
    $  grep -A 1 "OBJ_ATTR_TOKEN" attributes/attr_262168
    OBJ_ATTR_TOKEN
    0x00    
    
    // Verify that the wrapping key can be used for wrapping
     $  grep -A 1 "OBJ_ATTR_WRAP" attributes/attr_262168
    OBJ_ATTR_WRAP
    0x00000001  

最后，我们使用 exSymKey 命令通过使用会话密钥（密钥 262168）作为包装密钥来导出密钥 8。

当会话结束时，密钥 262168 不再存在。

        Command:  exSymKey -k 8 -w 262168 -out aes256_H8.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes256_H8.key"
      

例 ：使用外部解开包装密钥

此示例显示如何使用外部解开包装密钥来从 HSM 中导出密钥。

当从 HSM 中导出密钥时，您可在 HSM 上指定要成为包装密钥的 AES 密钥。默认情况下，包装密钥用于将要导出的密钥进行包装和解开包装。但是，您可以使用 -wk 参数来告知 exSymKey 使用磁盘上文件中的外部密钥解开包装。执行此操作时，由 -w 参数指定的密钥会包装目标密钥，而由 -wk 参数指定的文件中的密钥将为该密钥解开包装。

由于包装密钥必须是 AES 对称密钥，因此 HSM 中的包装密钥和磁盘上的解开包装密钥必须具有相同的密钥材料。为此，您必须将包装密钥导入 HSM 或在导出操作之前从 HSM 中导出包装密钥。

此示例在 HSM 外部创建密钥并将其导入到 HSM 中。它使用密钥的内部副本将要导出的对称密钥进行包装，然后使用文件中的密钥副本将其解开包装。

第一个命令使用 OpenSSL 生成 256 位 AES 密钥。它将密钥保存到 aes256-forImport.key 文件。OpenSSL 命令不会返回任何输出，但您可以使用多个命令来确认其是否运行成功。此示例使用了用于确认文件包含 32 字节数据的 wc (wordcount) 工具。

$  openssl rand -out keys/aes256-forImport.key 32

$ wc keys/aes256-forImport.key
 0  2 32 keys/aes256-forImport.key

此命令使用 imSymKey 命令将 AES 密钥从 aes256-forImport.key 文件导入到 HSM。该命令完成后，密钥句柄为 262167 的密钥将存在于 HSM 和 aes256-forImport.key 文件中。

Command:  imSymKey -f keys/aes256-forImport.key -t 31 -l aes256-imported -w 6

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262167

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

此命令在导出操作中使用该密钥。此命令使用 exSymKey 来导出密钥 21（192 位 AES 密钥）。为了包装该密钥，它会使用密钥 262167，这是已导入 HSM 中的副本。为了解开包装密钥，它会使用 aes256-forImport.key 文件中的相同密钥材料。该命令完成后，密钥 21 将会导出到 aes192_h21.key 文件。

        Command:  exSymKey -k 21 -w 262167 -out aes192_H21.key -wk aes256-forImport.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

Wrapped Symmetric Key written to file "aes192_H21.key"

参数

-h

显示该命令的帮助信息。

必需：是

-k

指定要导出的密钥的密钥句柄。此参数为必需参数。输入您拥有的对称密钥的密钥句柄。此参数为必需参数。要查找密钥句柄，请使用 findKey 命令。

要验证是否能导出密钥，请使用 getAttribute 命令获取由常量 354 表示的 OBJ_ATTR_EXTRACTABLE 属性的值。此外，您还只能导出您拥有的密钥。要查找密钥的所有者，请使用 getKeyInfo 命令。

必需：是

-w

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

包装密钥 是 HSM 中的密钥，用于对要导出的密钥进行加密 (包装) 和解密 (解开包装)。只有 AES 密钥才能用作包装密钥。

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

如果您使用 -wk 参数指定外部解开包装密钥，则 -w 包装密钥用于在导出过程中包装密钥而不是将其解开包装。

注意

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

必需：是

-out

指定输出文件的路径和名称。此命令成功后，此文件将包含以明文形式的已导出密钥。如果该文件已存在，则命令将覆盖该文件而不发出警告。

必需：是

-m

指定包装机制。唯一有效值为 4，它表示 NIST_AES_WRAP 机制。

必需：否

默认值：4

-wk

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

当您包含此参数时。exSymKey 使用 HSM 中由 -w 参数指定的密钥包装正在导出的密钥，并且使用 -wk 文件中的密钥将其解开包装。-w 和 -wk 参数值必须解析为相同的明文密钥。

必需：否

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

相关主题

• genSymKey

• imSymKey

• wrapKey