루트 키 또는 표준 키 목록 검색

상위 레벨 보기의 경우에는 다음 엔드포인트에 대한 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 액세스 토큰입니다. cURL 요청에 Bearer 값 등 IAM 토큰의 전체 컨텐츠를 포함하십시오. 자세한 정보는 액세스 토큰 검색을 참조하십시오.
   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 값은 0부터 시작합니다. 즉, 데이터 세트의 열 번째 암호화 키는 오프셋 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 조회 매개변수 설정에 대한 다음 예제를 확인하십시오.