Agrupando chaves usando a API

É possível proteger uma chave de criptografia de dados especificada (DEK) com uma chave raiz que você gerencia em Hyper Protect Crypto Services.

Ao fornecer uma chave raiz para agrupamento, assegure-se de que a chave raiz seja de 128, 192 ou 256 bits para que a chamada de agrupamento possa ser bem-sucedida. Se você criar uma chave raiz no serviço, Hyper Protect Crypto Services gera uma chave de 256 bits a partir dos HSMs, suportada pelo algoritmo AES-CBC.

Após você designar uma chave raiz no serviço, poderá agrupar uma DEK com criptografia avançada fazendo uma chamada POST para o terminal a seguir.

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

1. Recuperar suas credenciais de autenticação e serviço para que funcionem com chaves no serviço.

2. Copie o material de chave do DEK que você deseja gerenciar e proteger.

   Se você tem privilégios de gerenciador ou de gravador para sua instância de serviço do Hyper Protect Crypto Services, é possível recuperar o material de chave para uma chave específica fazendo uma solicitação de GET /v2/keys/<key_ID>.

3. Copie o ID da chave raiz que você deseja usar para agrupamento.

4. Execute o comando cURL a seguir para proteger a chave com uma operação de agrupamento.

   curl -X POST \
     'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/wrap' \
     -H 'accept: application/vnd.ibm.kms.key_action+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'content-type: application/vnd.ibm.kms.key_action+json' \
     -H 'x-kms-key-ring: <key_ring_ID>' \
     -H 'correlation-id: <correlation_ID>' \
     -d '{
     "plaintext": "<data_key>"
   }'
   

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

   Tabela 1. Descreve as variáveis necessárias para agrupar uma chave especificada

   Variável	Descrição
   region	Obrigatório. 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.
   key_ID	Obrigatório. O identificador exclusivo para a chave raiz que você deseja usar para agrupamento.
   IAM_token	Obrigatório. 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	Obrigatório. 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 da 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.
   data_key	O material de chave da DEK que você deseja gerenciar e proteger. O valor plaintext deve ser codificado em base64. Para gerar um novo DEK, omita o atributo plaintext O serviço gera um texto simples aleatório (32 bytes), agrupa esse valor e, em seguida, retorna os valores gerados e agrupados na resposta. Os valores gerados e agrupados são codificados em base64 e será necessário decodificá-los a fim de decriptografar as chaves.

   Sua chave de criptografia de dados agrupados contendo o material de chave codificado em Base64 é retornada no corpo da entidade de resposta. O corpo de resposta também contém o ID da versão da chave que foi usado para agrupar o texto simples fornecido. O objeto JSON a seguir mostra um valor retornado de exemplo.

   {
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "02fd6835-6001-4482-a892-13bd2085f75d"
     }
   }
   

   Se você omitir o atributo plaintext ao fazer a solicitação de agrupamento, o serviço retornará a chave de criptografia de dados gerada (DEK) e a DEK agrupada no formato codificado em Base64.

   {
     "plaintext": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6"
     }
   }
   

   O valor plaintext representa a DEK desagrupada e o valor ciphertext representa a DEK agrupada, ambos codificados em base64. O valor keyVersion.id representa a versão da chave raiz que foi usada para agrupamento.

   Se você desejar que o Hyper Protect Crypto Services gere uma nova chave de criptografia de dados (DEK) em seu nome, também será possível passar um corpo vazio em uma solicitação de agrupamento. Sua DEK gerada, contendo o material de chave codificado em Base64, é retornada no corpo da entidade de resposta juntamente com a DEK agrupada.