Importando chaves raiz

É possível usar o IBM® Key Protect for IBM Cloud® para proteger e gerenciar suas chaves raiz existentes importando-as.

Chaves raiz são chaves simétricas de quebra de chaves usadas para proteger a segurança dos dados criptografados na nuvem. Para obter mais informações sobre como importar chaves raiz para o Key Protect, consulte Trazendo suas chaves de criptografia para a nuvem.

Planeje antecipadamente a importação de chaves revisando suas opções de criação e criptografia do material de chave. Para maior segurança, é possível ativar a importação segura do material de chave usando um token de importação para criptografar seu material de chave antes de trazê-lo para a nuvem.

Importando chaves raiz com o console

Depois de criar uma instância do serviço, conclua as etapas a seguir para importar uma chave com o console da IBM Cloud.

Se você ativar as configurações de autorização dupla para a sua instância do Key Protect, tenha em mente que qualquer chave que você incluir no serviço requererá uma autorização de dois usuários para excluir chaves.

Efetue login no console do IBM Cloud.
Acesse Menu > Lista de recursos para visualizar uma lista de seus recursos.
Em sua lista de recursos do IBM Cloud, selecione a sua instância provisionada do Key Protect.
Para importar uma chave, clique em “Adicionar ” e selecione a janela “Importar chave ”.

Especifique os detalhes da chave:

Descreve as configurações da chave Import your own.
Configuração	Descrição
Tipo de chave	O tipo de chave que você gostaria de gerenciar no Key Protect. Selecione o botão Chave raiz.
Nome	Um alias legível por humanos para fácil identificação de sua chave. O comprimento deve estar entre 2 e 90 caracteres (inclusive). Para proteger sua privacidade, assegure-se de que o nome da chave não contenha informações pessoalmente identificáveis (PII), como seu nome ou local. Observe que os nomes de chaves não precisam ser exclusivos.
Material de chave	O material da chave codificada em Base64, como uma chave de quebra de chave existente, que você deseja armazenar e gerenciar no serviço. Para obter mais informações, confira Codificando em Base64 o seu material da chave. Certifique-se de que o material de chave tenha 16, 24 ou 32 bytes de comprimento e corresponda a 128, 192 ou 256 bits de comprimento. A chave também deve ser codificada em base64.
Descrição da chave	Opcional. Descrições são uma maneira útil de adicionar informações sobre uma chave (por exemplo, uma frase descrevendo seu propósito) de uma maneira que não é possível usar um alias ou seu nome. Essa descrição deve ter no mínimo dois caracteres e no máximo 240 e não pode ser alterada posteriormente. Para proteger sua privacidade, não utilize dados pessoais, como seu nome ou localização, como descrição para sua chave.
Alias da chave	Opcional. Aliases de chave são maneiras de descrever uma chave que permitem que ela seja identificada e agrupada além dos limites de um nome de exibição. As chaves podem ter até cinco aliases.
Conjunto de chaves	Opcional. Conjuntos de chaves são agrupamentos de chaves que permitem que esses agrupamentos sejam gerenciados de forma independente conforme necessário. Cada chave deve ser uma parte de um conjunto de chaves. Se nenhum conjunto de chaves for selecionado, as chaves serão colocadas no conjunto de chaves `default`. Observe que, para poder colocar a chave que está sendo criada em um conjunto de chaves, você deve ter a função de Gerenciador em relação a esse conjunto de chaves. Para obter mais informações sobre funções, confira Gerenciando o acesso de usuário.

Quando terminar de preencher os detalhes da chave, clique em “Adicionar” para confirmar.

Se você for o administrador de um chaveiro específico, poderá adicionar uma chave diretamente no painel “Chaveiros ”. No menu de ações do chaveiro (⋯), clique em “Adicionar nova chave ”. É exibido o mesmo painel que aparece quando você clica em “Adicionar” na página “Chaves”, mas o campo “Chaveiro” já vem preenchido com o nome do chaveiro selecionado.

Se você precisar importar e gerenciar chaves raiz de forma consistente entre contas ou ambientes, poderá automatizar isso com o módulo Key Protect Key. Para obter uma configuração completa que também provisiona a instância Key Protect e os chaveiros, consulte o módulo Key Protect com tudo incluído. Para obter uma visão geral, consulte Terraform IBM Modules.

Importando chaves raiz com a API

Importe chaves simétricas para o Key Protect fazendo uma chamada POST para o terminal a seguir.

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

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

Chame a API Key Protect com o comando curl a seguir.

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.key+json" \
    -d '{
            "metadata": {
                "collectionType": "application/vnd.ibm.kms.key+json",
                "collectionTotal": 1
            },
            "resources": [
                {
                    "type": "application/vnd.ibm.kms.key+json",
                    "name": "<key_name>",
                    "aliases": [alias_list],
                    "description": "<key_description>",
                    "expirationDate": "<expiration_date>",
                    "payload": "<key_material>",
                    "extractable": <key_type>
                }
            ]
        }'

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

