本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
imSymKey
key_mgmt_util 工具中的 imSymKey 命令可將檔案中對稱金鑰的純文字複本匯入 HSM。您可以使用它來匯入 HSM 以外任何方法所產生的金鑰，以及從 HSM 匯出的金鑰，例如exSymKey、命令寫入檔案的金鑰。
在匯入過程中，imSymKey 會使用您選取的 AES 金鑰 (「包裝金鑰」) 來「包裝」(加密) 然後「取消包裝」(解密) 要匯入的金鑰。不過，imSymKey 僅適用於包含純文字金鑰的檔案。若要匯出和匯入加密金鑰，請使用 wrapKey 和unWrapKey指令。
此外，imSymKey 命令只匯出對稱金鑰。若要匯入公有金鑰，請使用 importPubKey。要導入私鑰，請使用importPrivateKey或 wrapKey。
注意
您無法使用對稱或私有金鑰匯入受密碼保護的 PEM 金鑰。
匯入的金鑰運作方式非常類似於 HSM 中產生的金鑰。不過，OBJ_ATTR_LOCAL 屬性的值為零，表示其不是在本機產生。當您匯入對稱金鑰時，您可以使用以下命令來共用金鑰。匯入金鑰之後，您可以在 shareKeycloudhsm_mgmt_util 中使用 命令來共用金鑰。
imSymKey -l aesShared -t 31 -f kms.key -w 3296 -u 5
在您匯入金鑰之後，請務必標記或刪除金鑰檔案。此命令不會阻止您將相同的金鑰資料匯入許多次。結果 (具有不同金鑰控制代碼和相同金鑰資料的多個金鑰) 會難以追蹤金鑰資料的使用情形，也就很難防止超過其加密限制。
執行任何 key_mgmt_util 命令之前，您必須先啟動 key_mgmt_util 並以加密使用者 (CU) 的身分登入 HSM。
語法
imSymKey -h imSymKey -f <key-file> -w <wrapping-key-handle> -t <key-type> -l <label> [-id <key-ID>] [-sess] [-wk <wrapping-key-file> ] [-attest] [-min_srv <minimum-number-of-servers>] [-timeout <number-of-seconds> ] [-u <user-ids>]
範例
以下範例示範如何使用 imSymKey 將對稱金鑰匯入 HSM。
範例 ：匯入 AES 對稱金鑰
這個範例使用 imSymKey 將 AES 對稱金鑰匯入 HSM。
第一個命令使用 OpenSSL 產生隨機 256 位元 AES 對稱金鑰。此命令將金鑰儲存在 aes256.key 檔案中。
$openssl rand -out aes256-forImport.key 32
第二個命令使用 imSymKey，將 aes256.key 檔案中的 AES 金鑰匯入 HSM。此命令使用金鑰 20 (HSM 中的 AES 金鑰) 作為包裝金鑰，並指定標籤為 imported。與 ID 不同，標籤在叢集內不需要是唯一的。-t (類型) 參數的值是 31，代表 AES。
輸出顯示檔案中的金鑰已包裝和取消包裝，然後匯入 HSM 中，並於其中指派金鑰控制代碼 262180。
Command:imSymKey -f aes256.key -w 20 -t 31 -l importedCfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Unwrapped. Key Handle: 262180 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
下一個命令使用 getAttribute，以取得新匯入之金鑰的 OBJ_ATTR_LOCAL 屬性 (屬性 355)，並將此屬性寫入 attr_262180 檔案。
Command:getAttribute -o 262180 -a 355 -out attributes/attr_262180Attributes dumped into attributes/attr_262180_imported file Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS
當您檢查屬性檔案時，您可以看到 OBJ_ATTR_LOCAL 屬性值為零，這表示在金鑰資料不是在 HSM 中產生。
$cat attributes/attr_262180_localOBJ_ATTR_LOCAL 0x00000000
範例 ：在叢集之間移動對稱金鑰
此範例顯示如何在叢集之間使用exSymKey和imSymKey移動純文字 AES 金鑰。您可以使用像這樣的程序來建立 AES 包裝，而此 AES 包裝同時存在於兩個叢集的 HSM 上。一旦共享包裝密鑰到位，您可以使用 wrapKey 和集群之間unWrapKey移動加密密鑰。
執行此操作的 CU 使用者必須有許可，而能夠登入兩個叢集上的 HSM。
第一個命令使exSymKey用將密鑰 14（32 位元 AES 金鑰）從叢集 1 匯出到aes.key檔案中。此命令使用金鑰 6 (叢集 1 的 HSM 上的 AES 金鑰) 作為包裝金鑰。
Command:exSymKey -k 14 -w 6 -out aes.keyCfm3WrapKey returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS Wrapped Symmetric Key written to file "aes.key"
接著，使用者在叢集 2 登入 key_mgmt_util，並執行 imSymKey 命令，將 aes.key 檔案中的金鑰匯入叢集 2 的 HSM。此命令使用金鑰 252152 (叢集 2 的 HSM 上的 AES 金鑰) 作為包裝金鑰。
由於包裝鍵exSymKey並imSymKey使用包裝並立即解開目標鍵，因此不同集群上的包裝鍵不需要相同。
輸出顯示金鑰已成功匯入叢集 2，且指派的金鑰控制代碼為 21。
Command:imSymKey -f aes.key -w 262152 -t 31 -l xclusterCfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Unwrapped. Key Handle: 21 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
若要證明叢集 1 的金鑰 14 和叢集 2 的金鑰 21 有相同的金鑰資料，請取得每個金鑰的金鑰檢查值 (KCV)。如果 KCV 值相同，即表示金鑰資料相同。
以下命令在叢集 1 使用 getAttribute，將金鑰 14 的 KCV 屬性 (屬性 371) 的值寫入 attr_14_kcv 檔案。然後，使用 cat 命令取得 attr_14_kcv 檔案的內容。
Command:getAttribute -o 14 -a 371 -out attr_14_kcvAttributes dumped into attr_14_kcv file$cat attr_14_kcvOBJ_ATTR_KCV 0xc33cbd
以下類似的命令在叢集 2 使用 getAttribute，將金鑰 21 的 KCV 屬性 (屬性 371) 的值寫入 attr_21_kcv 檔案。然後，使用 cat 命令取得 attr_21_kcv 檔案的內容。
Command:getAttribute -o 21 -a 371 -out attr_21_kcvAttributes dumped into attr_21_kcv file$cat attr_21_kcvOBJ_ATTR_KCV 0xc33cbd
輸出顯示兩個金鑰的 KCV 值相同，這證明金鑰資料相同。
由於相同的金鑰資料同時存在於兩個叢集的 HSM 中，您現在可以在叢集之間共用加密的金鑰，而完全不需要公有純文字金鑰。例如，您可以對包裝金鑰 14 使用 wrapKey 命令，從叢集 1 匯出加密的金鑰，然後對包裝金鑰 21 使用 unWrapKey，將加密的金鑰匯入叢集 2。
範例 ：匯入工作階段金鑰
此命令使用 imSymKey 的 -sess 參數，以匯入只在目前工作階段中有效的 192 位元三重 DES 金鑰。
此命令使用 -f 參數來指定包含要匯入之金鑰的檔案、使用 -t 參數來指定金鑰類型，以及使用 -w 參數來指定包裝金鑰。此命令使用 -l 參數來指定金鑰的分類標籤，也使用 -id 參數來建立金鑰的易記 (且唯一的) 識別符。另外還使用 -attest 參數來驗證用於匯入金鑰的韌體。
輸出顯示金鑰已成功包裝和取消包裝、已匯入 HSM 中，且指派的金鑰控制代碼為 37。此外，也已通過證實檢查，表示韌體未被篡改。
Command:imSymKey -f 3des192.key -w 6 -t 21 -l temp -id test01 -sess -attestCfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Unwrapped. Key Handle: 37 Attestation Check : [PASS] Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
接著，您可以使用 getAttribute 或 findKey 命令，以驗證新匯入之金鑰的屬性。以下命令使用 findKey，以驗證金鑰 37 具有命令所指定的類型、標籤和 ID，而且是工作階段金鑰。如輸出的第 5 行所示，findKey 報告唯一符合所有屬性的金鑰是金鑰 37。
Command:findKey -t 21 -l temp -id test01 -sess 1Total number of keys present 1 number of keys matched from start index 0::0 37 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS
參數
- -attest
執行完整性檢查，以驗證執行叢集的韌體未被篡改。
預設：無認證檢查。
必要：否
- -f
-
指定檔案，其中包含要匯入的金鑰。
這個檔案必須包含具有指定長度之 AES 或三重 DES 金鑰的純文字副本。RC4 和 DES 金鑰不適用於 FIPS 模式的 HSM。
-
AES：16、24 或 32 位元組
-
三重 DES (3DES)：24 位元組
必要：是
-
- -h
-
顯示命令的說明。
必要：是
- -id
-
指使用者定義的金錀識別符。輸入叢集中唯一的字串。預設為空字串。
預設：無 ID 值。
必要：否
- -l
-
指使用者定義的金錀對標籤。輸入一個字串。
您可以使用任何可以幫助您識別金錀的片語。標籤不具唯一性，因此您可使用標籤將金錀進行分組和分類。
必要：是
- -min_srv
-
指在
-timeout參數值過期之前同步金鑰所需的 HSM 數量下限。如果未在規定時間內同步至指定數量的伺服器，金鑰就不會建立。AWS CloudHSM 自動將每個金鑰同步到叢集中的每個 HSM。要加速流程，請將
min_srv值設定為少於叢集中之 HSM 的數量，並設定低逾時值。然而，請注意有些請求可能不會產生金鑰。預設：1
必要：否
- -sess
-
建立只在目前工作階段中存在的金鑰。工作階段結束後，金鑰無法復原。
當您僅短暫需要金鑰 (例如，加密後快速解密另一個金鑰的包裝金鑰) 時，請使用此參數。請勿使用工作階段金鑰來加密工作階段結束後可能需要解密的資料。
若要將工作階段金鑰更改為持久性 (權杖) 金鑰，請使用 setAttribute。
預設：此金鑰是持久性金鑰。
必要：否
- -timeout
-
指命令等待金鑰同步到
min_srv參數指定數目的 HSM 的時長 (以秒為單位)。此參數只有在命令中同時使用
min_srv參數時才有效。預設：無逾時。該命令會無限期等待，並且僅在將金錀同步到最小數目的伺服器時才返回。
必要：否
- -t
-
指對稱金鑰的類型。輸入代表金鑰類型的常數。例如，若要建立 AES 金鑰，請輸入
-t 31。有效值：
-
21：三重 DES (3DES)
。 -
31：AES
必要：是
-
- -u
-
將您匯入的金鑰共用給指定的使用者。此參數授與其他 HSM 密碼使用者 (CU) 在密碼編譯操作中使用此金鑰的許可。
輸入一個 ID，或以逗號分隔的 HSM 使用者 ID 清單，例如 -u
5,6。請勿包含現行使用者的 HSM 使用者 ID。若要尋找 ID，您可以在 cloudhsm_mgmt_util 命令列工具中使用 listUsers 命令，或在 key_mgmt_util 命令列工具中使用 listUsers 命令。必要：否
- -w
-
指定包裝金鑰的金鑰控制代碼。此為必要參數。若要找出金鑰控制代碼，請使用 findKey 命令。
包裝金鑰是 HSM 中的金鑰，用於匯入過程中加密 (包裝) 然後解密 (取消包裝) 金鑰。只有 AES 金鑰可以做為包裝金鑰。
您可以使用任何 AES 金鑰 (任何大小) 做為包裝金鑰。因為包裝金鑰將目標金鑰包裝後又立即取消包裝，您可以使用僅限工作階段的 AES 金鑰做為包裝金鑰。若要判斷金鑰是否可作為包裝金鑰，請使用 getAttribute 以取得
OBJ_ATTR_WRAP屬性 (262) 的值。若要建立包裝金鑰，請genSymKey使用建立 AES 金鑰 (類型 31)。如果您使用
-wk參數來指定外部包裝金鑰，則會使用-w包裝金鑰來取消包裝 (而不是包裝) 要匯入的金鑰。注意
金鑰 4 是不支援的內部金鑰。建議您使用您所建立並做為包裝金鑰管理的 AES 金鑰。
必要：是
- -wk
-
使用指定檔案中的 AES 金鑰來包裝要匯入的金鑰。輸入包含純文字 AES 金鑰的檔案路徑和名稱。
當您加入此參數時，imSymKey 會使用
-wk檔案中的金鑰來包裝要匯入的金鑰，並使用由-w參數在 HSM 中指定的金鑰來取消包裝此金鑰。-w和-wk參數值必須解析為相同的純文字金鑰。預設：使用 HSM 上的包裝金鑰來取消包裝。
必要：否
相關主題
