目標

このチュートリアルでは、暗号鍵を作成して Hyper Protect Crypto Services サービスに安全にインポートする作業について順に説明します。 Hyper Protect Crypto Services の鍵管理機能については知らないが、鍵管理システムについてはいくらか知識があるというユーザーを対象にしています。 以下の手順は完了するまで約 20 分かかります。

• キー管理サービス API のセットアップ
• 鍵のインポートを開始するための Hyper Protect Crypto Services サービス・インスタンスの準備
• OpenSSL 暗号化ツールキットを使用した暗号鍵の作成と暗号化
• Hyper Protect Crypto Services サービス・インスタンスへの暗号化された鍵のインポート

このチュートリアルでは、ご使用の IBM Cloud アカウントに料金が発生することはありません。

タスク・フロー

以下のフローチャートは、暗号キーを作成およびインポートする方法の概要を示しています。 グラフの各ステップをクリックすると、ステップの詳細が表示されます。

開始前に

開始するには、IBM Cloud にプロビジョンするサービスと対話できるように、IBM Cloud CLI が必要です。 また、ご使用のワークステーションに openssl パッケージおよび jq パッケージがローカルにインストールされていることも必要です。

1. IBM Cloud アカウントを作成します。

2. ご使用のオペレーティング・システム用の IBM Cloud CLI をダウンロードしてインストールします。

3. IBM Key Protect の CLI プラグイン v0.6.3 以降をダウンロードしてインストールし、Hyper Protect Crypto Services で使用するために構成します。 KP_PRIVATE_ADDR 変数を、必ず現在のインスタンス鍵管理エンドポイント URL に更新してください。

   IBM Key Protect の CLI プラグインのバージョンを確認するには、次のようにします。

   ibmcloud plugin show key-protect
   

   IBM Key Protect の CLI プラグインを最新バージョンに更新するには、次のようにします。

   ibmcloud plugin update key-protect -r 'IBM Cloud'
   

4. OpenSSL 暗号化ライブラリーをダウンロードしてインストールします。

   Hyper Protect Crypto Services を初めて試す場合は、openssl コマンドを使用して、ローカル・ワークステーションに暗号キーを作成します。 このチュートリアルでは、OpenSSL バージョン 1.0.2r 以上が必要です。

   Mac を使用している場合は、 Homebrewを使用して、 OpenSSL を使用して素早く稼働させることができます。 初めてこのパッケージをインストールする場合は brew install openssl を実行し、既存のパッケージを最新バージョンにアップグレードする場合は brew upgrade openssl を実行します。

5. jqをダウンロードしてインストールします。

   jq は、JSONデータのスライスに役立ちます。 このチュートリアルでは、jq を使用して、Hyper Protect Crypto Services キー管理サービス API を呼び出したときに返される特定のデータを取得して使用します。

6. Hyper Protect Crypto Services サービスのインスタンスを作成します。

7. Hyper Protect Crypto Services サービス・インスタンスを初期設定します。

8. Hyper Protect Crypto Services キー管理サービス API をセットアップします。

インポート・トークンを作成します。

サービス資格情報を使用して、キー管理サービス API との対話を開始し、暗号キーを作成してサービスに持ち込めます。

以下のステップでは、Hyper Protect Crypto Services サービス・インスタンス向けのインポート・トークンを作成します。 指定するポリシーに基づいたインポート・トークンを作成することによって、サービスに転送されている間の暗号鍵のために追加のセキュリティーが有効になります。

1. コマンド・ラインで、新しい hs-crypto-test ディレクトリーに移動します。

   mkdir hs-crypto-test && cd hs-crypto-test
   

   このディレクトリーを、後の手順で作成するファイルの保管に使用します。

