本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
使用 AWS CloudHSM 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，從叢集 1 將金鑰 14 (32 位元 AES 金鑰) 匯出到 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 上的包裝金鑰來取消包裝。
必要：否
相關主題
