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

# 使用 KMU 取消包裝 AWS CloudHSM 金鑰
<a name="key_mgmt_util-unwrapKey"></a>

使用 AWS CloudHSM key\_mgmt\_util 工具中的 **unWrapKey**命令，將包裝 （加密） 對稱或私有金鑰從檔案匯入 HSM。此命令旨在匯入由 key\_mgmt\_util 中 [wrapKey](key_mgmt_util-wrapKey.md) 命令包裝的加密金鑰，同時也可對使用其他工具包裝的金鑰取消包裝。不過，在這些情況下，我們建議您使用 [PKCS\#11](pkcs11-library.md) 或 [JCE](java-library.md) 軟體程式庫來取消包裝金鑰。

匯入的金鑰的運作方式與 產生的金鑰相同 AWS CloudHSM。不過，其 [OBJ\_ATTR\_LOCAL 屬性](key-attribute-table.md)值為零，表示其不是在本機產生。

匯入金鑰後，請務必標示或刪除金鑰檔案。此命令不會阻止您將相同的金鑰資料匯入許多次。結果 (具有不同金鑰控制代碼和相同金鑰資料的多個金鑰) 會難以追蹤金鑰資料的使用情形，也就很難防止超過其加密限制。

執行任何 key\_mgmt\_util 命令之前，您必須先[啟動 key\_mgmt\_util](key_mgmt_util-setup.md#key_mgmt_util-start) 並以加密使用者 (CU) 的身分[登入](key_mgmt_util-log-in.md) HSM。

## 語法
<a name="unwrapKey-syntax"></a>

```
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>}}]
```

## 範例
<a name="unwrapKey-examples"></a>

這些範例示範如何使用 **unWrapKey** 將檔案的包裝金鑰匯入 HSM。在第一個範例中，我們取消包裝由 **[wrapKey](key_mgmt_util-wrapKey.md)** key\_mgmt\_util 命令包裝的金鑰，因此有標頭。在第二個範例中，我們取消包裝在 key\_mgmt\_util 外部包裝的金鑰，因此不會有標頭。

**Example ：取消包裝金鑰 (含標頭)**  
此命令可將 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
```

**Example ：取消包裝金鑰 (無標頭)**  
此命令可將 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
```

## Parameters
<a name="unwrapKey-params"></a>

**-h**  
顯示命令的說明。  
必要：是

**-f**  
包含包裝金鑰的檔案路徑和名稱。  
必要：是

**-w**  
指定包裝金鑰。輸入 HSM 上 AES 金鑰或 RSA 金錀的金鑰控制代碼。此為必要參數。若要找出金鑰控制代碼，請使用 [findKey](key_mgmt_util-findKey.md) 命令。  
如要創建一個包裝密鑰，請使用 [genSymKey](key_mgmt_util-genSymKey.md) 產生一個 AES 金錀 (類型 31) 或使用 [genRSAKeyPair](key_mgmt_util-genRSAKeyPair.md) 產生一個 RSA 金錀對 (類型 0)。如果您使用 RSA 金鑰對，請務必使用其中一個金鑰包裝該金鑰，並使用另一個金鑰對其取消包裝。如要驗證金鑰是否可做為包裝金鑰，請使用 [getAttribute](key_mgmt_util-getAttribute.md) 取得 `OBJ_ATTR_WRAP` 的屬性值 (以常數 `262` 表示)。  
必要：是

**-sess**  
建立只在目前工作階段中存在的金鑰。工作階段結束後，金鑰無法復原。  
當您僅短暫需要金鑰 (例如，加密後快速解密另一個金鑰的包裝金鑰) 時，請使用此參數。請勿使用工作階段金鑰來加密工作階段結束後可能需要解密的資料。  
若要將工作階段金鑰更改為持久性 (權杖) 金鑰，請使用 [setAttribute](key_mgmt_util-setAttribute.md)。  
預設：此金鑰是持久性金鑰。  
必要：否

**-min\_srv**  
指在 `-timeout` 參數值過期之前同步金鑰所需的 HSM 數量下限。如果未在規定時間內同步至指定數量的伺服器，金鑰就不會建立。  
AWS CloudHSM 會自動將每個金鑰同步到叢集中的每個 HSM。要加速流程，請將 `min_srv` 值設定為少於叢集中之 HSM 的數量，並設定低逾時值。然而，請注意有些請求可能不會產生金鑰。  
預設：1  
必要：否

**-timeout**  
指命令等待金鑰同步到 `min_srv` 參數指定數目的 HSM 的時長 (以秒為單位)。  
此參數只有在命令中同時使用 `min_srv` 參數時才有效。  
預設：無逾時。該命令會無限期等待，並且僅在將金錀同步到最小數目的伺服器時才返回。  
必要：否

**-attest**  
執行完整性檢查，以驗證執行叢集的韌體未被篡改。  
預設：無認證檢查。  
必要：否

**-nex**  
使金鑰無法擷取。產生的金鑰無法[從 HSM 匯出](export-keys.md)。  
預設：此金鑰可擷取。  
必要：否

**-m**  
表示包裝機制的值。CloudHSM 支援以下機制：      
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/key_mgmt_util-unwrapKey.html)
必要：是  
使用 `RSA_OAEP` 包裝機制時，您可以包裝的金鑰大小上限取決於 RSA 金鑰的模數和指定雜湊的長度，如下所示：金鑰大小上限 = modulusLengthInBytes-(2\*hashLengthInBytes)-2。  
使用 RSA\_PKCS 包裝機制時，您可以包裝的金鑰大小上限取決於 RSA 金鑰的模數，如下所示：金鑰大小上限 = (modulusLengthInBytes -11)。

**-t**      
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/key_mgmt_util-unwrapKey.html)
必要：否

**-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 模式下使用叢集。對於處於非 FIPS 模式的叢集，在 2023 年之後仍然允許。如需詳細資訊，請參閱 [FIPS 140 合規性：2024 機制棄用](compliance-dep-notif.md#compliance-dep-notif-1)。

## 相關主題
<a name="unwrapKey-seealso"></a>
+ [wrapKey](key_mgmt_util-wrapKey.md)
+ [exSymKey](key_mgmt_util-exSymKey.md)
+ [imSymKey](key_mgmt_util-imSymKey.md)