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

# 使用 KMU 匯出 AWS CloudHSM 金鑰
<a name="key_mgmt_util-wrapKey"></a>

使用 AWS CloudHSM key\$1mgmt\$1util 中的 **wrapKey**命令，將對稱或私有金鑰的加密副本從硬體安全模組 (HSM) 匯出至檔案。執行 **wrapKey** 時，您會指定要匯出的金鑰、HSM 上用來加密 (包裝) 您要匯出之金鑰的金鑰，以及輸出檔。

`wrapKey` 命令會將加密金鑰寫入您指定的檔案，但不會從 HSM 中移除該金鑰，或阻止您在密碼編譯操作中使用該金鑰。您可以多次匯出相同的金鑰。

只有金鑰的擁有者 (也就是建立金鑰的加密使用者 (CU)) 可以匯出金鑰。共用金鑰的使用者可以在密碼編譯操作中使用它，但不能將它匯出。

若要將加密金鑰匯回 HSM，請使用 [unWrapKey](key_mgmt_util-unwrapKey.md)。若要從 HSM 匯出純文字金鑰，請視需要使用 [exSymKey](key_mgmt_util-exSymKey.md) 或 [exportPrivateKey](key_mgmt_util-exportPrivateKey.md)。[aesWrapUnwrap](key_mgmt_util-aesWrapUnwrap.md) 命令無法解密 (取消包裝) **wrapKey** 所加密的金鑰。

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

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

```
wrapKey -h

wrapKey -k <exported-key-handle>
        -w <wrapping-key-handle>
        -out <output-file>
        [-m <wrapping-mechanism>]
        [-aad <additional authenticated data filename>]
        [-t <hash-type>]
        [-noheader]
        [-i <wrapping IV>]  
        [-iv_file <IV file>]
        [-tag_size <num_tag_bytes>>]
```

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

**Example**  
此命令會將 192 位元的三重 DES (3DES) 對稱金鑰 (金鑰控制代碼 `7`) 匯出。它使用 HSM 中的 256 位元 AES 金鑰 (金鑰控制代碼 `14`) 來包裝金鑰 `7`。然後它會將加密的 3DES 金鑰寫入 `3DES-encrypted.key` 檔案。  
輸出顯示金鑰 `7` (3DES 金鑰) 已成功包裝並寫入指定的檔案。加密金鑰的長度為 307 個位元組。  

```
        Command:  wrapKey -k 7 -w 14 -out 3DES-encrypted.key -m 4

        Key Wrapped.

        Wrapped Key written to file "3DES-encrypted.key length 307

        Cfm2WrapKey returned: 0x00 : HSM Return: SUCCESS
```

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

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

**-k**  
您要匯出之金鑰的金鑰控制代碼。輸入您擁有之對稱或私有金鑰的金鑰控制代碼。若要找出金鑰控制代碼，請使用 [findKey](key_mgmt_util-findKey.md) 命令。  
若要確認金鑰是否匯出，請使用 [getAttribute](key_mgmt_util-getAttribute.md) 命令取得 `OBJ_ATTR_EXTRACTABLE` 屬性的值 (以常數 `354` 表示)。如需金錀屬性的解譯說明，請參閱 [AWS CloudHSM KMU 的金鑰屬性參考](key-attribute-table.md)。  
您只能匯出您擁有的金鑰。若要尋找金鑰的擁有者，請使用 [getKeyInfo](key_mgmt_util-getKeyInfo.md) 命令。  
必要：是

**-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` 表示)。  
必要：是

**-out**  
輸出檔案的路徑和名稱。命令成功時，這個檔案會包含匯出金鑰的加密複本。如果檔案已存在，命令會覆寫檔案且不會有任何警告。  
必要：是

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

**-t**  
表示雜湊演算法的值。CloudHSM 支援以下演算法：      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudhsm/latest/userguide/key_mgmt_util-wrapKey.html)
必要：否

**-aad**  
檔案名稱包含 `AAD`。  
僅對 `AES_GCM` 和 `CLOUDHSM_AES_GCM` 機制有效。
必要：否

**-noheader**  
忽略標頭，其指定 CloudHSM 特定的[金鑰屬性](key_mgmt_util-reference.md)。*僅限*您要使用 key\$1mgmt\$1util 以外的工具來取消包裝金鑰時，才使用此參數。  
必要：否

**-i**  
初始向量 (IV) (十六進位值)。  
只在使用 `CLOUDHSM_AES_KEY_WRAP` 和 `NIST_AES_WRAP` 機制的 `-noheader` 參數傳遞時有效。
必要：否

**-iv\$1file**  
您要寫入回應中包含之 IV 值的檔案。  
只在使用 `AES_GCM` 機制的 `-noheader` 參數傳遞時有效。
必要：否

**-tag\$1size**  
要與包裝的 Blob 一起儲存的標籤大小。  
只在使用 `AES_GCM` 和 `CLOUDHSM_AES_GCM` 機制的 `-noheader` 參數傳遞時有效。標籤大小下限為 8。
必要：否

【1】 根據 NIST 指引，在 2023 年之後，不允許在 FIPS 模式下使用叢集。對於處於非 FIPS 模式的叢集，在 2023 年之後仍然允許。如需詳細資訊，請參閱 [FIPS 140 合規性：2024 機制棄用](compliance-dep-notif.md#compliance-dep-notif-1)。

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