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

# 使用 AWS CloudHSM KMU 匯入純文字對稱金鑰
<a name="key_mgmt_util-imSymKey"></a>

使用 AWS CloudHSM key\_mgmt\_util 工具中的 **imSymKey**命令，將對稱金鑰的純文字副本從檔案匯入硬體安全模組 (HSM)。您可以使用此命令匯入您在 HSM 外部以任何方法產生的金鑰，以及從 HSM 匯出的金鑰，例如 [exSymKey](key_mgmt_util-exSymKey.md) 命令寫入檔案中的金鑰。

在匯入過程中，**imSymKey** 會使用您選取的 AES 金鑰 (「包裝金鑰」**) 來「包裝」**(加密) 然後「取消包裝」**(解密) 要匯入的金鑰。不過，**imSymKey** 僅適用於包含純文字金鑰的檔案。若要匯出和匯入已加密的金鑰，請使用 [wrapKey](key_mgmt_util-wrapKey.md) 和 [unWrapKey](key_mgmt_util-unwrapKey.md) 命令。

此外，**imSymKey** 命令只匯出對稱金鑰。若要匯入公有金鑰，請使用 [importPubKey](key_mgmt_util-importPubKey.md)。若要匯入私有金鑰，請使用 [importPrivateKey](key_mgmt_util-importPrivateKey.md) 或 [wrapKey](key_mgmt_util-wrapKey.md)。

**注意**  
您無法使用對稱或私有金鑰匯入受密碼保護的 PEM 金鑰。

匯入的金鑰運作方式非常類似於 HSM 中產生的金鑰。不過，[OBJ\_ATTR\_LOCAL 屬性](key-attribute-table.md)的值為零，表示其不是在本機產生。當您匯入對稱金鑰時，您可以使用以下命令來共用金鑰。匯入金鑰之後，您可以在 `shareKey`cloudhsm\_mgmt\_util[ 中使用 ](cloudhsm_mgmt_util.md) 命令來共用金鑰。

```
imSymKey -l aesShared -t 31 -f kms.key -w 3296 -u 5
```

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

執行任何 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="imSymKey-syntax"></a>

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

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

以下範例示範如何使用 **imSymKey** 將對稱金鑰匯入 HSM。

**Example ：匯入 AES 對稱金鑰**  
這個範例使用 **imSymKey** 將 AES 對稱金鑰匯入 HSM。  
第一個命令使用 OpenSSL 產生隨機 256 位元 AES 對稱金鑰。此命令將金鑰儲存在 `aes256.key` 檔案中。  

```
$  openssl rand -out aes256.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 imported

        Cfm3WrapHostKey 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](key_mgmt_util-getAttribute.md)，以取得新匯入之金鑰的 OBJ\_ATTR\_LOCAL 屬性 ([屬性 355](key-attribute-table.md))，並將此屬性寫入 `attr_262180` 檔案。  

```
Command:  getAttribute -o 262180 -a 355 -out attributes/attr_262180
Attributes dumped into attributes/attr_262180_imported file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS
```
當您檢查屬性檔案時，您可以看到 `OBJ_ATTR_LOCAL` 屬性值為零，這表示在金鑰資料不是在 HSM 中產生。  

```
$  cat attributes/attr_262180_local
OBJ_ATTR_LOCAL
0x00000000
```

**Example ：在叢集之間移動對稱金鑰**  
此範例說明如何使用 [exSymKey](key_mgmt_util-exSymKey.md) 和 **imSymKey**，在叢集之間移動純文字 AES 金鑰。您可以使用像這樣的程序來建立 AES 包裝，而此 AES 包裝同時存在於兩個叢集的 HSM 上。當共用包裝金鑰備妥後，您就可以使用 [wrapKey](key_mgmt_util-wrapKey.md) 和 [unWrapKey](key_mgmt_util-unwrapKey.md)，在叢集之間移動已加密的金鑰。  
執行此操作的 CU 使用者必須有許可，而能夠登入兩個叢集上的 HSM。  
第一個命令使用 [exSymKey](key_mgmt_util-exSymKey.md)，從叢集 1 將金鑰 14 (32 位元 AES 金鑰) 匯出到 `aes.key` 檔案。此命令使用金鑰 6 (叢集 1 的 HSM 上的 AES 金鑰) 作為包裝金鑰。  

```
Command: exSymKey -k 14 -w 6 -out aes.key

        Cfm3WrapKey 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](key_mgmt_util-exSymKey.md) 和 **imSymKey** 使用的包裝金鑰會包裝目標金鑰，並立即取消包裝，所以不同叢集上的包裝金鑰不需要相同。  
輸出顯示金鑰已成功匯入叢集 2，且指派的金鑰控制代碼為 21。  