2. キー管理サービス API または CLI を使用して、Hyper Protect Crypto Services サービス・インスタンスのインポート・トークンを作成し、応答を JSON ファイルに保存できます。

   • API の使用

     curl -X POST $HPCS_API_URL/api/v2/import_token \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -H "Bluemix-Instance: $INSTANCE_ID" \
         -d '{
             "expiration": 1200,
             "maxAllowedRetrievals": 1
           }' > createImportTokenResponse.json
     

     要求本文で、時間および使用回数に基づいてインポート・トークンの使用を制限するポリシーを指定できます。 この例では、インポート・トークンの有効期限を 1200 秒 (20 分) に設定し、有効期限内に許可されるトークンの取得回数を 1 回に設定します。

   • IBM Key Protect CLI の使用

     ibmcloud kp import-token create --instance-id $INSTANCE_ID --max-retrievals=1 --expiration=1200 -o json > createImportTokenResponse.json
     

3. インポート・トークンの詳細を表示します。

   jq '.' createImportTokenResponse.json
   

   インポート・トークンに関連付けられたメタデータ (作成日やポリシー詳細など) が出力に表示されます。 次のスニペットは出力例を示しています。

   {
     "creationDate": "2020-06-08T16:58:29Z",
     "expirationDate": "2020-06-08T17:18:29Z",
     "maxAllowedRetrievals": 1,
     "remainingRetrievals": 1
   }
   

インポート・トークンの取得

前のステップで、インポート・トークンを作成し、そのトークンと関連付けられているメタデータを表示しました。

このステップでは、インポート・トークンに関連付けられたパブリック・キーと nonce 値をリトリーブします。 公開鍵は後のステップでデータを暗号化するために必要であり、nonce は Hyper Protect Crypto Services サービスへのセキュアなインポート要求を検証するために必要です。

インポート・トークンの内容を取得するには、以下のようにします。

1. 前のステップで生成したインポート・トークンを取得し、応答を JSON ファイルに保存します。

   • API の使用

     curl -X GET $HPCS_API_URL/api/v2/import_token \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Bluemix-Instance: $INSTANCE_ID" > getImportTokenResponse.json
     

   • IBM Key Protect CLI の使用

     ibmcloud kp import-token show -o json > getImportTokenResponse.json
     

2. オプション: インポート・トークンの内容を検査します。

   jq '.' getImportTokenResponse.json
   

   インポート・トークンについての詳細情報が出力で表示されます。 以下のスニペットは出力例を示しています (一部の値は切り捨てられています)。

   {
     "creationDate": "2020-06-08T16:58:29Z",
     "expirationDate": "2020-06-08T17:18:29Z",
     "maxAllowedRetrievals": 1,
     "remainingRetrievals": 0,
     "payload": "MIICIjANBgkqhkiG...",
     "nonce": "8zJE9pKVdXVe/nLb"
   }
   

   payload 値は、インポート・トークンと関連付けられた公開鍵を表しています。 この値は base64 でエンコードされています。 セキュリティーを強化するため、Hyper Protect Crypto Services は、サービスへの要求が元のものであることを検証するために使用される nonce 値を提供します。 暗号鍵をインポートするときに、この値を暗号化して提供する必要があります。

3. パブリック・キーをデコードして PublicKey.pem というファイルに保存し、後で使用するために値を変数に抽出します。

   jq -r '.payload' getImportTokenResponse.json | openssl enc -base64 -A -d -out PublicKey.pem
   

   HPCS_PUBKEY="$(jq -r '.payload' getImportTokenResponse.json)"
   NONCE="$(jq -r '.nonce' getImportTokenResponse.json)"
   

   これで、ご使用のワークステーションに公開鍵が PEM フォーマットでダウンロードされました。 次のステップに進んでください。

暗号鍵の作成

Hyper Protect Crypto Services では、IBM Cloud で使用する独自の暗号キーを作成してアップロードすることで、Keep Your Own Key (KYOK) のセキュリティー上のメリットを活用できます。

以下のステップでは、ローカル・ワークステーション上で 256 ビット AES 対称鍵を作成します。

