チュートリアル: 暗号鍵の作成とインポート

Key Protect を使用して、暗号鍵の作成、暗号化、およびクラウドへの取り込みを行う方法について説明します。

組織のセキュリティーの専門家であるあなたは、クラウド上の保存データのセキュリティーを強化する方法を常に模索しています。

厳格なデータ・ガバナンスと法規制上の監査要件に準拠するために、暗号鍵へのきめ細かいアクセス制御、監査証跡機能、およびオンプレミスで生成する暗号鍵をアップロードするための柔軟性のあるオプションを提供する鍵管理サービスに、アプリを統合することをあなたは希望しています。

Key Protect を使用すれば、内部の鍵管理システムを使用して暗号鍵を作成し、それらの鍵をクラウド上で使用するためにアップロードすることができます。

現在のセキュリティーのニーズに基づいて、鍵をアップロードするためのさまざまなオプションから選択できます。暗号鍵のライフサイクルを管理する際は、Cloud Identity and Access Management を使用してリソースへのアクセスを制御し、IBM Cloud Logs を使用してサービスに対する API アクティビティーをモニターします。

このチュートリアルでは、インポート・トークンを使用して Key Protect に暗号鍵をアップロードします。鍵を Key Protect にインポートするためのオプションの詳細については、鍵素材をインポートするための事前計画を参照してください。

インポート・トークンなしでの鍵のインポートについて詳しくは、ルート鍵のインポートを参照してください。

目標

このチュートリアルでは、暗号鍵を作成して Key Protect サービスに安全にインポートする作業について順に説明します。これは、 Key Protect を初めて使用するが、鍵管理システムについてある程度精通している可能性があるユーザーを対象としています。以下のステップを完了するまでにかかる時間は約 20 分です。

Key Protect CLI のセットアップ
鍵のインポートを開始するための Key Protect サービス・インスタンスの準備
OpenSSL 暗号化ツールキットを使用した暗号鍵の作成と暗号化
暗号化された鍵を以下にインポートする Key Protect インスタンス

このチュートリアルでは、IBM Cloud アカウント。

開始前に

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

以下のアカウントを作成します。 IBM Cloud アカウント。
ご使用のオペレーティング・システム用のご使用のオペレーティング・システム用の IBM Cloud 基本 CLI。
鍵の管理を開始するように Key Protect CLI のセットアッププラグインを構成します。上記の最初の 2 つのステップを既に完了している場合は、このチュートリアルに戻る前に、リンク先のステップ 3 から開始してください。
暗号ライブラリをダウンロードしてインストールする。 OpenSSL 暗号ライブラリをダウンロードしてインストールする。

以下を試行している場合、openssl コマンドを使用して、ローカル・コンピューター上に暗号鍵を生成できます。 Key Protect (初回)。このチュートリアルでは、 OpenSSL バージョン 1.0.2r 以降が必要です。

Macを使っている場合は、 OpenSSL。 Homebrew。初めてこのパッケージをインストールする場合は brew install openssl を実行し、既存のパッケージを最新バージョンにアップグレードする場合は brew upgrade openssl を実行します。
jqをダウンロードしてインストールする。

jq は、JSONデータのスライスに役立ちます。このチュートリアルでは、jq を使用して、以下を呼び出したときに返される特定のデータをキャプチャーします Key Protect API。

ステップ 1. Key Protect インスタンスの作成

IBM Cloud アカウントをセットアップした後、以下のステップを実行して Key Protect インスタンスをプロビジョンします。インスタンス。

端末ウィンドウで、以下のコマンドを実行して、以下を使用して IBM Cloud にログインします。 IBM Cloud CLI。
```
ibmcloud login
```
ログインに失敗した場合は、ibmcloud login --ssoコマンドを実行して再試行してください。フェデレーテッドIDを使用してログインする場合は、 --ssoパラメーターが必要です。このオプションを使用する場合、CLI 出力にリストされているリンクに移動して、ワンタイム・パスコードを生成します。
以下を作成するアカウントとリソース・グループを選択します。 Key Protect インスタンス。

このチュートリアルでは、ワシントン DC 地域と対話します。別の地域にログインしている場合は、次のコマンドを実行して、ワシントン DC をターゲット地域に設定してください。
```
ibmcloud target -r us-east
```
そのアカウントおよびリソース・グループ内の Key Protect のインスタンスをプロビジョンします。

