ルート鍵または標準鍵のリストの取得

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

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys

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

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

   curl -X GET \
   "https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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>' \
   

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

   表 2. API を使用して鍵を表示するために必要な変数について説明します。

   変数	説明
   region	Hyper Protect Crypto Services サービス・インスタンスを置く地理的領域を表す、地域の省略形 (us-south、au-syd など)。 詳細については、リージョナル・サービス・エンドポイントを参照してください。
   port	必須。 API エンドポイントのポート番号。
   IAM_token	IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを cURL 要求に組み込みます。 詳細については、アクセス・トークンのリトリーブを参照してください。
   instance_ID	Hyper Protect Crypto Services サービス・インスタンスに割り当てられた固有 ID。 詳細については、インスタンス ID のリトリーブを参照してください。
   key_ring_ID	オプション。 鍵が属する鍵リングの固有 ID。 指定しないと、Hyper Protect Crypto Services は、指定されたインスタンスに関連付けられているすべての鍵リングで鍵を検索します。 このため、鍵リング ID を指定して、より最適化された要求を行うことをお勧めします。 注: x-kms-key-ring ヘッダーを指定せずに作成した鍵の鍵リング ID は「default」になります。 詳しくは、鍵リングの管理を参照してください。
   correlation_ID	オプション。 トランザクションを追跡し、相互に関連付けるために使用される固有 ID。

   GET /v2/keys 要求が成功すると、Hyper Protect Crypto Services インスタンス内の使用可能な鍵の集合が返されます。

   {
     "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:hs-crypto: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": "CBC_PAD"
         },
         "extractable": false,
         "imported": true,
         "algorithmMode": "CBC_PAD",
         "algorithmBitSize": 256,
         "dualAuthDelete": {
           "enabled": false
         }
       },
       {
         "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
         "type": "application/vnd.ibm.kms.key+json",
         "name": "Standard-key",
         "state": 1,
         "crn": "crn:v1:bluemix:public:hs-crypto: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": "CBC_PAD"
         },
         "extractable": true,
         "imported": false,
         "algorithmMode": "CBC_PAD",
         "algorithmBitSize": 256,
         "dualAuthDelete": {
           "enabled": false
         }
       }
     ]
   }
   

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

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

鍵のサブセットの取得

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

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

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

curl -X GET \
  'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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 変数を置き換えてください。

照会パラメーター limit および offset を設定する以下の例で、使用上の注意点を確認してください。

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

状態による鍵の取得

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

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

状態クエリー・パラメーターは、空白や末尾のコンマを含まず、コンマで区切られた 0 から 5 までの整数のリストを取ります。 有効な状態は NIST SP 800-57 に基づきます。 鍵の状態について詳しくは、鍵の状態および遷移を参照してください。

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

curl -X GET \
  'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/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 照会パラメーターの次の設定例を確認してください。