このチュートリアルでは、OpenSSL 暗号化ツールキットを使用して疑似ランダム鍵を生成しますが、セキュリティー上のニーズに応じて、もっと強い鍵を生成するためのさまざまなオプションを探索することもできます。 例えば、オンプレミスのハードウェア・セキュリティー・モジュール (HSM) を利用した、組織の内部鍵管理システムを使用して、鍵の作成とエクスポートを行いたい場合などが考えられます。

256 ビット AES 対称キーを作成する場合は、コマンド行から以下の openssl コマンドを実行します。

openssl rand 32 > PlainTextKey.bin

所有している鍵をこのチュートリアルで使用する場合、この手順はスキップできます。

成功! これで、PlainTextKey.bin という名前のファイルに暗号鍵が保存されました。 次のステップに進んでください。

暗号キーを環境変数として設定します。

ステップ 3 に従ってキーを作成する場合に、キーをエンコードして、エンコードされた値を環境変数として設定するには、以下のコマンドを実行します。 このチュートリアルで独自のキーを使用する場合は、このステップをスキップできます。

KEY_MATERIAL=$(openssl enc -base64 -A -in PlainTextKey.bin)

暗号キーを使用して nonce を暗号化します

セキュリティー強化の目的で、Hyper Protect Crypto Services は、暗号キーをサービスにインポートする際に nonce 検証を必要とします。

nonce は、暗号化において、悪意のある攻撃や不正な呼び出しから保護するために要求が元のものであることを検査するセッション・トークンとして機能します。 Hyper Protect Crypto Services によって配布されたのと同じ nonce を使用することは、鍵をアップロードする要求が有効であることを保証するのに役立ちます。 nonce 値は、サービスにインポートするのと同じ鍵を使用して暗号化されている必要があります。

nonce 値を暗号化するには、以下のようにします。

1. これ以降の手順を API を使用して実行する場合は、以下を実行します。

   IBM Key Protect CLI を使用する場合、この手順を実行する必要はありません。

   1. ご使用のオペレーティング・システムと互換性のある サンプルの kms-encrypt-nonce バイナリー をダウンロードします。 ファイルを解凍してから、バイナリーを hs-crypto-test ディレクトリーに移動します。

      バイナリーには、ステップ 2 で生成したキーを使用して nonce 値に対して AES-CBC 暗号化を実行するためのスクリプトが含まれています。 このスクリプトについて詳しくは、 GitHubでソース・ファイルを確認してください。

   2. Linuxを使用している場合は、以下の chmod コマンドを実行して、ファイルに実行可能のマークを付けます。 Windows を使用している場合、この手順はスキップできます。

      chmod +x ./kms-encrypt-nonce
      

   3. ステップ 2 で生成したキーを使用して nonce 値を暗号化するには、このスクリプトを実行します。

2. 暗号化された nonce を EncryptedValues.json というファイルに保存します。

   • API の使用

     ./kms-encrypt-nonce -key $KEY_MATERIAL -nonce $NONCE -alg "CBC" > EncryptedValues.json
     

   • IBM Key Protect CLI の使用

     ibmcloud kp import-token nonce-encrypt --key "$KEY_MATERIAL" --nonce "$NONCE" --cbc -o json > EncryptedValues.json
     

3. オプション: JSON ファイルの内容を検査します。

   jq '.' EncryptedValues.json
   

   次のステップで指定する必要のある値が出力で表示されます。 以下のスニペットは出力例を示しています (一部の値は切り捨てられています)。

   {
     "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==",
     "iv": "puQrzDX7gU1TcTTx"
   }
   

   encryptedNonce の値は、OpenSSL を使用して生成したキーでラップ (または暗号化) された元の nonce を表します。 iv 値は、AES-CBC アルゴリズムによって作成される初期設定ベクトル (IV) であり、Hyper Protect Crypto Services が nonce を正常に復号するために後で必要になります。

作成された暗号キーを暗号化します

