imSymKey - AWS CloudHSM
構文例パラメータ関連トピック

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

imSymKey

key_mgmt_util ツールの imSymKey コマンドは、対称キーのプレーンテキストコピーをファイルから HSM にインポートします。これを使用して、HSM 外で任意の方法で生成したキーや、HSM からエクスポートしたキー (exSymKey でファイルに書き込んだキーなど) をインポートできます。

インポートプロセス中に、imSymKey は選択した AES キー (ラッピングキー) を使用して、インポートするキーをラップ (暗号化) してからアンラップ (復号化) します。ただし、imSymKey を使用できるのは、プレーンテキストのキーが含まれているファイルに対してのみです。暗号化されたキーのエクスポートとインポートには、wrapKey コマンドと unWrapKey コマンドを使用します。

また、imSymKey コマンドは対称キーのみをインポートします。パブリックキーをインポートするには、importPubKey を使用します。プライベートキーをインポートするには、 importPrivateKey または wrapKey を使用します。

注記

パスワードで保護された PEM キーは、対称キーまたはプライベートキーを使用してインポートすることはできません。

インポートしたキーは、HSM で生成したキーとほぼ同じように動作します。ただし、OBJ_ATTR_LOCAL 属性の値は 0 であり、ローカルに生成されたものでないことを示しています。次のコマンドを使用して、インポートした対称キーを共有します。shareKeycloudhsm_mgmt_util で コマンドを使用して、インポート後にキーを共有します。

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

キーのインポート後に、必ずキーファイルをマークまたは削除してください。このコマンドでは、同じキーマテリアルを複数回インポートすることが禁止されません。その結果、キーハンドルが異なる複数のキーが同じキーマテリアルを持つ場合があり、キーマテリアルの使用の追跡が困難になります。また、暗号化の制限に制約されます。

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

構文

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

例

以下の例では、imSymKey を使用して対称キーを HSM 内にインポートする方法を示します。

例 : AES 対称キーをインポートする

次の例では、imSymKey を使用して AES 対称キーを HSM 内にインポートします。

最初のコマンドでは、OpenSSL を使用してランダムな 256 ビット AES 対称キーを生成します。生成したキーは、aes256.key ファイルに保存されます。

$  openssl rand -out aes256-forImport.key 32

2 番目のコマンドでは、imSymKey を使用し、AES キーを aes256.key ファイルから HSM 内にインポートします。HSM の AES キー (キー 20) をラップキーとして使用し、imported をラベルとして指定します。ID とは異なり、ラベルはクラスター内で一意である必要はありません。-t (タイプ) パラメータの値は、AES を表す 31 です。

出力は、ファイルのキーがラップ/ラップ解除され、次に 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 を使用して、新しくインポートしたキーの OBJ_ATTR_LOCAL 属性 (属性 355) を取得し、それを 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 属性の値は 0 であり、キーマテリアルが HSM で生成されたものでないことがわかります。

$  cat attributes/attr_262180_local
OBJ_ATTR_LOCAL
0x00000000
例 : クラスター間で対称キーを移動する

次の例では、exSymKey と imSymKey を使用し、クラスター間でプレーンテキストの AES キーを移動する方法を示します。次のようなプロセスを使用して HSM の両クラスターで有効な AES ラッピングを作成できます。共有ラップキーの準備が整ったら、wrapKey と unWrapKey を使用してクラスター間で暗号化されたキーを移動できます。

このオペレーションを実行する CU ユーザーには、両クラスターで HSM にログインするアクセス許可が必要です。

