IBM Cloud Docs
鍵リングを使用した鍵のグループ化

鍵リングを使用した鍵のグループ化

IBM® Key Protect for IBM Cloud® では、同じ IAM アクセス権限を必要とするターゲットのユーザー・グループのために、鍵のグループを作成することができます。

アカウント管理者は、 Key Protect サービス・インスタンスの鍵を「鍵リング」と呼ばれるグループにバンドルできます。 1 つの鍵リングは、サービス・インスタンス内の鍵のうち、同じ IAM アクセス権限を必要とするものをすべてまとめたものです。 例えば、チーム・メンバーの特定のグループが、特定の鍵のグループに対して特定のタイプのアクセス権限を必要としている場合は、それらの鍵をまとめた鍵リングを作成し、ターゲットのユーザー・グループに適切な IAM アクセス・ポリシーを割り当てます。 鍵リングに対するアクセス権限を割り当てられたユーザーは、その鍵リング内に存在するリソースの管理と作成を行えます。

あるビジネス部門がアクセスできる一連の鍵に、他のビジネス部門がアクセスできてはいけないという場合にも、鍵リングは便利です。 アカウント管理者は、ビジネス部門ごとに鍵リングを作成し、適切なレベルのアクセス権限を適切なユーザーに割り当てることができます。 アカウント管理者が、特定の鍵リングのプラットフォーム管理を他の人に委任したい場合は、 鍵リング・レベルのプラットフォーム管理者の役割をユーザーに割り当てることができます。 そうすれば、代理管理者が、鍵リングを管理して適切なユーザーにアクセス権限を付与できるようになります。

以下の鍵リングへのアクセス権限を付与できます。 Key Protect インスタンス (以下を使用) IBM Cloud コンソール、IAM API、IAM CLI。

以下の鍵リングを作成する前に (Key Protect インスタンス)、以下の考慮事項に留意してください。

  • すべての Key Protect インスタンスに、デフォルトの鍵リングがあります。 Key Protect インスタンスを新規作成すると必ず、default という ID の鍵リングが生成されます。 特に鍵リングを指定して関連付けた場合を除き、鍵はすべてこのデフォルトの鍵リングに入れられます。

  • 鍵リングには標準鍵とルート鍵を入れることができます。 鍵リングには標準鍵もルート鍵も両方入れることができます。 1 つの鍵リングに入れられる鍵の数に制限はありません。

  • 1 つの鍵は、一度に 1 つの鍵リングにしか含められません。 1 つの鍵は 1 つの鍵リングにしか入れられません。 鍵リングへの割り当ては、鍵の作成時に行われます。 鍵リングの ID を作成時に渡さなければ、その鍵は default 鍵リングに入れられます。

鍵リングの最大数は、サービス・インスタンス 1 つあたり 50 個です。

UI を使用した鍵リングの作成

鍵リングを作成するには、「ライター」または「管理者」のどちらかのサービス役割が必要です。

鍵リングを作成するには、次のようにします。

  1. 左側のナビゲーションで**「鍵リング (Key rings)」**をクリックします。
  2. **「鍵リング (Key rings)」パネルで、「作成」**ボタンをクリックします。
  3. **「鍵リングの作成 (Create a key ring)」**タブで、使用できる文字に関する説明に従って、新規鍵リングに名前を付けます。 次に、 作成 をクリックします。

作成されると、新規鍵リングが鍵リングのリストに表示されるので、その鍵リングに鍵を移動したり、鍵を作成したりできます。

API を使用した鍵リングの作成

以下のエンドポイントへの POST 呼び出しを行うことにより、鍵リングを作成します。

https://<region>.kms.cloud.ibm.com/api/v2/keys
  1. サービス内で鍵の処理を行うために、認証資格情報を取得します

  2. 以下の curl コマンドを実行して、鍵リングを作成します。

    $ curl -X POST \
        "https://<region>.kms.cloud.ibm.com/api/v2/key_rings/<key_ring_id>" \
        -H "authorization: Bearer <IAM_token>" \
        -H "bluemix-instance: <instance_ID>" \
        -H "correlation-id: <correlation_ID>"
    

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