```
Command:  imSymKey -f aes.key -w 262152 -t 31 -l xcluster

        Cfm3WrapHostKey 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](key_mgmt_util-getAttribute.md)，將金鑰 14 的 KCV 屬性 (屬性 371) 的值寫入 `attr_14_kcv` 檔案。然後，使用 **cat** 命令取得 `attr_14_kcv` 檔案的內容。  

```
Command:  getAttribute -o 14 -a 371 -out attr_14_kcv
Attributes dumped into attr_14_kcv file

$  cat attr_14_kcv
OBJ_ATTR_KCV
0xc33cbd
```
以下類似的命令在叢集 2 使用 [getAttribute](key_mgmt_util-getAttribute.md)，將金鑰 21 的 KCV 屬性 (屬性 371) 的值寫入 `attr_21_kcv` 檔案。然後，使用 **cat** 命令取得 `attr_21_kcv` 檔案的內容。  

```
Command:  getAttribute -o 21 -a 371 -out attr_21_kcv
Attributes dumped into attr_21_kcv file

$  cat attr_21_kcv
OBJ_ATTR_KCV
0xc33cbd
```
輸出顯示兩個金鑰的 KCV 值相同，這證明金鑰資料相同。  
由於相同的金鑰資料同時存在於兩個叢集的 HSM 中，您現在可以在叢集之間共用加密的金鑰，而完全不需要公有純文字金鑰。例如，您可以對包裝金鑰 14 使用 `wrapKey` 命令，從叢集 1 匯出加密的金鑰，然後對包裝金鑰 21 使用 `unWrapKey`，將加密的金鑰匯入叢集 2。

**Example ：匯入工作階段金鑰**  
此命令使用 **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 -attest

        Cfm3WrapHostKey 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](key_mgmt_util-getAttribute.md) 或 [findKey](key_mgmt_util-findKey.md) 命令，以驗證新匯入之金鑰的屬性。以下命令使用 **findKey**，以驗證金鑰 37 具有命令所指定的類型、標籤和 ID，而且是工作階段金鑰。如輸出的第 5 行所示，**findKey** 報告唯一符合所有屬性的金鑰是金鑰 37。  

```
Command:  findKey -t 21 -l temp -id test01 -sess 1
Total 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
```

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

**-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](key_mgmt_util-setAttribute.md)。  
預設：此金鑰是持久性金鑰。  
必要：否

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

**-t**  
指對稱金鑰的類型。輸入代表金鑰類型的常數。例如，若要建立 AES 金鑰，請輸入 `-t 31`。  
有效值：  
+ 21：[三重 DES (3DES)](https://en.wikipedia.org/wiki/Triple_DES)。
+ 31：[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
必要：是

**-u**  
將您匯入的金鑰共用給指定的使用者。此參數授與其他 HSM 密碼使用者 (CU) 在密碼編譯操作中使用此金鑰的許可。  
輸入一個 ID，或以逗號分隔的 HSM 使用者 ID 清單，例如 -u `5,6`。請勿包含現行使用者的 HSM 使用者 ID。若要尋找 ID，您可以在 cloudhsm\_mgmt\_util 命令列工具中使用 [listUsers](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_mgmt_util-listUsers.html) 命令，或在 key\_mgmt\_util 命令列工具中使用 [listUsers](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-listUsers.html) 命令。  
必要：否

**-w**  
指定包裝金鑰的金鑰控制代碼。此為必要參數。若要找出金鑰控制代碼，請使用 [findKey](key_mgmt_util-findKey.md) 命令。  
*包裝金鑰*是 HSM 中的金鑰，用於匯入過程中加密 (包裝) 然後解密 (取消包裝) 金鑰。只有 AES 金鑰可以做為包裝金鑰。  
您可以使用任何 AES 金鑰 (任何大小) 做為包裝金鑰。因為包裝金鑰將目標金鑰包裝後又立即取消包裝，您可以使用僅限工作階段的 AES 金鑰做為包裝金鑰。若要判斷金鑰是否可作為包裝金鑰，請使用 [getAttribute](key_mgmt_util-getAttribute.md) 以取得 `OBJ_ATTR_WRAP` 屬性 (262) 的值。要建立包裝金鑰，請使用 [genSymKey](key_mgmt_util-genSymKey.md) 以建立 AES 金鑰 (輸入 31)。  
如果您使用 `-wk` 參數來指定外部包裝金鑰，則會使用 `-w` 包裝金鑰來取消包裝 (而不是包裝) 要匯入的金鑰。  
金鑰 4 是不支援的內部金鑰。建議您使用您所建立並做為包裝金鑰管理的 AES 金鑰。
必要：是

**-wk**  
使用指定檔案中的 AES 金鑰來包裝要匯入的金鑰。輸入包含純文字 AES 金鑰的檔案路徑和名稱。  
當您加入此參數時，**imSymKey** 會使用 `-wk` 檔案中的金鑰來包裝要匯入的金鑰，並使用由 `-w` 參數在 HSM 中指定的金鑰來取消包裝此金鑰。`-w` 和 `-wk`參數值必須解析為相同的純文字金鑰。  
預設：使用 HSM 上的包裝金鑰來取消包裝。  
必要：否

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