本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
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
和 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 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 是 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。若要尋找特定使用者的金鑰,請使用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 模式下的叢集不允許這樣做。對於處於非 FIP 模式的叢集,在 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。預設:只有現行使用者能夠使用此金鑰。
必要:否