Key Protect API でキーホルダーを作成するために必要な変数について説明します。
変数 説明
リージョン 必須。 Key Protect インスタンスが存在する地域を表す us-southeu-gb などの地域略称。

詳細については、 地域サービスエンドポイントを 参照してください。
key_ring_id 必須。 作成する鍵リングの固有 ID。
IAM_token 必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを cURL 要求に組み込みます。

詳細については、 アクセストークンの取得を 参照してください。
instance_ID 必須。 Key Protect サービス・インスタンスに割り当てられた固有 ID。

詳細については、 インスタンスIDの取得を 参照してください。
correlation_ID オプション。トランザクションを追跡し、相互に関連付けるために使用される固有 ID。

POST api/v2/key_rings リクエストに成功すると、 HTTP が返される。 201 Created これは、キーホルダーが作成され、標準キーとルートキーを保持できるようになったことを示す。 これは、キーホルダーが作成され

別の鍵リングへの鍵の移動

要件が変わったり、新しいチーム・メンバーが組織に加わったりしたら、それらの組織的変更を反映するために新規鍵リングの作成が必要になることがあります。 そのような鍵リングを作成したら、一般的には、既存の鍵リングの鍵を、IAM アクセス権限が異なる新規鍵リングに移動することが必要になります。 例えば、オンボーディングするチームに、デフォルトの鍵リングではなく、以前作成したカスタム鍵リングに含まれている鍵に対する特定のアクセス権限が必要であるとします。 オンボーディング・チーム専用の新規鍵リングを作成できますが、鍵は一度に 1 つの鍵リングにしか関連付けられないので、対象の鍵を新規鍵リングに移動する必要があります。

別の鍵リングに鍵を移動した後、その変更が有効になるまで最大 10 分かかる場合があります。

UI を使用した別の鍵リングへの鍵の移動

表示されるはずのオプションの一部が表示されない場合は、特定のアクションを実行する権限がないことが原因である可能性があります。 アクションを実行するための十分な役割と権限があることを確認してください。 役割について詳しくは、ユーザーのアクセス権限の管理を参照してください。

鍵を移動するには、移動する鍵とターゲットの鍵リングの両方に対する「管理者」サービス役割が必要です。

**「鍵」**パネルから、以下を行います。

  1. 移動する鍵を見つけます。 **「鍵リング ID (Key ring ID)」ドロップダウン・リストで、鍵が現在配置されている鍵リングを選択してリングを指定すると便利です。 左側のナビゲーションで「鍵リング (Key rings)」をクリックし、該当する鍵リングを見つけて、設定のドロップダウン・リストに含まれている「関連付けられている鍵の表示 (View associated keys)」**をクリックすることもできます。 これにより、その鍵リングに関連付けられているすべての鍵が表示されます。
  2. 「⋯」ボタンをクリックし、ドロップダウン・リストから**「鍵リングの編集 (Edit key ring)」**を選択します。
  3. ドロップダウン・リストで、鍵の移動先の鍵リングを選択します。 次に**「保存」**をクリックします。

API を使用した別の鍵リングへの鍵の移動

以下のエンドポイントに PATCH 呼び出しを実行して、鍵を別の鍵リングに移動します。

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>
  1. サービス内で鍵の処理を行うために、認証資格情報を取得します

    キーのキー・リングを更新するには、少なくともキーおよびターゲット・キー・リングに対する_「マネージャー」_サービス・アクセス権限が必要です。 IAM ロールがどのように Key Protect サービス・アクションにどのようにマップされるかについては、サービス・アクセス役割を確認してください。

  2. 以下の curl コマンドを実行して、鍵の鍵リングを更新します。

    $ curl -X PATCH \
        https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias> \
        -H 'accept: application/vnd.ibm.kms.key+json' \
        -H 'authorization: Bearer <IAM_token>' \
        -H 'bluemix-instance: <instance_ID>' \
        -H 'content-type: application/vnd.ibm.kms.key+json' \
        -H "x-kms-key-ring: <original_key_ring_ID>" \
        -H "correlation-id: <correlation_ID>" \
        -d '{
        "keyRingID": "<new_key_ring_ID>"
        }'
    

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

Key Protect API でキーのキーホルダーを更新するために必要な変数について説明します。
変数 説明
リージョン 必須。 Key Protect インスタンスが存在する地域を表す us-southeu-gb などの地域略称。

