本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 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** 在 HSM 中建立對稱金鑰。 **提示** 如要使用您在這些範例中建立的金鑰進行 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 位元組金鑰。此命令不會等待金鑰同步至叢集內的所有 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; ``` **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` 和 ID 為 `IT-02` 的三重 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 是 192 位元 (`OBJ_ATTR_VALUE_LEN 0x00000018` 或 24 位元組) 3DES (`OBJ_ATTR_KEY_TYPE 0x15`) 對稱金鑰 (`OBJ_ATTR_CLASS 0x04`)，標籤為 `3DES_shared` (`OBJ_ATTR_LABEL 3DES_shared`)，ID 為 `IT_02` (`OBJ_ATTR_ID IT-02`)。金鑰是持久性 (`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)。 ## Parameters **-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 模式的 HSM + 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** 指在 `-timeout` 參數值過期之前同步金鑰所需的 HSM 數量下限。如果未在規定時間內同步至指定數量的伺服器，金鑰就不會建立。 AWS CloudHSM 會自動將每個金鑰同步到叢集中的每個 HSM。要加速流程，請將 `min_srv` 值設定為少於叢集中之 HSM 的數量，並設定低逾時值。然而，請注意有些請求可能不會產生金鑰。預設：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` 參數指定數目的 HSM 的時長 (以秒為單位)。此參數只有在命令中同時使用 `min_srv` 參數時才有效。預設：無逾時。該命令會無限期等待，並且僅在將金錀同步到最小數目的伺服器時才返回。必要：否 **-u** 將金鑰共用給指定的使用者。此參數授與其他 HSM 密碼使用者 (CU) 在密碼編譯操作中使用此金鑰的許可。輸入以逗號分隔的 HSM 使用者 ID 清單，例如 -`u 5,6`。請勿包含現行使用者的 HSM 使用者 ID。若要尋找 HSM 上 CU 的 HSM 使用者 ID，請使用 [listUsers](key_mgmt_util-listUsers.md)。之後，如要共用或取消共用現有金鑰，請使用 cloudhsm\_mgmt\_util 中的 [shareKey](cloudhsm_mgmt_util-shareKey.md)。預設：只有現行使用者能夠使用此金鑰。必要：否 ## 相關主題 + [exSymKey](key_mgmt_util-exSymKey.md) + [genRSAKeyPair](key_mgmt_util-genRSAKeyPair.md) + [genDSAKeyPair](key_mgmt_util-genDSAKeyPair.md) + [genECCKeyPair](key_mgmt_util-genECCKeyPair.md) + [setAttribute](cloudhsm_mgmt_util-setAttribute.md)