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

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

exSymKey

key_mgmt_util 工具中的 exSymKey 命令會從 HSM 匯出對稱金鑰的純文字複本，並將其儲存在磁碟上的檔案中。若要匯出金鑰的加密 (包裝) 複本，請使用 wrapKey 命令。若要匯入純文字金鑰，就像匯exSymKey出的金鑰一樣，請使用. imSymKey

在匯出程序時，exSymKey 會使用您指定要包裝 (加密) 的 AES 金鑰 (包裝金鑰)，然後將金鑰取消包裝 (解密)以便匯出。不過，匯出操作的結果是磁碟上的純文字 (取消包裝) 金鑰。

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

exSymKey 操作會將金鑰資料複製到您指定的檔案，但不會從 HSM 中移除該金鑰、變更其金鑰屬性、或阻止您在密碼編譯操作中使用金鑰。您可以多次匯出相同的金鑰。

exSymKey 只會匯出對稱金鑰。若要匯出公有金鑰，請使用 exportPubKey。若要匯出私有金鑰，請使用 exportPrivateKey。

執行任何 key_mgmt_util 命令之前，您必須先啟動 key_mgmt_util 並以加密使用者 (CU) 的身分登入 HSM。

語法

exSymKey -h

exSymKey -k <key-to-export>
         -w <wrapping-key>
         -out <key-file>
         [-m 4] 
         [-wk <unwrapping-key-file> ]

範例

下列範例示範如何從 HSM 使用 exSymKey 來匯出您擁有的對稱金鑰。

範例 ：匯出 3DES 對稱金鑰

此命令會將三重 DES (3DES) 對稱金鑰 (金鑰控制代碼 7) 匯出。它使用 HSM 中的現有 AES 金鑰 (金鑰控制代碼 6) 做為包裝金鑰。然後，將純文字的 3DES 金鑰寫入 3DES.key 檔案。

輸出顯示已成功將金鑰 7 (3DES 金鑰) 包裝和取消包裝，然後將其寫入 3DES.key 檔案。

警告

雖然輸出寫著已將 "Wrapped Symmetric Key"(包裝的對稱金鑰) 寫入輸出檔，但輸出檔中包含純文字 (取消包裝) 金鑰。

        Command: exSymKey -k 7 -w 6 -out 3DES.key

       Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "3DES.key"
範例 ：匯出僅限工作階段的包裝金鑰

此範例示範如何使用只存在於工作階段中的金鑰做為包裝金鑰。因為要匯出的金鑰會被包裝、再立即取消包裝，然後以純文字傳送，所以不需要保留包裝金鑰。

這一系列的命令會從 HSM 匯出金鑰控制代碼為 8 的 AES 金鑰。它會使用特別為此目的建立的 AES 工作階段金鑰。

第一個命令使genSymKey用創建 256 位 AES 密鑰。它會使用 -sess 參數來建立只在目前工作階段中存在的金鑰。

輸出顯示 HSM 建立了金鑰 262168。

        Command:  genSymKey -t 31 -s 32 -l AES-wrapping-key -sess

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 262168

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS

接著，範例會驗證金鑰 8 (要匯出的金鑰) 是可擷取的對稱金鑰。它也會驗證包裝金鑰 (金鑰 262168) 是只存在於工作階段中的 AES 金鑰。您可以使用 findKey 命令，而本範例則是將兩個金鑰的屬性匯出到檔案，然後使用 grep 在檔案中尋找相關的屬性值。

這些命令使用 getAttribute，再加上 -a 的值為 512 (所有)，來取得 8 和 262168 金鑰的所有屬性。如需有關這些金鑰屬性的詳細資訊，請參閱金錀屬性參考。

getAttribute -o 8 -a 512 -out attributes/attr_8
getAttribute -o 262168 -a 512 -out attributes/attr_262168

這些命令使用 grep 來驗證要匯出金鑰 (金鑰 8) 的屬性，以及僅限工作階段的包裝金鑰 (金鑰 262168)。

    // Verify that the key to be exported is a symmetric key.
    $  grep -A 1 "OBJ_ATTR_CLASS" attributes/attr_8    
    OBJ_ATTR_CLASS
    0x04
   
    // Verify that the key to be exported is extractable.
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_8
    OBJ_ATTR_EXTRACTABLE
    0x00000001

    // Verify that the wrapping key is an AES key
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_262168
    OBJ_ATTR_KEY_TYPE
    0x1f

    // Verify that the wrapping key is a session key
    $  grep -A 1 "OBJ_ATTR_TOKEN" attributes/attr_262168
    OBJ_ATTR_TOKEN
    0x00    
    
    // Verify that the wrapping key can be used for wrapping
     $  grep -A 1 "OBJ_ATTR_WRAP" attributes/attr_262168
    OBJ_ATTR_WRAP
    0x00000001

最後，我們使用工作階段金鑰 (金鑰 262168) 做為包裝金鑰，來使用 exSymKey 命令匯出金鑰 8。

當工作階段結束時，金鑰 262168 便不再存在。

        Command:  exSymKey -k 8 -w 262168 -out aes256_H8.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes256_H8.key"
範例 ：使用外部取消包裝金鑰