最初に、以下を発行して、インスタンスのリソース・グループを指定します。
```
ibmcloud target -g <your-resource-group>
```
例: ibmcloud target -g Default

その後、以下を発行してインスタンスを作成できます。
```
ibmcloud resource service-instance-create "import-keys-demo" kms tiered-pricing us-east
```
このチュートリアルでは、ご使用の IBM Cloud アカウントに料金が発生することはありません。
オプション: 使用可能な Key Protect インスタンスをリストすることによって、 Key Protect インスタンスが正常に作成されたことを確認します。
```
ibmcloud resource service-instances
```
成功! これで、暗号鍵を保管および管理できる Key Protect インスタンスが設定されました。次のステップに進んでください。

ステップ 2 Key Protect API のセットアップ

以下のインスタンスがプロビジョンされました。 Key Protect、これで、API の使用を開始する準備ができました。

Key Protect には、暗号鍵の作成、追跡、および管理を行うために使用できる、グラフィカル・ユーザー・インターフェースおよび REST API があります。この Key Protect API にはサービスで認証するための有効な IBM Cloud IAM トークンとインスタンス ID が必要です。

このステップでは、IBM Cloud CLI を使用して、以下との対話を開始するために必要な認証資格情報を収集します。 Key Protect API。また、後のステップに備えて資格情報を取得および準備するために、資格情報を端末に環境変数として設定します。

端末ウィンドウで、 Key Protect API エンドポイントを環境変数として設定します。
```
export KP_API_URL=https://<region>.kms.cloud.ibm.com
```
IBM Cloud アクセス・トークンが、 Key Protect CLI プラグインの使用するで生成され、それを環境変数として設定します。

環境変数は認可タイプで始まるべきである、 Bearer. この例に示している CLI コマンドによって、適切なタイプが自動的に組み込まれます。
```
export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`
```
IBM Cloud アクセス・トークンは 1 時間有効ですが、必要に応じて再生成できます。新しいアクセス・トークンを生成するには、以下を実行します。 ibmcloud iam oauth-tokens コマンドを使用して作成できます。以下の取得の詳細については、 (IBM Cloud アクセス・トークン)、アクセス・トークンの取得を参照してください。
以下に関連付けられている ID を取得して、 (Key Protect インスタンス)、その値を環境変数として設定します。
```
export INSTANCE_ID=`ibmcloud resource service-instance "import-keys-demo" --output json | jq -r '.[].guid'`
```
オプション: 環境変数を端末画面に出力することによって、それらが正しく設定されていることを確認します。
```
$ echo $KP_API_URL
https://us-east.kms.cloud.ibm.com
$ echo $ACCESS_TOKEN
Bearer eyJraWQiOiIyM...
$ echo $INSTANCE_ID
c1cf624b-6bed-4d4d-bd54-8e2534258a88
```
成功! これで、Key Protect API への認証に必要なサービス資格情報が設定されました。次のステップに進んでください。

ステップ 3。インポート・トークンを作成します。

サービス資格情報を使用して、 Key Protect API との対話を開始し、暗号鍵を作成してサービスに持ち込むことができます。

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

端末セッションを使用して、新しい key-protect-test ディレクトリーに移動します。
```
mkdir key-protect-test && cd key-protect-test
```
このディレクトリーは、後のステップに備えてファイルを保管するために使用します。
以下のインポート・トークンを作成して (Key Protect インスタンス)、応答を JSON ファイルに保存します。
```
$ curl -X POST \
    "$KP_API_URL/api/v2/import_token" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: $ACCESS_TOKEN" \
    -H "bluemix-instance: $INSTANCE_ID" \
    -H "content-type: application/json" \
    -d '{
            "expiration": 1200,
            "maxAllowedRetrievals": 1
        }' > createImportTokenResponse.json
