exSymKey - AWS CloudHSM
Syntax例パラメータ 関連トピック

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

exSymKey

key_mgmt_util ツールの exSymKey コマンドは、対称キーのプレーンテキストコピーを HSM からエクスポートし、ディスク上のファイルに保存します。キーの暗号化 (ラップ) されたコピーをエクスポートするには、wrapKey キーを使用します。exSymKey エクスポートするキーのようにプレーンテキストキーをインポートするには、 を使用しますimSymKey。

エクスポートプロセス中に、exSymKey は、指定した AES キー (ラッピングキー) を使用して、エクスポートするキーを ラップ (暗号化) してから アンラップ (復号化)します。ただし、エクスポートオペレーションの結果は、ディスク上のプレーンテキスト (ラップ解除された) キーとなります。

キーの所有者 (キーを作成した CU ユーザー) のみがキーをエクスポートできます。キーを共有するユーザーは、キーを暗号化オペレーションで使用することはできますが、エクスポートすることはできません。

exSymKey オペレーションは、キーマテリアルをユーザーが指定したファイルにコピーしますが、キーを HSM から削除したり、そのキー属性を変更したり、暗号化オペレーションでのキーの使用を禁止したりはしません。同じキーを複数回エクスポートできます。

exSymKey は対称キーのみをエクスポートします。パブリックキーをエクスポートするには、exportPubKey を使用します。プライベートキーをエクスポートするには、exportPrivateKey を使用します。

key_mgmt_util コマンドを実行する前に、key_mgmt_util を起動し、Crypto User (CU) として HSM に ログインする 必要があります。

Syntax

exSymKey -h

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

例

以下の例では、exSymKey を使用してユーザーが所有する対称キーを HSM からエクスポートする方法を示しています。

例 : 3 DES 対称キーをエクスポートする

次のコマンドでは、Triple DES (3DES) 対称キー (キーハンドル 7) をエクスポートします。HSM の既存の AES キー (キーハンドル 6) をラップキーとして使用します。次に、3DES キーのプレーンテキストを 3DES.key ファイルに書き込みます。

出力は、キー 7 (3DES キー) が正常にラップ/ラップ解除されて 3DES.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"
例 : セッション専用のラップキーでエクスポートする

次の例では、セッションでのみ有効なキーをラップキーとして使用する方法を示します。エクスポートするキーはラップされた後で、すぐにラップ解除されて、プレーンテキストとして配信されるため、ラップキーを保持する必要はありません。

以下のコマンドでは、キーハンドル 8 の AES キーを HSM からエクスポートします。このために専用の 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

最後に、exSymKey コマンドを使用してキー 8 をエクスポートします。ラップキーとしてセッションキー (キー 262168) を使用します。

セッションが終了すると、キー 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 内にインポートします。エクスポートする対称キーはキーの内部コピーでラップし、ファイルのキーのコピーでラップ解除します。

最初のコマンドでは、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 コマンドを使用して、aes256-forImport.keyファイルから HSM に AES キーをインポートします。コマンドが完了すると、キーはキーハンドル 262167 で HSM の 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 キー) をエクスポートします。キーをラップするために、HSM 内にコピーとしてインポートしたキー 262167 を使用します。キーをラップ解除するには、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 ラップキーがラップに使用されます。ただし、ラップ解除には使用されません。

注記

キー 4 は、サポートされていない内部キーを表します。AES キーをラップキーとして作成および管理することをお勧めします。

必須: はい

-out

出力ファイルのパスと名前を指定します。コマンドが成功すると、このファイルに、エクスポートされたキーがプレーンテキストとして配置されます。既存のファイルがある場合は、警告なしに上書きされます。

必須: はい

-m

ラップ方法を指定します。唯一の有効な値は 4 です。これは NIST_AES_WRAP メカニズムを表します。

必須: いいえ

デフォルト: 4

-wk

指定したファイルの AES キーを使用して、エクスポートするキーをラップ解除します。プレーンテキストの AES キーが含まれているファイルのパスと名前を入力します。

このパラメータを含める場合、exSymKey は、-w パラメータで指定した HSM のキーを使用してエクスポートするキーをラップし、-wk ファイルのキーを使用してラップ解除します。-w パラメータと -wk パラメータの値は同じプレーンテキストのキーに解決される必要があります。

必須: いいえ

デフォルト: HSM のラップキーを使用してラップ解除します。

関連トピック