擷取根金鑰或標準金鑰的清單

對於進階視圖，您可以瀏覽在您配置的實例中管理的根密鑰或標準密鑰Hyper Protect Crypto Services透過製作一個 GET 調用以下端點。

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 存取記號。 請在 cURL 要求中包含 IAM 記號的完整內容，包括 Bearer 值。 有關更多信息，請參閱 檢索訪問令牌。
   instance_ID	指派給您 Hyper Protect Crypto Services 服務實例的唯一 ID。 有關更多信息，請參閱 檢索實例 ID。
   key_ring_ID	選用。 金鑰所屬金鑰環的唯一 ID。 如果未指定，Hyper Protect Crypto Services 將在與指定實例相關聯的每個金鑰環中搜尋金鑰。 因此，建議為更最佳化的要求指定金鑰環 ID。 附註: 在沒有 x-kms-key-ring 標頭的情況下建立之金鑰的金鑰環 ID 為: 預設值。 如需相關資訊，請參閱 管理金鑰環。
   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 查詢參數。