本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
unWrapKey
key_mgmt_util 工具中的 unWrapKey 命令可將檔案中包裝 (加密) 的對稱或私有金鑰匯入到 HSM。此命令旨在匯入由 key_mgmt_util 中 wrapKey 命令包裝的加密金鑰,同時也可對使用其他工具包裝的金鑰取消包裝。不過,在這些情況下,我們建議您使用 PKCS#11 或 JCE 軟體程式庫來取消包裝金鑰。
匯入的金鑰的運作方式就像產生的 AWS CloudHSM金鑰 不過,其 OBJ_ATTR_LOCAL 屬性值為零,表示其不是在本機產生。
匯入金鑰後,請務必標示或刪除金鑰檔案。此命令不會阻止您將相同的金鑰資料匯入許多次。結果 (具有不同金鑰控制代碼和相同金鑰資料的多個金鑰) 會難以追蹤金鑰資料的使用情形,也就很難防止超過其加密限制。
執行任何 key_mgmt_util 命令之前,您必須先啟動 key_mgmt_util 並以加密使用者 (CU) 的身分登入 HSM。
語法
unWrapKey -h unWrapKey -f
<key-file-name>
-w<wrapping-key-handle>
[-sess] [-min_srv<minimum-number-of-HSMs>
] [-timeout<number-of-seconds>
] [-aad<additional authenticated data filename>
] [-tag_size<tag size>
] [-iv_file<IV file>
] [-attest] [-m<wrapping-mechanism>
] [-t<hash-type>
] [-nex] [-u<user id list>
] [-m_value<number of users needed for approval>
] [-noheader] [-l<key-label>
] [-id<key-id>
] [-kt<key-type>
] [-kc<key-class
] [-i<unwrapping-IV>
]
範例
這些範例示範如何使用 unWrapKey 將檔案的包裝金鑰匯入 HSM。在第一個範例中,我們取消包裝由 wrapKey key_mgmt_util 命令包裝的金鑰,因此有標頭。在第二個範例中,我們取消包裝在 key_mgmt_util 外部包裝的金鑰,因此不會有標頭。
範例 :取消包裝金鑰 (含標頭)
此命令可將 3DES 對稱金鑰的包裝複本匯入 HSM。此金鑰是使用標籤為 6
的 AES 金鑰取消包裝,其加密方式與用來包裝 3DES 金鑰的金鑰相同。此輸出說明檔案中的金鑰已取消包裝並匯入,且匯入金鑰的控制代碼為 29
。
Command:
unWrapKey -f 3DES.key -w 6 -m 4
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS Key Unwrapped. Key Handle: 29 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
範例 :取消包裝金鑰 (無標頭)
此命令可將 3DES 對稱金鑰的包裝複本匯入 HSM。此金鑰是使用標籤為 6
的 AES 金鑰取消包裝,其加密方式與用來包裝 3DES 金鑰的金鑰相同。由於這個 3DES 金鑰並非使用 key_mgmt_util 包裝,因此指定了 noheader
參數,以及其必要的相關參數:金鑰標籤 (unwrapped3DES
)、金鑰類別 (4
) 和金鑰類型 (21
)。此輸出說明檔案中的金鑰已取消包裝並匯入,且匯入金鑰的控制代碼為 8
。
Command:
unWrapKey -f 3DES.key -w 6 -noheader -l unwrapped3DES -kc 4 -kt 21 -m 4
Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS Cfm2UnWrapWithTemplate3 returned: 0x00 : HSM Return: SUCCESS Key Unwrapped. Key Handle: 8 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
參數
- -h
-
顯示命令的說明。
必要:是
- -f
-
包含包裝金鑰的檔案路徑和名稱。
必要:是
- -w
-
指定包裝金鑰。輸入 HSM 上 AES 金鑰或 RSA 金錀的金鑰控制代碼。此為必要參數。若要找出金鑰控制代碼,請使用 findKey 命令。
要創建一個包裝密鑰,使genSymKey用生成一個 AES 密鑰(類型 31)或 genRSA 生KeyPair成一個 RSA key pair(類型 0)。如果您使用 RSA 金鑰對,請務必使用其中一個金鑰包裝該金鑰,並使用另一個金鑰對其取消包裝。如要驗證金鑰是否可做為包裝金鑰,請使用 getAttribute 取得
OBJ_ATTR_WRAP
的屬性值 (以常數262
表示)。必要:是
- -sess
-
建立只在目前工作階段中存在的金鑰。工作階段結束後,金鑰無法復原。
當您僅短暫需要金鑰 (例如,加密後快速解密另一個金鑰的包裝金鑰) 時,請使用此參數。請勿使用工作階段金鑰來加密工作階段結束後可能需要解密的資料。
若要將工作階段金鑰更改為持久性 (權杖) 金鑰,請使用 setAttribute。
預設:此金鑰是持久性金鑰。
必要:否
- -min_srv
-
指在
-timeout
參數值過期之前同步金鑰所需的 HSM 數量下限。如果未在規定時間內同步至指定數量的伺服器,金鑰就不會建立。AWS CloudHSM 自動將每個金鑰同步到叢集中的每個 HSM。要加速流程,請將
min_srv
值設定為少於叢集中之 HSM 的數量,並設定低逾時值。然而,請注意有些請求可能不會產生金鑰。預設:1
必要:否
- -timeout
-
指命令等待金鑰同步到
min_srv
參數指定數目的 HSM 的時長 (以秒為單位)。此參數只有在命令中同時使用
min_srv
參數時才有效。預設:無逾時。該命令會無限期等待,並且僅在將金錀同步到最小數目的伺服器時才返回。
必要:否
- -attest
執行完整性檢查,以驗證執行叢集的韌體未被篡改。
預設:無認證檢查。
必要:否
- -nex
-
使金鑰無法擷取。產生的金鑰無法從 HSM 匯出。
預設:此金鑰可擷取。
必要:否
- -m
-
表示包裝機制的值。CloudHSM 支援以下機制:
Mechanism Value AES_KEY_WRAP_PAD_PKCS5
4 NIST_AES_WRAP_NO_PAD
5 NIST_AES_WRAP_PAD
6 RSA_AES
7 RSA_OAEP
(如需資料大小上限,請參閱本節後文的備註)8 AES_GCM
10 CLOUDHSM_AES_GCM
11 RSA_PKCS
(如需資料大小上限,請參閱本節後文的備註)。請參閱下列備註 1 查看即將進行的變更。12 必要:是
注意
使用
RSA_OAEP
包裝機制時,您可以換行的最大金鑰大小取決於 RSA 金鑰的模數和指定雜湊的長度,如下所示:最大金鑰大小 = modulusLengthIn 位元組-(2* 位元hashLengthIn組) -2。使用 RSA_PKCS 環繞機制時,您可以換行的最大金鑰大小由 RSA 金鑰的模數決定,如下所示:最大金鑰大小 = (位元組 -11)。modulusLengthIn
- -t
-
雜湊演算法 Value SHA1
2 SHA256
3 SHA384
4 SHA512
5 SHA224
(對RSA_AES
和RSA_OAEP
機制有效)6 必要:否
- -noheader
-
如果您的金鑰是在 key_mgmt_util 外部包裝,則您必須指定此參數和所有其他相關參數。
必要:否
注意
指定此參數時,您也必須指定下列
-noheader
參數:-
-l
指定要新增到取消包裝金鑰的標籤。
必要:是
-
-kc
指定要取消包裝的金鑰類別。以下是可接受的值:
3 = 來自公私金鑰對的私有金鑰
4 = 私密 (對稱) 金鑰
必要:是
-
-kt
指定要取消包裝的金鑰類型。以下是可接受的值:
0 =
RSA
1 =
DSA
3 =
ECC
16 =
GENERIC_SECRET
21 =
DES3
31 =
AES
必要:是
您也可以選擇指定以下
-noheader
參數:-
-id
要新增到取消包裝金鑰的 ID。
必要:否
-
-i
要使用的取消包裝初始化向量 (IV)。
必要:否
-
[1] 根據 NIST 指引,在 2023 年之後,FIPS 模式下的叢集不允許這樣做。對於處於非 FIP 模式的叢集,在 2023 之後仍然允許使用該叢集。如需詳細資訊,請參閱 FIPS 140 合規性:2024 機制棄用。