Recuperando chaves por estado

Ao filtrar por estado de chaves específicas em sua instância do Key Protect, é possível recuperar chaves que estão nos estados que você especificar.

Por exemplo, é possível ter chaves na instância do Key Protect que estão nos estados ativo, suspenso e destruído, mas você deseja recuperar apenas as chaves no estado ativo quando percorrer uma lista de chaves.

Para obter mais informações sobre os estados de chave, consulte Estados e transições de chave.

Depois de criar ou importar suas chaves existentes para o serviço, há duas opções para visualizar essas chaves. A primeira opção, Exibir chaves por meio da lista de recursos, funciona para todas as chaves, exceto aquelas com acesso refinado. Para obter informações sobre a visualização de chaves com acesso de granulação fina, consulte Visualização de chaves de acesso de granulação fina do IAM.

Recuperando uma lista de chaves

Para uma visualização de alto nível, é possível procurar chaves que são gerenciadas em sua instância provisionada do Key Protect fazendo uma chamada GET para o terminal a seguir.

https://<region>.kms.cloud.ibm.com/api/v2/keys

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

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

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/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 as informações na Tabela 1. Para obter mais informações sobre os parâmetros opcionais disponíveis ao visualizar coleções de chaves, incluindo a capacidade de procurar suas chaves, consulte a Documentação da API referente ao método List keys.

Uma solicitação GET api/v2/keys bem-sucedida retorna uma coleção de chaves que estão disponíveis em sua instância de serviço do Key Protect.

{
    "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:kms: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": "Deprecated"
            },
            "extractable": false,
            "imported": true,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        },
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Standard-key",
            "state": 1,
            "expirationDate": "2020-03-14T03:50:12Z",
            "crn": "crn:v1:bluemix:public:kms: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": "Deprecated"
            },
            "extractable": true,
            "imported": false,
            "algorithmMode": "Deprecated",
            "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? Talvez seja necessário acessar limit e offset ou consultar seu administrador para garantir que você tenha o nível correto de acesso às chaves na 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, é possível ter 3.000 chaves totais armazenadas em sua instância do Key Protect e querer recuperar as chaves de 200 a 300 ao fazer 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://<region>.kms.cloud.ibm.com/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.

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 ter chaves em sua instância do Key Protect nos estados ativo, suspenso e destruído, mas querer recuperar somente as 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 nenhum espaço em branco ou vírgula à direita. Para obter mais informações sobre os estados de chave, consulte Estados e transições de chave.

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

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/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.

Recuperando chaves por valor Extractable

Ao especificar o parâmetro extractable na hora da consulta, é possível recuperar chaves cujo material pode sair do serviço.

Por exemplo, é possível ter chaves padrão e raiz na instância do Key Protect, mas você deseja apenas recuperar as chaves com o material de chave extraível quando fizer uma solicitação GET /keys.

O parâmetro de consulta extractable é semelhante a um booleano.

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

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?extractable=<extractable>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Substitua a variável extractable 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 extractable.

Classificação de uma lista de chaves

Usando o parâmetro sort na string de consulta classificam-se a lista de chaves retornados com base em uma ou mais propriedades chave. Para classificar em uma propriedade em ordem decrescente, prefixe o termo com "-". Para classificar várias propriedades-chave, use uma vírgula para separar cada propriedade. A primeira propriedade da lista separada por vírgulas é avaliada antes da próxima.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?sort=<sort-value>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"