此範例示範如何使用外部取消包裝金鑰來從 HSM 匯出金鑰。

當您從 HSM 匯出金鑰時，會指定 HSM 上的 AES 金鑰做為包裝金鑰。依預設，此包裝金鑰會用於將要匯出的金鑰進行包裝和取消包裝。不過，您可以使用 -wk 參數來告訴 exSymKey 使用磁碟上檔案中的外部金鑰來取消包裝。當您這麼做時，由 -w 參數指定的金鑰會包裝目標金鑰，而 -wk 參數指定檔案中的金鑰會將金鑰取消包裝。

因為包裝金鑰必須是 AES 金鑰 (其為對稱)，在 HSM 中的包裝金鑰和磁碟上的取消包裝金鑰必須有相同的金鑰資料。為此，您必須在匯出操作前將包裝金鑰匯入 HSM，或從 HSM 匯出包裝金鑰。

此範例會在 HSM 外建立金鑰，並將其匯入 HSM。它使用內部的金鑰複本來包裝要匯出的對稱金鑰，然後複製檔案中的金鑰來將其取消包裝。

第一個命令會使用 OpenSSL 來產生 256 位元的 AES 金鑰。此命令會將金鑰儲存到 aes256-forImport.key 檔案。OpenSSL 命令不會傳回任何輸出，但您可以使用多種命令來確認操作是否成功。此範例中使用 wc (字數) 工具，該工具會確認檔案中是否包含 32 位元組的資料。

$  openssl rand -out keys/aes256-forImport.key 32

$ wc keys/aes256-forImport.key
 0  2 32 keys/aes256-forImport.key

此命令使用imSymKey命令將 AES 金鑰從aes256-forImport.key檔案匯入 HSM。命令完成後，HSM 中便有該金鑰，金鑰控制代碼為 262167，並位於 aes256-forImport.key 檔案中。

Command:  imSymKey -f keys/aes256-forImport.key -t 31 -l aes256-imported -w 6

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262167

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

此命令在匯出操作時使用該金鑰。命令使用 exSymKey 來匯出金鑰 21，後者是 192 位元的 AES 金鑰。若要包裝金鑰，它使用金鑰 262167，這是之前匯入 HSM 的複本。為了要將金鑰取消包裝，它使用 aes256-forImport.key 檔案中的相同金鑰資料。命令完成時，會將金鑰 21 匯出到 aes192_h21.key 檔案。

        Command:  exSymKey -k 21 -w 262167 -out aes192_H21.key -wk aes256-forImport.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

Wrapped Symmetric Key written to file "aes192_H21.key"

參數

-h

顯示命令的說明。

必要：是

-k

指定要匯出之金鑰的金鑰控制代碼。此為必要參數。輸入您擁有之對稱金鑰的金鑰控制代碼。此為必要參數。若要找出金鑰控制代碼，請使用 findKey 命令。

若要確認金鑰是否匯出，請使用 getAttribute 命令取得 OBJ_ATTR_EXTRACTABLE 屬性的值 (以常數 354 表示)。此外，您只能匯出您擁有的金鑰。若要尋找金鑰的擁有者，請使用getKeyInfo指令。

必要：是

-w

指定包裝金鑰的金鑰控制代碼。此為必要參數。若要找出金鑰控制代碼，請使用 findKey 命令。

包裝金鑰 是 HSM 中的金鑰，用於將要匯出的金鑰進行加密 (包裝) 然後解密 (取消包裝)。只有 AES 金鑰可以做為包裝金鑰。

您可以使用任何 AES 金鑰 (任何大小) 做為包裝金鑰。因為包裝金鑰將目標金鑰包裝後又立即取消包裝，您可以使用僅限工作階段的 AES 金鑰做為包裝金鑰。若要判斷金鑰是否可做為包裝金鑰，使用 getAttribute 取得 OBJ_ATTR_WRAP 屬性之值 (以常數 262 表示)。若要建立包裝金鑰，請genSymKey使用建立 AES 金鑰 (類型 31)。

如果您使用 -wk 參數來指定外部的取消包裝金鑰，則在匯出期間會使用 -w 包裝金鑰來進行包裝，但不會用來取消包裝。

注意

Key 4 代表不支援的內部金鑰。建議您使用您所建立並做為包裝金鑰管理的 AES 金鑰。

必要：是

-out

指定輸出檔案的路徑和名稱。命令成功時，這個檔案中會包含匯出的純文字金鑰。如果檔案已存在，命令會覆寫檔案且不會有任何警告。

必要：是

-m

指定包裝機制。唯一的有效值是 4，這代表 NIST_AES_WRAP 機制。

必要：否

預設：4

-wk

使用指定檔案中的 AES 金鑰來將要匯出的金鑰取消包裝。輸入包含純文字 AES 金鑰的檔案路徑和名稱。

當您加入此參數時，exSymKey 會使用 -w 參數在 HSM 指定的金鑰來包裝要匯出的金鑰，並使用 -wk 檔案中的金鑰來取消包裝此金鑰。-w 和 -wk參數值必須解析為相同的純文字金鑰。

必要：否

預設：使用 HSM 上的包裝金鑰來取消包裝。

相關主題