检索根密钥或标准密钥的列表

对于高级视图，可以通过对以下端点进行 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	区域缩写（例如，us-south 或 au-syd），表示 Hyper Protect Crypto Services 服务实例所在的地理区域。 有关更多信息，请参阅区域服务端点。
   port	必需。 API 端点的端口号。
   IAM_token	您的 IBM Cloud 访问令牌。 在 cURL 请求中包含 IAM 令牌的完整内容，包括 Bearer 值。 有关更多信息，请参阅 检索访问令牌。
   instance_ID	指定给您的 Hyper Protect Crypto Services 服务实例的唯一标识。 有关更多信息，请参阅 检索实例标识。
   key_ring_ID	可选。 密钥所属的密钥环的唯一标识。 如果未指定，Hyper Protect Crypto Services 将在与指定实例关联的每个密钥环中搜索密钥。 因此，建议为更优化的请求指定密钥环标识。 注: 在没有 x-kms-key-ring 头的情况下创建的密钥的密钥环标识为: 缺省值。 有关更多信息，请参阅 管理密钥环。
   correlation_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 值开始。

例如，可能总共有 3000 密钥存储在 Hyper Protect Crypto Services 服务实例中，但是在发出 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 是数据集中特定密钥的位置。 offset 值从 0 开始，这意味着数据集中的第 10 个加密密钥位于 offset 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 查询参数的示例。