最初のコマンドでは、exSymKey を使用し、キー 14 (32 ビット AES キー) をクラスター 1 から aes.key ファイル内にエクスポートします。ラップキーとして、クラスター 1 の HSM でキー 6 (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 内にインポートします。このコマンドでは、ラップキーとして、クラスター 2 の HSM で キー 252152 (AES キー) を使用します。

exSymKey と 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 を使用してキー 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 を使用してキー 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

出力は、2 つのキーの KCV 値が同じであり、キーマテリアルが同じであることを示しています。

両クラスターの HSM でキーマテリアルが同じであるため、プレーンテキストキーを公開することなく、クラスター間で暗号化されたキーを共有できます。たとえば、wrapKey コマンドでラップキー 14 を使用してクラスター 1 から暗号化されたキーをエクスポートし、次に unWrapKey でラップキー 21 を使用してクラスター 2 に暗号化されたキーをインポートできます。

例 : セッションキーをインポートする

次のコマンドでは、-sess の imSymKey パラメータを使用し、現在のセッションでのみ有効な 192 ビット Triple 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 コマンドまたは findKey コマンドを使用し、新しくインポートされたキーの属性を検証できます。次のコマンドでは、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

パラメータ

-attest

クラスターを実行するファームウェアが改ざんされていないことを確認する整合性チェックを実行します。

デフォルト: 認証チェックなし。

必須: いいえ

-f

インポートするキーが含まれているファイルを指定します。

ファイルには、指定された長さの AES キーまたは Triple DES キーのプレーンテキストコピーが含まれている必要があります。RC4 キーと DES キーは FIPS モードの HSM では無効です。

  • AES: 16、24、または 32 バイト

  • Triple DES (3 DES): 24 バイト

必須: はい

-h

コマンドに関するヘルプを表示します。

必須: はい

-id

キーのユーザー定義識別子を指定します。クラスター内で一意の文字列を入力します。デフォルトは空の文字列です。

デフォルト: ID 値なし。

必須: いいえ

-I

キーのユーザー定義ラベルを指定します。文字列を入力します。

キーを識別するのに役立つ任意のフレーズを使用できます。ラベルは一意である必要がないため、このラベルを使用してキーをグループ化および分類できます。

必須: はい

-min_srv

-timeout パラメーターの値が期限切れになる前に、キーが同期される HSM の最小数を指定します。キーが割り当てられた時間内に指定された数のサーバーに同期されない場合は、作成されません。

AWS CloudHSM は、どのキーもクラスターのすべての HSM に自動的に同期します。プロセスを高速化するため、min_srv の値をクラスターの HSM の数より少なく設定し、低いタイムアウト値を設定します。ただし、一部のリクエストでキーが生成されない場合があることに注意してください。

デフォルト: 1

必須: いいえ

-sess

現在のセッションにのみ存在するキーを作成します。セッション終了後、キーをリカバリすることはできません。

このパラメータは、別のキーを暗号化してからすばやく復号化するラッピングキーなど、キーが短時間だけ必要な場合に使用します。セッション終了後に復号する必要がある可能性のあるデータを暗号化するためにセッションキーを使用しないでください。

セッションキーを永続(トークン)キーに変更するには、setAttribute を使用します。

デフォルト: キーは永続的です。

必須: いいえ

-timeout

キーが min_srv パラメータで指定された HSM の数に同期されるのをコマンドが待機する時間 (秒単位) を指定します。

このパラメータは、min_srv パラメータがコマンドでも使用されている場合にのみ有効です。

デフォルト: タイムアウトなし。このコマンドは無期限に待機し、キーが最小数のサーバーと同期されている場合にのみ戻ります。

必須: いいえ

-t

対称キーのタイプを指定します。キーのタイプを表す定数を入力します。たとえば、AES キーを作成するには「-t 31」と入力します。

有効な値:

必須: はい

-u

指定したユーザーとインポートするキーを共有します。このパラメータは、別の HSM Crypto User (CU) に、暗号化オペレーションでこのキーを使用するアクセス許可を付与します。

1 つの ID または HSM ユーザー ID のカンマ区切りリスト (5,6 など) を入力します。現在のユーザーの HSM ユーザー ID を含めないでください。ID を確認するには、cloudhsm_mgmt_util コマンドラインツールの listUsers コマンドまたは key_mgmt_util コマンドラインツールの listUsers コマンドを使用できます。

必須: いいえ

-w

ラップキーのキーハンドルを指定します。このパラメータは必須です。キーハンドルを見つけるには、findKey コマンドを使用します。

ラップキーは、インポートプロセスでキーの暗号化 (ラップ) と復号 (ラップ解除) に使用する HSM のキーです。ラップキーとして使用できるのは AES キーのみです。

任意の AES キー (任意のサイズ) をラップキーとして使用できます。ラップキーは、ターゲットキーをラップし、直後にラップ解除するため、セッション専用の AES キーをラップキーとして使用できます。キーをラップキーとして使用できるかどうかを確認するには、getAttribute を使用して OBJ_ATTR_WRAP 属性 (262) の値を取得します。ラップキーを作成するには、genSymKey を使用して AES キー (タイプ 31) を作成します。

-wk パラメータを使用して外部のラップキーを指定した場合、インポートしたキーは -w ラップキーでラップ解除することはできますが、ラップすることはできません。

注記

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

必須: はい

-wk

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

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

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

必須: いいえ

関連トピック