genSymKey - AWS CloudHSM
语法示例Parameters相关 主题

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

genSymKey

key_mgmt_util 工具中的 genSymKey 命令可在 HSM 中生成对称密钥。您可以指定密钥类型和大小、分配 ID 和标签以及与其他 HSM 用户共享密钥。您还可以创建不可提取的密钥以及将在会话结束时过期的密钥。如果命令成功，则返回 HSM 分配给密钥的密钥句柄。您可以使用该密钥句柄来为其他命令标识密钥。

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

语法

genSymKey -h

genSymKey -t <key-type>
          -s <key-size> 
          -l <label> 
          [-id <key-ID>] 
          [-min_srv <minimum-number-of-servers>] 
          [-m_value <0..8>]
          [-nex] 
          [-sess] 
          [-timeout <number-of-seconds> ]
          [-u <user-ids>] 
          [-attest]

示例

这些示例演示如何使用 genSymKey 在 HSM 中创建对称密钥。

提示

要将您在这些示例中创建的密钥用于 HMAC 操作，则必须在生成密钥后将 OBJ_ATTR_SIGN 和 OBJ_ATTR_VERIFY 设置为 TRUE。要设置这些值，请在 CloudHSM 管理实用程（CMU）中使用setAttribute。更多信息，请参阅 setAttribute。

例 ：生成 AES 密钥

此命令将创建一个具有 aes256 标签的 256 位 AES 密钥。输出显示，新密钥的密钥句柄为 6。

Command: genSymKey -t 31 -s 32 -l aes256

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 6

        Cluster Error Status
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
例 ：创建会话密钥

此命令将创建仅在当前会话中有效的不可提取的 192 位 AES 密钥。您可能希望创建一个与此类似的密钥来包装 (然后立即解开包装) 正导出的密钥。

Command: genSymKey -t 31 -s 24 -l tmpAES -id wrap01 -nex -sess
例 ：快速返回

此命令将创建一个具有 IT_test_key 标签的通用 512 字节密钥。此命令不会等待该密钥同步到群集中的所有 HSM。相反，此命令将在任何一个 HSM (-min_srv 1) 上创建该密钥或在 1 秒 (-timeout 1) 后返回，以时间较短者为准。如果该密钥在超时前未同步到指定最少数量的 HSM，则不会生成。您可能希望在脚本中使用与此类似的命令创建许多密钥，如以下示例中的 for 循环。

Command: genSymKey -t 16 -s 512 -l IT_test_key -min_srv 1 -timeout 1

$  for i in {1..30}; 
     do /opt/cloudhsm/bin/key_mgmt_util singlecmd loginHSM -u CU -s example_user -p example_pwd genSymKey -l aes -t 31 -s 32 -min_srv 1 -timeout 1; 
 done;
例 ：创建仲裁授权通用密钥

此命令将创建一个具有 generic-mV2 标签的 2048 位通用机密密钥。此命令使用 -u 参数与另一 CU (用户 6) 共享此密钥。对于使用此密钥的任何加密操作，它使用 -m_value 参数以要求至少有两个审批者的仲裁。此命令还使用 -attest 参数来验证生成密钥的固件的完整性。

输出显示，此命令已生成一个具有密钥句柄 9 的密钥以及已通过群集固件上的鉴证检查。


                Command:  genSymKey -t 16 -s 2048 -l generic-mV2 -m_value 2 -u 6 -attest

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 9

        Attestation Check : [PASS]

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
例 ：创建并检查密钥

此命令将创建一个具有 3DES_shared 标签和 IT-02 ID 的三重 DES 密钥。此密钥可由当前用户、用户 4 和用户 5 使用。如果该 ID 在群集中不唯一或当前用户为用户 4 或 5，则此命令将失败。

输出显示，新密钥具有密钥句柄 7。

Command: genSymKey -t 21 -s 24 -l 3DES_shared -id IT-02 -u 4,5

       Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 7

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

要验证新的 3DES 密钥是否由当前用户拥有并与用户 4 和 5 共享，请使用 getKeyInfo。此命令使用分配给新密钥的句柄 (Key Handle: 7)。

输出确认，此密钥由用户 3 所有并与用户 4 和 5 共享。

Command:  getKeyInfo -k 7

        Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS

        Owned by user 3

        also, shared to following 2 user(s):

                 4, 5