詳細については、 地域サービスエンドポイントを 参照してください。
keyID_or_alias 必須。 更新する鍵の固有 ID または別名。
IAM_token 必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを cURL 要求に組み込みます。

詳細については、 アクセストークンの取得を 参照してください。
instance_ID 必須。 Key Protect サービス・インスタンスに割り当てられた固有 ID。

詳細については、 インスタンスIDの取得を 参照してください。
original_key_ring_ID オプション。 鍵が現在含まれている鍵リングの固有 ID。 指定しない場合は、Key Protect が、指定されたインスタンスに関連付けられているすべての鍵リングで鍵を検索します。 そのため、鍵リング ID を指定して、より最適化された要求を行うことをお勧めします。 注: x-kms-key-ring ヘッダーを指定せずに作成した鍵の鍵リング ID は、default になります。
correlation_ID オプション。トランザクションを追跡し、相互に関連付けるために使用される固有 ID。
new_key_ring_ID 必須。 鍵の移動先にするターゲットの鍵リングの固有 ID。

PATCH api/v2/keys/keyID_or_alias 要求が成功すると、鍵が含まれている鍵リングの ID を含む鍵のメタデータが返されます。

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "type": "application/vnd.ibm.kms.key+json",
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "name": "test-root-key",
            "aliases": [
                "alias-1",
                "alias-2"
            ],
            "description": "A test root key",
            "state": 1,
            "extractable": false,
            "keyRingID": "new-key-ring",
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "imported": false,
            "creationDate": "2020-03-12T03:37:32Z",
            "createdBy": "...",
            "algorithmType": "Deprecated",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "algorithmBitSize": 256,
            "algorithmMode": "Deprecated",
            "lastUpdateDate": "2020-03-12T03:37:32Z",
            "keyVersion": {
                "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
                "creationDate": "2020-03-12T03:37:32Z"
            },
            "dualAuthDelete": {
                "enabled": false
            },
            "deleted": false
        }
    ]
}

鍵リングへのアクセス権限の付与

IBM Cloud コンソール、 IAM API、または CLI{ :external} を使用して、 Key Protect インスタンス内のキーホルダーへのアクセスを許可できます。

IBM Cloud IAM 役割と Key Protect アクションの対応関係については、役割と許可を参照してください。

コンソールを使用して鍵リングに対するアクセス権限を割り当てるには、以下のようにします。

  1. メニュー・バーから、「管理」>**「アクセス (IAM)」をクリックし、「ユーザー」**を選択して、アカウント内の既存のユーザーを参照します。

  2. いずれかのテーブル行を選択し、「⋯」アイコンをクリックして、そのユーザーのオプションのリストを開きます。

  3. オプション・メニューから**「アクセス権限の割り当て」**をクリックします。

  4. **「ユーザーへの追加のアクセス権限の割り当て」**をクリックします。

  5. **「IAM サービス」**ボタンをクリックします。

  6. サービスのリストから、以下を選択します。 Key Protect.

  7. **「属性に基づいたサービス」**を選択します。

  8. **「インスタンス ID」**属性を選択し、鍵リングが存在するインスタンスを選択します。

  9. **「鍵リング ID (Key Ring ID)」**属性を選択し、鍵リングに関連付けられている ID を入力します。

  10. ユーザーにアクセス権限を割り当てるプラットフォーム・アクセス役割とサービス・アクセス役割の組み合わせを選択します。

  11. 追加 をクリックします。

  12. 必要に応じてプラットフォーム・アクセス役割とサービス・アクセス役割の追加を続け、終了したら**「割り当て」**をクリックします。 ユーザーがインスタンス内の鍵リングをリスト、作成、および削除するには、少なくともインスタンス全体に対する_リーダー_・アクセス権限をユーザーに割り当てる必要があることに注意してください。

画像は、キーホルダーへのアクセスをユーザーに許可する方法の例です。
インスタンスへのユーザアクセス権を付与する方法を示します。

API を使用した鍵リングのリスト表示

概要を参照するために、次のエンドポイントへの GET 呼び出しをして、Key Protect のプロビジョン済みインスタンスで管理されている鍵リングを表示できます。