```
要求本体に、時間および使用回数に基づいてインポート・トークンの使用を制限するポリシーを設定できます。この例では、インポート・トークンの有効期限を 1200 秒 (20 分) に設定し、有効期限内に許可されるトークンの取得回数を 1 回に設定します。
インポート・トークンの詳細を表示します。
```
jq '.' createImportTokenResponse.json
```
インポート・トークンと関連付けられたメタデータ (作成日やポリシー詳細など) が出力で表示されます。次のスニペットは出力例を示しています。
```
{
    "creationDate": "2019-04-08T16:58:29Z",
    "expirationDate": "2019-04-08T17:18:29Z",
    "maxAllowedRetrievals": 1,
    "remainingRetrievals": 1
}
```

ステップ 4: インポート・トークンの取得

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

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

このステップでは、インポート・トークンと関連付けられている公開暗号鍵および nonce 値を取得します。後のステップでデータを暗号化するために公開鍵が必要であり、以下への安全なインポート要求を検証するために nonce が必要です。 Key Protect サービス。

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

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

$ curl -X GET \
    "$KP_API_URL/api/v2/import_token" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: $ACCESS_TOKEN" \
    -H "bluemix-instance: $INSTANCE_ID" > getImportTokenResponse.json

オプション: インポート・トークンの内容を検査します。
```
jq '.' getImportTokenResponse.json
```
インポート・トークンについての詳細情報が出力で表示されます。以下のスニペットは出力例を示しています (一部の値は切り捨てられています)。
```
{
    "creationDate": "2019-04-08T16:58:29Z",
    "expirationDate": "2019-04-08T17:18:29Z",
    "maxAllowedRetrievals": 1,
    "remainingRetrievals": 0,
    "payload": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv...",
    "nonce": "8zJE9pKVdXVe/nLb"
}
```
payload 値は、インポート・トークンと関連付けられた公開鍵を表しています。この値は base64 でエンコードされています。 nonce 値は、サービスへの要求が元のものであることを検証するために使用されます。後のステップで暗号鍵をインポートするときに、この値を暗号化して提供する必要があります。
公開鍵をデコードし、PublicKey.pem という名前のファイルに保存します。
```
jq -r '.payload' getImportTokenResponse.json | base64 --decode -o PublicKey.pem
```
これで、ご使用のコンピューターに公開鍵が PEM フォーマットでダウンロードされました。次のステップに進んでください。

ステップ 5. 暗号鍵の作成

Key Protect を使用すると、IBM Cloud で使用するための独自の鍵を作成してアップロードすることによって、Bring Your Own Key (BYOK) のセキュリティー上の利点を活用できます。

以下のステップでは、ローカル・コンピューター上で 256 ビット AES 対称鍵を作成します。

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

端末ウィンドウで以下の openssl コマンドを実行して、256 ビット暗号鍵を作成します。
```
openssl rand 32 > PlainTextKey.bin
```
成功! 暗号化キーは次のファイルに保存されます PlainTextKey.bin. 次のステップに進んでください。

ステップ 6. nonce の暗号化

受信するビットが、要求の一部として送信するビットと完全に同じであることを確認するには、Key Protect では、対称鍵をサービスにアップロードするときに nonce 検証が必要です。

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

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

前のステップで生成した鍵をエンコードし、エンコードされた値を環境変数として設定します。
```
KEY_MATERIAL=$(base64 PlainTextKey.bin)
```
ステップ 4 で取得した nonce 値を収集します。
```
NONCE=$(jq -r '.nonce' getImportTokenResponse.json)
```
以下の手順を実行して、ステップ 5 で生成した暗号鍵で nonce 値を暗号化します。そして、レスポンスを EncryptedValues.json.
```
ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE --output json > EncryptedValues.json
```
オプション: 示されているように jq を使用して、JSON ファイルの内容を検査します。
```
jq '.' EncryptedValues.json
```
次のステップで指定する必要のある値が出力で表示されます。以下のスニペットは出力例を示しています (一部の値は切り捨てられています)。
```
{
    "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==",
    "iv": "puQrzDX7gU1TcTTx"
}
```
encryptedNonce 値は、OpenSSL を使用して生成した暗号鍵によってラップ (暗号化) された、元の nonce を表します。この iv 値は、AES-アルゴリズムによって作成される初期化ベクター（IV）である。アルゴリズムによって生成される初期化ベクトル(IV)である。 GCM Key Protect が nonce を正常に暗号化解除できるように後で必要になります。

手順 7. 鍵の暗号化

次に、以下によって配布された公開鍵を使用して (Key Protect)、OpenSSL を使用して生成した対称鍵を暗号化します。

ステップ 4 で取得した公開鍵を使用して、生成された鍵を暗号化します。
```
openssl pkeyutl \
    -encrypt \
    -pubin \
    -keyform PEM \
    -inkey PublicKey.pem \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -in PlainTextKey.bin \
    -out EncryptedKey.bin