要确认密钥的其他属性，请使用 getAttribute。第一个命令使用 getAttribute 获取密钥句柄 7 (-o 7) 的所有属性 (-a 512)。它将这些属性写入 attr_7 文件。第二个命令使用 cat 获取 attr_7 文件的内容。

此命令确认，密钥 7 是具有标签 3DES_shared (OBJ_ATTR_LABEL 3DES_shared) 和 IT_02 (OBJ_ATTR_ID IT-02) ID 的 192 位 (OBJ_ATTR_VALUE_LEN 0x00000018 或 24 字节) 3DES (OBJ_ATTR_KEY_TYPE 0x15) 对称密钥 (OBJ_ATTR_CLASS 0x04)。此密钥是永久密钥 (OBJ_ATTR_TOKEN 0x01) 和可提取密钥 (OBJ_ATTR_EXTRACTABLE 0x01)，并且可用于加密、解密和包装。

提示

要查找您所创建密钥的属性（例如类型、长度、标签和 ID），请使用 getAttribute。要查找特定用户的密钥，请使用 getKeyInfo 。要根据属性值查找密钥，请使用 findKey。

有关解释密钥属性的帮助，请参阅 密钥属性引用。

Command:  getAttribute -o 7 -a 512 -out attr_7

got all attributes of size 444 attr cnt 17
Attributes dumped into attr_7 file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS


$  cat attr_7

OBJ_ATTR_CLASS
0x04
OBJ_ATTR_KEY_TYPE
0x15
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x01
OBJ_ATTR_ENCRYPT
0x01
OBJ_ATTR_DECRYPT
0x01
OBJ_ATTR_WRAP
0x00
OBJ_ATTR_UNWRAP
0x00
OBJ_ATTR_SIGN
0x00
OBJ_ATTR_VERIFY
0x00
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x01
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
3DES_shared
OBJ_ATTR_ID
IT-02
OBJ_ATTR_VALUE_LEN
0x00000018
OBJ_ATTR_KCV
0x59a46e
提示

要将您在这些示例中创建的密钥用于 HMAC 操作，则必须在生成密钥后将 OBJ_ATTR_SIGN 和 OBJ_ATTR_VERIFY 设置为 TRUE。要设置这些值，请在 CMU 中使用 setAttribute。更多信息，请参阅 setAttribute。

Parameters

-h

显示该命令的帮助信息。

必需：是

-t

指定对称密钥的类型。输入表示密钥类型的常量。例如，要创建 AES 密钥，请键入 -t 31。

有效值：

必需：是

-s

指定以字节为单位的密钥大小。例如，要创建 192 位密钥，请键入 24。

每种密钥类型的有效值如下：

  • AES：16 (128 位)、24 (192 位)、32 (256 位)

  • 3DES：24 (192 位)

  • 通用密钥：<3584（28672 位）

必需：是

-l

指定用户定义的密钥标签。键入字符串。

您可使用任何短语，以帮助您识别密钥。由于标签并非唯一，因此您可将其用于分组和分类密钥。

必需：是

-attest

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

默认：不执行认证检查。

必需：否

-id

为密钥指定用户定义标识符。在集群中键入唯一字符串。默认值是空字符串。

默认值：无 ID 值。

必需：否

-min_srv

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

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

默认值：1

必需：否

-m_value

指定必须批准使用密钥进行任何加密操作的用户数量。键入 0 至 8 范围的值。

此参数规定了密钥的仲裁身份验证要求。默认值 0 表明禁用密钥的仲裁身份验验证功能。启用仲裁身份验证后，必须有指定数量的用户签署令牌，才能批准使用密钥的加密操作，以及共享或不共享密钥的操作。

要查找密钥的 m_value 用户，请使用 getKeyInfo。

只有当命令中的 -u 参数与足够多的用户共享密钥以满足 m_value 要求时，此参数才有效。

默认值：0

必需：否

-nex

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

默认：密钥可提取。

必需：否

-sess

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

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

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

默认：密钥永久有效。

必需：否

-timeout

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

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

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

必需：否

-u

与指定用户共享密钥。此参数向其他 HSM 加密用户 (CU) 授予在加密操作中使用此密钥的权限。

键入一个逗号分隔的 HSM 用户 ID 列表，例如 -u 5,6。请勿包括当前用户的 HSM 用户 ID。要查找 HSM 上的 CU 的 HSM 用户 ID，请使用 listUsers。要共享或取消共享现有密钥，请在 cloudhsm_mgmt_util 中使用 shareKey。

默认：只有当前用户可使用密钥。

必需：否

相关 主题