本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 KMU 生成 AWS CloudHSM 对称密钥使用 AWS CloudHSM key\_mgmt\_util 工具中的**genSymKey**命令在硬件安全模块 (HSM) 中生成对称密钥。您可以指定密钥类型和大小、分配 ID 和标签以及与其他 HSM 用户共享密钥。您还可以创建不可提取的密钥以及将在会话结束时过期的密钥。如果命令成功，则返回 HSM 分配给密钥的密钥句柄。您可以使用该密钥句柄来为其他命令标识密钥。在运行任何 key\_mgmt\_util 命令之前，您必须[启动 key\_mgmt\_util](key_mgmt_util-setup.md#key_mgmt_util-start) 并以加密用户（CU）身份[登录](key_mgmt_util-log-in.md)到 HSM。 ## 语法 ``` genSymKey -h genSymKey -t {{}} -s {{}} -l {{}} [-id {{}}] [-min_srv {{}}] [-m_value {{<0..8>}}] [-nex] [-sess] [-timeout {{}} ] [-u {{}}] [-attest] ``` ## 示例这些示例说明了**genSymKey**如何使用在中创建对称密钥。 HSMs **提示** 要将您在这些示例中创建的密钥用于 HMAC 操作，则必须在生成密钥后将 `OBJ_ATTR_SIGN` 和 `OBJ_ATTR_VERIFY` 设置为 `TRUE`。要设置这些值，请在 CloudHSM 管理实用程（CMU）中使用 **setAttribute**。更多信息，请参阅 [setAttribute](cloudhsm_mgmt_util-setAttribute.md)。 **Example ：生成 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 ``` **Example ：创建会话密钥** 此命令将创建仅在当前会话中有效的不可提取的 192 位 AES 密钥。您可能希望创建一个与此类似的密钥来包装 (然后立即解开包装) 正导出的密钥。 ``` Command: genSymKey -t 31 -s 24 -l tmpAES -id wrap01 -nex -sess ``` **Example ：快速返回** 此命令将创建一个具有 `IT_test_key` 标签的通用 512 字节密钥。该命令不会等待密钥同步到集群 HSMs 中的所有人。相反，此命令将在任何一个 HSM (`-min_srv 1`) 上创建该密钥或在 1 秒 (`-timeout 1`) 后返回，以时间较短者为准。如果在超时到期 HSMs 之前，密钥未同步到指定的最小数量，则不会生成该密钥。您可能希望在脚本中使用与此类似的命令创建许多密钥，如以下示例中的 `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; ``` **Example ：创建仲裁授权通用密钥** 此命令将创建一个具有 `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 ``` **Example ：创建并检查密钥** 此命令将创建一个具有 `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_mgmt_util-getKeyInfo.md)**。此命令使用分配给新密钥的句柄 (`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](key_mgmt_util-getAttribute.md)。第一个命令使用 `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](key_mgmt_util-getAttribute.md)。要查找特定用户的密钥，请使用[getKeyInfo](key_mgmt_util-getKeyInfo.md)。要根据属性值查找密钥，请使用 [findKey](key_mgmt_util-findKey.md)。有关解释密钥属性的帮助，请参阅 [AWS CloudHSM KMU 的关键属性参考](key-attribute-table.md)。 ``` 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](cloudhsm_mgmt_util-setAttribute.md)。 ## 参数 **-h** 显示该命令的帮助信息。是否必需：是 **-t** 指定对称密钥的类型。输入表示密钥类型的常量。例如，要创建 AES 密钥，请键入 `-t 31`。有效值： + 16：[GENERIC\_SECRET](http://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cos01/pkcs11-curr-v2.40-cos01.html#_Toc408226962)。*通用机密密钥* 是一个字节数组，不符合任何特定标准 (如 AES 密钥的要求)。 + 18: [RC4](https://en.wikipedia.org/wiki/RC4)。 RC4 密钥在 FIPS 模式下无效 HSMs + 21：[三重 DES (3DES)](https://en.wikipedia.org/wiki/Triple_DES)。根据 NIST 指导，2023 年以后处于 FIPS 模式的集群不允许这样做。对于处于非 FIPS 模式的集群，2023 年之后仍然允许。有关详细信息，请参阅 [FIPS 140 合规：2024 年机制弃用](compliance-dep-notif.md#compliance-dep-notif-1)。 + 31：[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) 是否必需：是 **-s** 指定以字节为单位的密钥大小。例如，要创建 192 位密钥，请键入 `24`。每种密钥类型的有效值如下： + AES：16 (128 位)、24 (192 位)、32 (256 位) + 3DES：24 (192 位) + 通用密钥：<3584（28672 位）是否必需：是 **-l** 指定用户定义的密钥标签。键入字符串。您可使用任何短语，以帮助您识别密钥。由于标签并非唯一，因此您可将其用于分组和分类密钥。是否必需：是 **-attest** 运行完整性检查，以验证运行集群的固件是否被篡改。默认：不执行认证检查。必需：否 **-id** 为密钥指定用户定义标识符。在集群中键入唯一字符串。默认值是空字符串。默认值：无 ID 值。必需：否 **-min\_srv** 指定 HSMs 在`-timeout`参数值到期之前同步密钥的最小数量。如果密钥在分配的时间内未同步到指定数量的服务器，则不会创建它。 AWS CloudHSM 自动将每个密钥同步到集群中的每个 HSM。要加快处理速度，请将的值设置`min_srv`为小于群集 HSMs 中的数量，并设置一个较低的超时值。但请注意，一些请求可能无法生成密钥。默认：1 必需：否 **-m\_value** 指定必须批准使用密钥进行任何加密操作的用户数量。键入 `0` 至 `8` 范围的值。此参数规定了密钥的仲裁身份验证要求。默认值 `0` 表明禁用密钥的仲裁身份验验证功能。启用仲裁身份验证后，必须有指定数量的用户签署令牌，才能批准使用密钥的加密操作，以及共享或不共享密钥的操作。要查找密钥`m_value`的，请使用[getKeyInfo](key_mgmt_util-getKeyInfo.md)。只有当命令中的 `-u` 参数与足够多的用户共享密钥以满足 `m_value` 要求时，此参数才有效。默认：0 必需：否 **-nex** 使密钥无法提取。生成的私有密钥无法[从 HSM 导出](export-keys.md)。默认：密钥可提取。必需：否 **-sess** 创建仅在当前会话中存在的密钥。会话结束后，密钥无法恢复。如果您只需要一个短暂的密钥，例如用于加密然后快速解密另一个密钥的包装密钥，请使用此参数。对于会话结束后可能需要解密的加密数据，切勿使用会话密钥。若要将会话密钥更改为永久（令牌）密钥，请使用 [setAttribute](key_mgmt_util-setAttribute.md)。默认：密钥永久有效。必需：否 **-timeout** 指定命令等待密钥同步到`min_srv`参数所 HSMs 指定数量的时间（以秒为单位）。仅当 `min_srv` 参数也用于此命令时，该参数才有效。默认：没有超时该命令无限期等待，仅当密钥同步至最少数量的服务器时才返回。必需：否 **-u** 与指定用户共享密钥。此参数授予其他 HSM 加密用户 (CUs) 在加密操作中使用此密钥的权限。键入以逗号分隔的 HSM 用户列表 IDs，例如-。`u 5,6`请勿包括当前用户的 HSM 用户 ID。[要在 HSM CUs 上查找 HSM 用户 IDs ，请使用 ListUsers。](key_mgmt_util-listUsers.md)要共享或取消共享现有密钥，请在 cloudhsm\_mgmt\_util 中使用 [shareKey](cloudhsm_mgmt_util-shareKey.md)。默认：只有当前用户可使用密钥。必需：否 ## 相关主题 + [exSymKey](key_mgmt_util-exSymKey.md) + [RSAKey一代对](key_mgmt_util-genRSAKeyPair.md) + [DSAKey一代对](key_mgmt_util-genDSAKeyPair.md) + [ECCKey一代对](key_mgmt_util-genECCKeyPair.md) + [setAttribute](cloudhsm_mgmt_util-setAttribute.md)