本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
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。
参数
- -h
-
显示该命令的帮助信息。
必需:是
- -t
-
指定对称密钥的类型。输入表示密钥类型的常量。例如,要创建 AES 密钥,请键入
-t 31
。有效值:
-
16:GENERIC_SECRET
。通用机密密钥 是一个字节数组,不符合任何特定标准 (如 AES 密钥的要求)。 -
18:RC4
。RC4 密钥在 FIPS 模式的 HSM 上无效 -
21:三重 DES (3DES)
。根据 NIST 的指导方针,2023 年之后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群,2023 年之后仍允许这样做。有关详细信息,请参阅 FIPS 140 合规:2024 年机制弃用。 -
31:AES
必需:是
-
- -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。默认:只有当前用户可使用密钥。
必需:否