```
Mac OSX で openssl コマンドをMac OSX上で実行する場合、 OpenSSL が正しく設定されていることを確認する必要があるかもしれません。が適切に設定されていることを確認する必要があるかもしれない。 Homebrew を使用して OpenSSL をインストールした場合、brew update を実行してから brew install openssl を実行して、最新バージョンを取得してください。その後、実行します。 export PATH="/usr/local/opt/openssl/bin:$PATH" >> ~/.bash_profile にパッケージをシンボリックリンクする。新しい端末セッションを開き、以下を実行します。 which openssl && openssl version の最新バージョンがが。 OpenSSL /usr/local/ 引き続きエラーが発生する場合は、この例にリストされているパラメーターのみを使用するようにしてください。

成功! 暗号化された鍵は、以下のファイルに保存されます EncryptedKey.bin. 暗号化された鍵を次のステップにアップロードするための準備完了しました。 Key Protect. 次のステップに進んでください。

ステップ 8. 鍵のインポート

以下を使用して暗号化された鍵をインポートできます。 Key Protect API。

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

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

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

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

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

次の Key Protect インスタンス。(次の curl コマンドを実行することによる)
```
$ curl -X POST \
    "$KP_API_URL/api/v2/keys" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: $ACCESS_TOKEN" \
    -H "bluemix-instance: $INSTANCE_ID" \
    -H "content-type: application/json" \
    -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_256",
                    "encryptedNonce": "'"$ENCRYPTED_NONCE"'",
                    "iv": "'"$IV"'"
                }
            ]
        }' > createRootKeyResponse.json
```
要求本体に、前のステップで準備した暗号鍵を指定します。また、要求を検証するために必要な、暗号化された nonce 値および IV 値も指定します。最後に、 extractable 値が以下のように設定されます。 false は、新しい鍵を、エンベロープの暗号化に使用できるサービスのルート鍵として指定します。として指定します。

Key Protect は、TLS 1.2 または 1.3 プロトコルを介して暗号化されたパケットを受信します。ハードウェア・セキュリティー・モジュール内部で、システムは秘密鍵を使用して対称鍵を復号します。最後に、システムは対称鍵と IV を使用して、nonce を復号し、要求を検証します。

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

暗号鍵の詳細を表示します。

jq '.' createRootKeyResponse.json

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

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "encrypted-root-key",
            "state": 1,
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "extractable": false,
            "imported": true
        }
    ]
}

id 値は、鍵に割り当てられた固有 ID で、その後続の以下の呼び出しに使用されます Key Protect API。 state 値が 1 に設定されている場合は、暗号鍵がアクティブ 鍵の状態にあることを示します。 crn 値は、鍵へのフル・スコープ・パスであり、IBM Cloud 内のどこにリソースがあるのかを指定します。最後に、extractable 値および imported 値は、このリソースをサービスにインポートしたルート鍵として記述しています。

オプション: Key Protect ダッシュボードにナビゲートして、暗号鍵を表示および管理します。

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

ステップ 9。クリーンアップ

前のステップでインポートした暗号鍵の ID を収集します。
```
ROOT_KEY_ID=$(jq -r '.resources[].id' createRootKeyResponse.json)
```

以下から暗号鍵を削除します。 Key Protect インスタンス。

$ curl -X DELETE \
    "$KP_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 .

このチュートリアルに関連するすべてのローカル・ファイルを削除します。
```
rm *.json *.bin *.pem
```
このチュートリアル用に作成したテスト・ディレクトリーを削除します。
```
cd .. && rm -r key-protect-test
```
オプション: Key Protect サービス・インスタンスを削除します。
```
ibmcloud resource service-instance-delete import-keys-demo
```
追加のテスト・キーを Key Protect インスタンスで作成した場合は、インスタンスを削除またはプロビジョン解除する前に必ずインスタンスからすべての暗号鍵を削除します。

次のステップ

このチュートリアルでは、 Key Protect API を設定し、暗号鍵を作成し、および暗号化された鍵を以下に安全にインポートする方法を学習しました。 Key Protect インスタンス。

ルート鍵を使用した保存中データの保護についての詳細を学習します。
サポートされるクラウド・サービスにルート鍵をデプロイします。
以下についての詳細 Key Protect API。