Descreve as variáveis necessárias para adicionar uma chave raiz com a API do Key Protect
Variável	Descrição
região	Obrigatório. A abreviação da região, como `us-south` ou `eu-gb`, que representa a área geográfica onde sua instância do Key Protect está localizada. Para obter mais informações, consulte “ Pontos de conexão de serviço regionais ”.
IAM_token	Obrigatório. Seu token de acesso do IBM Cloud. Inclua o conteúdo completo do token do IAM, incluindo o valor Bearer, na solicitação curl. Para obter mais informações, consulte “Como recuperar um token de acesso ”.
instance_ID	Obrigatório. O identificador exclusivo que é designado para sua instância de serviço Key Protect. Para obter mais informações, consulte “Como recuperar um ID de instância ”.
correlation_ID	O identificador exclusivo que é usado para rastrear e correlacionar transações.
return_preference	Um cabeçalho que altera o comportamento do servidor para operações POST e DELETE. Ao configurar a variável return_preference como return=minimal, o serviço retorna apenas os metadados da chave, como o nome da chave e o valor de ID, na resposta entity-body. Ao configurar a variável como return=representation, o serviço retorna o material de chave e os metadados da chave.
key_name	Obrigatório. Um nome exclusivo legível para fácil identificação da sua chave. Para proteger a sua privacidade, não armazene os seus dados pessoais como metadados para a sua chave.
alias_list	Opcional. Um ou mais aliases exclusivos e legíveis designados à sua chave. Importante: para proteger sua privacidade, não armazene seus dados pessoais como metadados para sua chave. Cada alias deve ser alfanumérico, distinguir maiúsculas de minúsculas e não pode conter espaços ou caracteres especiais, exceto - ou _. O alias não pode ser um UUID e não deve ser um nome reservado do Key Protect: allowed_ip, key, keys, metadata, policy, policies, registration, registrations, ring, rings, rotate, wrap, unwrap, rewrap, version, versions.
key_description	Opcional. Uma descrição estendida de sua chave. Para proteger a sua privacidade, não armazene os seus dados pessoais como metadados para a sua chave.
expiration_date	Opcional. A data e hora em que a chave expira no sistema, no formato RFC 3339 (`YYYY-MM-DD HH:MM:SS.SS`, por exemplo `2019-10-12T07:20:50.52Z`). A chave executará a transição para o estado desativado dentro de uma hora após a data de expiração da chave. Se o atributo expirationDate for omitido, a chave não expirará.
key_material	Obrigatório. O material de chave codificado em base64, uma chave de agrupamento de chave existente que você deseja armazenar e gerenciar no serviço. Para mais informações, acesse Base64 codificação do seu material de chave. Assegure-se de que o material de chave atenda aos seguintes requisitos: Uma chave padrão pode ter até 7.500 bytes de tamanho. A chave deve ser codificada em Base64.
key_type	Um valor booleano determina se o material de chave pode sair do serviço. Quando você define o atributo “extractable” como “ `false` ”, o serviço designa a chave como uma chave raiz que você pode usar para operações de “wrap” ou “unwrap”.

Para proteger a confidencialidade de seus dados pessoais, evite inserir informações pessoalmente identificáveis (PII), como seu nome ou local, ao incluir chaves no serviço.

Uma resposta POST api/v2/keys bem-sucedida retorna o valor de ID para a sua chave, junto com outros metadados. O ID é um identificador exclusivo que é designado para sua chave e é usado para chamadas subsequentes para a API do Key Protect.

Opcional: verifique se a chave foi incluída executando a chamada a seguir para procurar as chaves em sua instância do Key Protect.

$ 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>"

Codificando em Base64 o seu material da chave

Ao importar uma chave raiz existente, é necessário incluir o material de chave criptografada que você deseja armazenar e gerenciar no serviço.

Usando o OpenSSL para criptografar o material da chave existente

Use este processo para criptografar os conteúdos de um material de chave em um arquivo.

Faça download e instale OpenSSL.
Codifique em Base64 a sua sequência de material da chave executando o comando a seguir:
```
openssl base64 -in <infile> -out <outfile>
```
Substitua as variáveis na solicitação de exemplo de acordo com a tabela a seguir.

Descreve as variáveis que são necessárias para codificar seu material de chave em base64.
Variável	Descrição
infile	O nome do arquivo no qual a sua sequência de material da chave reside. Assegure-se de que a chave tenha 16, 24 ou 32 bytes de comprimento, correspondentes a 128, 192 ou 256 bits de comprimento. A chave deve ser codificada em Base64.
outfile	O nome do arquivo no qual o seu material da chave codificada em Base64 será criado uma vez que o comando tenha sido executado.

Caso queira enviar o material codificado em base64 diretamente para a linha de comandos, em vez de usar um arquivo, emita openssl enc -base64 <<< '<key_material_string>', em que key_material_string é a entrada do material da chave para a chave importada.

Usando o OpenSSL para criar e codificar o novo material da chave

Use este processo para criar um material de chave aleatório, codificado em base64 e com um comprimento de byte específico. A recomendação são 32 bytes (256 bits).

Faça download e instale OpenSSL.
Codifique em Base64 a sua sequência de material da chave executando o comando a seguir:
```
openssl rand -base64 <byte_length>
```
Substitua a variável na solicitação de exemplo de acordo com a tabela a seguir.

Descreve a variável que é necessária para criar e codificar o novo material de chave.
Variável	Descrição
byte_length	O comprimento da chave, medido em bytes. Os comprimentos de bytes aceitáveis são 16, 24 ou 32 bytes, correspondentes a 128, 192 ou 256 bits de comprimento. A chave deve ser codificada em Base64.

Exemplos de criação de material da chave

openssl rand -base64 16 gerará um material da chave de 128 bits.
openssl rand -base64 24 gerará um material da chave de 192 bits.
openssl rand -base64 32 gerará um material da chave de 256 bits.

O que vem a seguir

Para descobrir mais sobre como proteger chaves com criptografia de envelope, consulte Chaves de quebra.
Para saber mais sobre como gerenciar suas chaves programaticamente, consulte a documentação de referência da API do Key Protect.