次に、ステップ 2 で Hyper Protect Crypto Services によって配布されたパブリック・キーを使用して、OpenSSL を使用して作成した暗号キーを暗号化します。

• 作成された暗号キーを API で暗号化して、環境変数に割り当てます。

  openssl pkeyutl \
    -encrypt \
    -pubin \
    -keyform PEM \
    -inkey PublicKey.pem \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha1 \
    -in PlainTextKey.bin \
    -out EncryptedKey.bin
  

  ENCRYPTED_KEY=$(openssl enc -base64 -A -in EncryptedKey.bin)
  

  Mac OSX での openssl コマンドの実行時にパラメーター設定エラーが発生する場合、環境に応じて OpenSSL が適切に構成されていることを確認する必要があります。 Homebrew を使用して OpenSSL をインストールした場合、brew update を実行してから brew install openssl を実行して、最新バージョンを取得してください。 その後、export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.bash_profile を実行してパッケージを symlink します。 コマンド・ラインで、which openssl && openssl version を実行して最新バージョンの OpenSSL が /usr/local/ の場所にあることを確認します。 引き続きエラーが発生する場合は、この例にリストされているパラメーターのみを使用するようにしてください。

• IBM Key Protect CLI を使用して、作成した暗号キーを暗号化します。

  ibmcloud kp import-token key-encrypt -k "$KEY_MATERIAL" -p "$HPCS_PUBKEY" --hash SHA1 -o json > EncryptedKey.json
  ENCRYPTED_KEY=$(jq -r '.encryptedKey' EncryptedKey.json)
  

  成功! 暗号化された鍵を Hyper Protect Crypto Services にアップロードするためのすべての設定が整いました。 次のステップに進んでください。

暗号化されたキーのインポート

これで、キー管理サービス API を使用して、暗号化されたキーをインポートできます。

暗号キーをインポートするには、以下のようにします。

1. 暗号化された nonce および初期設定ベクトル (IV) の値を収集します。

   ENCRYPTED_NONCE=$(jq -r '.encryptedNonce' EncryptedValues.json)
   

   IV=$(jq -r '.iv' EncryptedValues.json)
   

2. 暗号化した鍵を Hyper Protect Crypto Services サービス・インスタンスに保管します。

   • API の使用

     curl -X POST  $HPCS_API_URL/api/v2/keys \
         -H "Accept: application/vnd.ibm.collection+json" \
         -H "Authorization: $ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -H "Bluemix-Instance: $INSTANCE_ID" \
         -d '{
           "metadata": {
             "collectionType": "application/vnd.ibm.kms.key+json",
             "collectionTotal": 1
           },
           "resources": [
           {
             "name": "encrypted-root-key",
             "type": "application/vnd.ibm.kms.key+json",
             "payload": "'"$ENCRYPTED_KEY"'",
             "extractable": false,
             "encryptionAlgorithm": "RSAES_OAEP_SHA_1",
             "encryptedNonce": "'"$ENCRYPTED_NONCE"'",
             "iv": "'"$IV"'"
           }
         ]
       }' > createRootKeyResponse.json
     

     要求本体に、前のステップで準備した暗号鍵を指定します。 また、要求を検証するために必要な、暗号化された nonce 値および IV 値も指定します。 最後に、extractable に設定された false 値は、新しい鍵を、エンベロープ暗号化に使用できるサービス内のルート鍵として指定します。

     インポート・トークン期限切れエラーのために API 要求が失敗する場合、ステップ 1 に戻って、新しいインポート・トークンを作成してください。 インポート・トークンおよび関連付けられた公開鍵は、作成時に指定するポリシーに基づいて有効期限が切れることに注意してください。

   • IBM Key Protect CLI の使用

     ibmcloud kp key create new-imported-key --key-material "$ENCRYPTED_KEY" --encrypted-nonce "$ENCRYPTED_NONCE" --iv "$IV" --sha1 -o json > createRootKeyResponse.json
     

     背後で、Hyper Protect Crypto Services は、暗号化されたパケットを TLS 1.2 接続を介して受信します。 ハードウェア・セキュリティー・モジュール内部で、システムは秘密鍵を使用して対称鍵を復号します。 最後に、システムは対称鍵と IV を使用して、nonce を復号し、要求を検証します。 鍵は、耐タンパー性のある FIPS 140-2 レベル 4 認定のハードウェア・セキュリティー・モジュールに保管されました。

