Recuperando uma lista de suas chaves raiz ou chaves padrão

Para uma visualização de alto nível, é possível navegar em suas chaves raiz ou em chaves padrão que são gerenciadas em sua instância provisionada dos Hyper Protect Crypto Services fazendo uma chamada GET para o terminal a seguir.

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

1. Recupere suas credenciais de serviço e autenticação para trabalhar com chaves no serviço.

2. Visualize características gerais sobre suas chaves executando o comando cURL a seguir.

   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>' \
   

   Substitua as variáveis na solicitação de exemplo de acordo com a tabela a seguir.

   Tabela 2. Descreve as variáveis necessárias para visualizar chaves com a API

   Variável	Descrição
   region	A abreviação de região, como us-south ou au-syd, que representa a área geográfica em que a sua instância de serviço do Hyper Protect Crypto Services reside. Para obter mais informações, consulte Terminais de serviços regionais.
   port	Obrigatório. O número da porta do terminal da API.
   IAM_token	Seu token de acesso do IBM Cloud. Inclua o conteúdo integral do token IAM, incluindo valor Bearer, na solicitação cURL. Para obter mais informações, consulte Recuperando um token de acesso.
   instance_ID	O identificador exclusivo que é designado para sua instância de serviço Hyper Protect Crypto Services. Para obter mais informações, consulte Recuperando um ID de instância.
   key_ring_ID	Opcional. O identificador exclusivo do conjunto de chaves ao qual a chave pertence. Se não especificado, o Hyper Protect Crypto Services procurará a chave em cada conjunto de chaves associado à instância especificada. Portanto, sugere-se especificar o ID do conjunto de chaves para uma solicitação mais otimizada. Nota: o ID do conjunto de chaves de chaves que são criadas sem um cabeçalho x-kms-key-ring é: default. Para obter mais informações, consulte Gerenciando conjuntos de chaves.
   correlation_ID	Opcional. O identificador exclusivo que é usado para rastrear e correlacionar transações.

   Uma solicitação GET /v2/keys bem-sucedida retorna uma coleção de chaves que estão disponíveis em sua instância dos 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
         }
       }
     ]
   }
   

   Por padrão, GET api/v2/keys retorna as suas primeiras 200 chaves, mas é possível ajustar esse limite usando o parâmetro limit no momento da consulta. Para saber mais sobre o limit e o offset, veja Recuperando um subconjunto de chaves.

   Não está vendo a lista completa de chaves? Pode ser necessário usar limit e offset ou verifique com seu administrador para assegurar que você tenha designado o acesso de nível correto para as chaves em sua instância Para saber mais, consulte Não é possível visualizar ou listar chaves.

Recuperando um subconjunto de chaves

Ao especificar os parâmetros limit e offset no momento da consulta, é possível recuperar um subconjunto de suas chaves, começando com o valor offset especificado.

Por exemplo, você pode ter um total de 3000 chaves que são armazenadas em sua instância de serviço do Hyper Protect Crypto Services, mas você deseja recuperar de 200 a 300 chaves quando faz uma solicitação GET /keys.

É possível usar a solicitação de exemplo a seguir para recuperar um conjunto diferente de chaves.

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>'

Substitua as variáveis limit e offset em sua solicitação de acordo com a tabela a seguir.

Para obter notas de uso, verifique os exemplos a seguir para configurar os seus parâmetros de consulta limit e offset.

Deslocamento é o local de uma determinada chave em um conjunto de dados. O valor offset é baseado em zero, o que significa que a décima chave de criptografia em um conjunto de dados está no deslocamento 9.

Recuperando chaves por estado

Ao especificar o parâmetro state no momento da consulta, é possível recuperar as chaves que estão nos estados especificados.

Por exemplo, é possível que você tenha chaves em sua instância de serviço que estejam nos estados ativo, suspenso e destruído, mas queira recuperar somente chaves no estado ativo ao fazer uma solicitação GET /keys.

O parâmetro de consulta de estado obtém uma lista de números inteiros de 0 a 5 delimitados por vírgulas sem espaço em branco ou vírgulas à direita. Os estados válidos são baseados no NIST SP 800-57. Para obter mais informações sobre estados de chaves, consulte Estados e transições de chaves.

É possível usar a solicitação de exemplo a seguir para recuperar um conjunto diferente de chaves.

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>'

Substitua a variável state em sua solicitação de acordo com a tabela a seguir.

Para observações de uso, confira os exemplos a seguir para configurar seu parâmetro de consulta state.