unWrapKey - AWS CloudHSM
語法範例參數相關主題

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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 機制棄用。

相關主題