使用 KMU 导出 AWS CloudHSM 密钥的明文副本 - AWS CloudHSM
语法示例参数相关主题

使用 KMU 导出 AWS CloudHSM 密钥的明文副本

使用 AWS CloudHSM 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 在文件中查找相关属性值。

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

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 命令通过使用会话密钥（密钥 8）作为包装密钥来导出密钥 262168。

当会话结束时，密钥 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（字数统计）工具。

$  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 上使用包装密钥解开包装。

相关主题