状態による鍵の取得

Key Protect インスタンスの特定の鍵の状態でフィルタリングすることで、指定した状態の鍵を取得できます。

例えば、Key Protect インスタンスにアクティブ状態の鍵、中断状態の鍵、破棄状態の鍵が存在する場合に、鍵のリストを表示してアクティブ状態の鍵だけを確認したいことがあります。

鍵の状態について詳しくは、鍵の状態および遷移を参照してください。

既存の鍵を作成するか、サービスにインポートした後、鍵を表示するオプションが 2 つあります。 最初のオプションは、 リソース・リストを通してキーを表示する もので、 きめ細かなアク セスが 可能なキーを除くすべてのキーに有効である。 詳細アクセス・キーの表示については、「 詳細アクセス・キーの表示 IAM 」を参照のこと。

鍵のリストの取得

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

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

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

2. 以下の curl コマンドを実行して、鍵に関する一般的な特性を表示します。

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "x-kms-key-ring: <key_ring_ID>" \
       -H "correlation-id: <correlation_ID>"
   

   表 1 の情報に従って、要求例の変数を置き換えます。 鍵のコレクションを表示するときに使用できるオプション・パラメーターや、鍵の検索機能について詳しくは、List keys メソッドに関する API 資料を参照してください。

        存在している地理的領域を表す、
        地域の省略形
        (例: `us-south` または
        `eu-gb`)。 詳細については、[リージョナル・サービス・エンドポイント](/docs/key-protect?topic=key-protect-regions#service-endpoints)を参照してください。 |

| key_ID_or_alias | 必須。 検査対象となる鍵の固有 ID または別名。 | | IAM_token | 必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを curl 要求に組み込みます。 詳細については、アクセス・トークンのリトリーブを参照してください。 | | instance_ID | 必須。 Key Protect サービス・インスタンスに割り当てられた固有 ID。 詳細については、インスタンス ID のリトリーブを参照してください。 | | key_ring_ID | オプション。 ターゲットの鍵リングの固有 ID。 特に指定がない場合、レスポンスには、指定されたインスタンス内でユーザーがアクセス権を持つすべてのリソースが含まれます。 返される応答には、指定されたキーリング内でユーザーがアクセス権を持つリソースのみが含まれます。 詳しくは、鍵のグループ化を参照してください。 | | correlation_ID | オプション。 トランザクションを追跡し、相互に関連付けるために使用される固有 ID。 |

GET api/v2/keys 要求が成功すると、Key Protect サービス・インスタンス内の使用可能な鍵の集合が返されます。

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "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",
            "createdBy": "...",
            "creationDate": "2020-03-11T16:30:06Z",
            "lastUpdateDate": "2020-03-11T16:30:06Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": false,
            "imported": true,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        },
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Standard-key",
            "state": 1,
            "expirationDate": "2020-03-14T03:50:12Z",
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "createdBy": "...",
            "creationDate": "2020-03-12T03:50:12Z",
            "lastUpdateDate": "2020-03-12T03:50:12Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": true,
            "imported": false,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        }
    ]
}

デフォルトでは、GET api/v2/keys は最初の 200 個の鍵を返しますが、照会時に limit パラメーターを使用してこの制限を調整できます。 limit および offset について詳しくは、鍵のサブセットの取得を参照してください。

鍵の完全なリストが表示されない場合、 limit および offset を利用するか、管理者にお問い合わせいただき、インスタンス内のキーに対する適切なアクセス権限が割り当てられていることを確認してください。 詳しくは、『鍵を表示またはリストできない』を参照してください。

鍵のサブセットの取得

照会時に limit パラメーターおよび offset パラメーターを指定することによって、指定した offset 値から始まる、鍵のサブセットを取得できます。

例えば、Key Protect インスタンスに 合計 3000 個の鍵を保管しているが、GET /keys 要求を行うときに 200 から 300 までの鍵を取得したい場合が考えられます。

以下の要求例を使用して、さまざまな鍵セットを取得できます。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?offset=<offset>&limit=<limit>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

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

オフセットは、データ・セット内の特定の鍵の位置です。 offset 値はゼロが基準です。つまり、データ・セット内の 10 番目の暗号鍵はオフセット 9 の位置にあります。

状態による鍵の取得

照会時に state パラメーターを指定することにより、 指定した状態にある鍵を取得できます。

例えば、Key Protect インスタンス内に アクティブ状態、中断状態、および破棄状態の鍵が存在する可能性があるが、 GET /keys 要求を行うときはアクティブ状態の鍵のみを取得したい場合が考えられます。

state 照会パラメーターは、空白も末尾のコンマもない、コンマによって区切られた 0 から 5 までの 整数のリストを受け入れます。 鍵の状態について詳しくは、鍵の状態および遷移を参照してください。

以下の要求例を使用して、さまざまな鍵セットを取得できます。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?state=<state_integers>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

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

使用上の注意点については、state 照会パラメーターの次の設定例を確認してください。

extractable 値による鍵の取得

照会時に extractable パラメーターを指定すると、鍵素材がサービスの外部に出ることができる鍵を取得できます。

例えば、Key Protect インスタンスに標準鍵とルート鍵の両方がある場合に、GET /keys 要求を実行して、鍵素材を抽出できる鍵だけを取得したいことがあります。

extractable 照会パラメーターはブール値を取ります。

以下の要求例を使用して、さまざまな鍵セットを取得できます。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?extractable=<extractable>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

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

使用上の注意点については、extractable 照会パラメーターの次の設定例を確認してください。

キーのリストの並べ替え

1 つ以上のキー・プロパティーに基づいて返される照会ストリング キーのリストをソートします。 で sort パラメーターを使用する。 プロパティの降順でソートするには、用語の前に"-"を付けます。複数のキー・プロパティでソートするには、各プロパティをカンマで区切ります。 カンマで区切られたリストの最初のプロパティが、次のプロパティの前に評価される。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?sort=<sort-value>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"