3. キーの詳細を表示します。

   jq '.' createRootKeyResponse.json
   

   次のスニペットは出力例を示しています。

   {
     "metadata": {
       "collectionType": "application/vnd.ibm.kms.key+json",
       "collectionTotal": 1
     },
     "resources": [
       {
         "id": "644cba65-e240-471f-8b84-14115447d2ae",
         "type": "application/vnd.ibm.kms.key+json",
         "name": "encrypted-root-key",
         "state": 1,
         "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:346d9f67-4bb2-481e-a3e1-3c2c646aa886:key:644cba65-e240-471f-8b84-14115447d2ae",
         "extractable": false,
         "imported": true
       }
     ]
   }
   

   • id の値はキーに割り当てられた固有 ID で、キー管理サービス API の今後の呼び出しに使用されます。

   • state 値が 1 に設定されている場合は、鍵が アクティブ鍵の状態 になっていることを示します。

   • crn 値は、鍵へのフル・スコープ・パスであり、IBM Cloud 内のどこにリソースがあるのかを指定します。

   • 最後に、extractable 値および imported 値は、このリソースをサービスにインポートしたルート鍵として記述しています。 extractable属性をtrueに設定すると、サービスはその鍵を、アプリまたはサービスに保管できる標準鍵として指定します。 それ以外の場合、extractable属性をfalseに設定すると、サービスはその鍵をルート鍵として指定します。

4. オプション: Hyper Protect Crypto Services ダッシュボードに移動して、キーを表示、管理します。

   アプリケーションの詳細ページで、鍵の一般的な特性を参照できます。 鍵の管理に関するオプションのリストから選択します (鍵のローテートや鍵の削除など)。

クリーンアップ

1. 前のステップでインポートした暗号鍵の ID を収集します。

   ROOT_KEY_ID=$(jq -r '.resources[].id' createRootKeyResponse.json)
   

2. 暗号鍵を Hyper Protect Crypto Services サービス・インスタンスから削除します。

   • API の使用

     curl -X DELETE $HPCS_API_URL/api/v2/keys/$ROOT_KEY_ID \
       -H "Accept: application/vnd.ibm.collection+json" \
       -H "Authorization: $ACCESS_TOKEN" \
       -H "Bluemix-Instance: $INSTANCE_ID" | jq .
     

   • IBM Key Protect CLI の使用

     ibmcloud kp key delete {ROOT_KEY_ID}
     

3. このチュートリアルに関連するすべてのローカル・ファイルを削除します。

   rm kms-encrypt-nonce *.json *.bin *.pem
   

4. このチュートリアル用に作成したテスト・ディレクトリーを削除します。

   cd .. && rm -r hs-crypto-test
   

5. オプション: Hyper Protect Crypto Services サービス・インスタンスを削除します。

   ibmcloud resource service-instance-delete import-keys-demo
   

   サービス・インスタンスに追加のテスト鍵を作成した場合は、サービス・インスタンスのプロビジョンを解除する前に、必ず、インスタンスからすべての暗号鍵を削除してください。

次のステップ

このチュートリアルでは、Hyper Protect Crypto Services キー管理サービス API をセットアップし、暗号キーを作成し、暗号化されたキーを Hyper Protect Crypto Services サービス・インスタンスに安全にインポートする方法について学習しました。

• ルート鍵を使用した保存中データの保護についての詳細を学習します。
• サポートされるクラウド・サービスにルート鍵をデプロイします。
• キー管理サービス API の詳細をご覧ください。