https://<region>.kms.cloud.ibm.com/api/v2/keys_rings
  1. サービス内で鍵の処理を行うために、認証資格情報を取得します

  2. 以下を実行して、キーホルダーに関する一般的な特性を表示します curl コマンドを使用して作成できます。

    $ curl -X GET \ "https://<region>.kms.cloud.ibm.com/api/v2/key_rings?totalCount=<show_total>&offset=<offset_value>&limit=<offset_limit>" \
        -H "accept: application/vnd.ibm.kms.key_ring+json" \
        -H "authorization: Bearer <IAM_token>" \
        -H "bluemix-instance: <instance_ID>" \
        -H "correlation-id: <correlation_ID>"
    

    疑問符 ? に続く照会パラメーターはオプションですが、それらの使用法を文書化するためにここに含まれています。 (:: 注)

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

Key Protect API でキーリングを表示するために必要な変数について説明する。
変数 説明
リージョン 必須。 Key Protect インスタンスが存在する地域を表す us-southeu-gb などの地域略称。

詳細については、 地域サービスエンドポイントを 参照してください。
IAM_token 必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを cURL 要求に組み込みます。

詳細については、 アクセストークンの取得を 参照してください。
instance_ID 必須。 Key Protect インスタンスに割り当てられる一意の識別子。

詳細については、 インスタンスIDの取得を 参照してください。
correlation_ID オプション。 トランザクションを追跡し、相互に関連付けるために使用される固有 ID。
offset_limit オプション。 デフォルトでは、GET /key_rings は、デフォルトの鍵リングを含む 51 個の鍵リングのシーケンスを返します。 別の鍵リング・セットを取得するには、offset とともに limit を使用して、使用可能なリソースをページ編集します。 limit の最大値は 「5,000」 です。
offset_value オプションoffsetを指定することにより、offset 値から始まる鍵リングのサブセットが取得されます。
show_total オプションtrue に設定すると、応答メタデータは、ページ編集で使用されている totalCount の値を返します。

GET api/v2/key_rings 要求が成功すると、以下で使用可能な鍵リングのコレクションが返されます。 Key Protect サービス・インスタンス。

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key_ring+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "id": "default"
        },
        {
            "id": "Sample Key Ring 2",
            "creationDate": "2020-03-12T11:00:06Z",
            "createdBy": "..."
        }
    ]
}

API を使用した鍵リングの削除

以下のエンドポイントへの DELETE 呼び出しを行うことによって、鍵リングを削除できます。

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

このアクションは、鍵リングに 破棄 状態以外の状態の鍵が少なくとも 1 つ含まれている場合は成功しません。 鍵リング内の鍵のみが 破棄 状態の場合、削除コマンドに force=true が追加されると、鍵リングを削除できます。 その状態の鍵は、自動的に default 鍵リングに転送されます。

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

  2. 削除する鍵リングの ID を取得します。

    鍵リングの ID は、以下の場所にあります。 (Key Protect インスタンス) 鍵リングのリストを取得することで見つけることができます。

  3. 次の curl コマンドを実行して、鍵リングを削除します。 force=true が存在することに注意してください。これは、 破棄 状態の鍵が含まれている場合に鍵リングを強制的に削除します。

    $ curl -X DELETE \
        "https://<region>.kms.cloud.ibm.com/api/v2/key_rings/<key_ring_id>?force=true" \
        -H "authorization: Bearer <IAM_token>" \
        -H "bluemix-instance: <instance_ID>" \
        -H "prefer: <return_preference>"
    

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

Key Protect API で鍵を削除するために必要な変数について説明する。
変数 説明
リージョン 必須。 Key Protect インスタンスが存在する地域を表す us-southeu-gb などの地域略称。

詳細については、 地域サービスエンドポイントを 参照してください。
key_ring_id 必須。 削除する鍵リングの固有 ID。
IAM_token 必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを cURL 要求に組み込みます。

詳細については、 アクセストークンの取得を 参照してください。
instance_ID 必須。 Key Protect サービス・インスタンスに割り当てられた固有 ID。

詳細については、 インスタンスIDの取得を 参照してください。

要求が成功すると、204 No Content の HTTP 応答が返されます。これは、鍵リングが正常に削除されたことを示しています。