インポート・トークンの作成

最初に Key Protect インスタンス用のインポート・トークンを 作成することによって、ルート鍵素材をクラウドにセキュアに インポートできるようになります。

インポート・トークンは、ルート鍵素材を暗号化して Key Protect にセキュアに取り込むために、指定するポリシーに基づいて使用されます。 鍵をクラウドにセキュアにインポートすることについて詳しくは、クラウドへの独自の暗号鍵の取り込みを参照してください。

この機能は現在、 Key Protect Dedicatedとは互換性がありません。

API を使用したインポート・トークンの作成

以下のエンドポイントへの POST 呼び出しを行うことによって、 Key Protect インスタンスと関連付けられた インポート・トークンを作成します。 

https://<region>.kms.cloud.ibm.com/api/v2/import_token

  1. サービス内で鍵の処理を行うために、サービス資格情報および認証資格情報を取得します。

  2. Key Protect API を呼び出して、インポート トークンのポリシーを設定します。

    $ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/import_token" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/json" \
    -d '{
            "expiration": <expiration_time>,
            "maxAllowedRetrievals": <use_count>
        }'

    次の表に従って、例の要求内の変数を置き換えてください。

インポートトークンの作成に必要な変数について説明します。
変数 説明
リージョン 必須。 Key Protect インスタンスが存在している地理的領域を表す、地域の省略形 (例: us-south または eu-gb)。 詳しくは、地域のサービス・エンドポイントを参照してください。
IAM_token 必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを curl 要求に組み込みます。 詳細については、アクセス・トークンのリトリーブを参照してください。
instance_ID 必須。 Key Protect サービス・インスタンスに割り当てられた固有 ID。 詳細については、インスタンス ID のリトリーブを参照してください。
expiration_time インポート・トークンが作成されてから有効である期間 (秒)。 最小値は 300 秒 (5 分)、最大値は 86400 (24 時間) です。 デフォルト値は 600 (10 分) です。
use_count インポート・トークンを有効期間内に取得できる回数。これを超えるとアクセスできなくなります。 デフォルト値は 1 です。 最大値は 500 です。

POST api/v2/import_token 要求が成功すると、 Key Protect インスタンス用のインポート・トークンが作成されます。 応答本体には、インポート・トークンと関連付けられたメタデータ (作成日やポリシー詳細など) が含まれています。 次のスニペットは出力例を示しています。

Key Protect インスタンスに関連付けられるインポート・トークンは、どの時点でも 1 つしか持つことができません。 後続のインポート・トークンの作成要求はすべて、前のインポート・トークンをオーバーライドします。

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

API を使用したインポート・トークンの取得

以下のエンドポイントへの GET 呼び出しを行うことによって、 Key Protect インスタンスと関連付けられた インポート・トークンを取得します。 

https://<region>.kms.cloud.ibm.com/api/v2/import_token

  1. サービス内で鍵の処理を行うために、サービス資格情報および認証資格情報を取得します。

  2. Key ProtectKey Protect インスタンスに関連付けられているインポートトークンを取得するには、 API を呼び出してください。

    $ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/import_token" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

    次の表に従って、例の要求内の変数を置き換えてください。

Key Protect API を使用してインポートトークンを取得するために必要な変数について説明します。
変数 説明
リージョン 必須。 Key Protect インスタンスが存在している地理的領域を表す、地域の省略形 (例: us-south または eu-gb)。 詳しくは、地域のサービス・エンドポイントを参照してください。
IAM_token 必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを curl 要求に組み込みます。 詳細については、アクセス・トークンのリトリーブを参照してください。
instance_ID 必須。 Key Protect サービス・インスタンスに割り当てられた固有 ID。 詳細については、インスタンス ID のリトリーブを参照してください。

GET api/v2/import_token 要求が成功すると、 Key Protect インスタンス用のインポート・トークンが取得されます。 応答本体には、インポート・トークンと関連付けられたメタデータ (作成日やポリシー詳細など) が含まれています。

取得されたインポート・トークンは、インポート・トークンの有効期限が切れる日付まで、1 つ以上の鍵をインポートするために再使用できます。

以下のスニペットは出力例を示しています (一部の値は切り捨てられています)。

{
    "creationDate": "2019-04-08T16:58:29Z",
    "expirationDate": "2019-04-08T17:18:29Z",
    "maxAllowedRetrievals": 1,
    "remainingRetrievals": 0,
    "payload": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
    "nonce": "8zJE9pKVdXVe/nLb"
}

応答本体には公開暗号鍵も含まれています。 これは、 Key Protect インスタンスに鍵素材をアップロードする前に ルート鍵を暗号化するために 使用できます。

この例では、payload 値が、インポート・トークンと関連付けられた公開鍵を表しています。 この値は base64 でエンコードされています。 セキュリティをさらに強化するため、 Key Protect では、サービスへのキーインポート要求の真正性を確認するために使用される「 nonce 」値も提供しています。 これらの値の使用方法について詳しくは、チュートリアル: 暗号鍵の作成とインポートを参照してください。

次の作業