Como importar uma chave para o Cloud KMS

Neste tópico, mostramos como importar uma chave criptográfica para o Cloud HSM ou o Cloud Key Management Service.

Para mais detalhes sobre como importar chaves, incluindo limitações e restrições, consulte Importação de chaves.

Você pode concluir as etapas deste tópico em 5 a 10 minutos, sem incluir as etapas Antes de começar. Encapsular a chave manualmente aumenta a complexidade da tarefa.

Antes de começar

É recomendável criar um novo projeto para testar esse recurso, a fim de facilitar a limpeza após o teste e garantir que você tenha permissões adequadas do Cloud IAM para importar uma chave.

Antes de importar uma chave, você precisa preparar o projeto, o sistema local e a própria chave.

Como preparar o projeto

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página de seletor de projetos, selecione ou crie um projeto do Cloud.

    Acesse a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. Ative a API necessária.

    Ative a API

  5. Instale e inicialize o SDK do Cloud..
  6. O usuário que executa a importação precisa das seguintes permissões do Cloud IAM para criar keyrings, chaves e jobs de importação. Se o usuário não for o proprietário do projeto, atribua ambos os dois papéis predefinidos a seguir:

    • roles/editor
    • roles/cloudkms.importer

    Para mais informações sobre os papéis e as permissões do Cloud IAM disponíveis para o Cloud KMS, consulte Permissões e papéis.

Como preparar o sistema local

Prepare o sistema local escolhendo uma das opções a seguir. O encapsulamento automático de chaves é recomendado para a maioria dos usuários.

Como preparar a chave

  • Se você não tiver uma chave para importar, mas quiser testar chaves de importação, crie uma chave simétrica no sistema local usando o seguinte comando:

    openssl rand 32 > ${HOME}/test.bin
    

    Use esta chave somente para teste. Uma chave criada dessa maneira pode não ser apropriada para uso em produção.

  • Certifique-se de que a chave que você quer importar esteja no formato correto e converta-a, se necessário. Para mais informações, consulte Como formatar chaves para importação.

  • Se você precisar encapsular a chave manualmente, faça isso antes de continuar com os procedimentos deste tópico.

Criar a chave e o keyring de segmentação

Antes de importar uma chave, crie uma chave vazia no projeto do Google Cloud para conter o material da chave importada. Neste tópico, essa chave é chamada de chave de destino. Ao criá-la pela primeira vez, ela não tem versão, não está ativa e não pode ser usada.

A chave de segmentação existe em um keyring. Você pode criar um novo keyring ou usar um atual. Neste tópico, esse keyring é chamado de keyring de segmentação.

O local do keyring de destino determina onde a chave ficará disponível após a importação. As chaves do Cloud HSM não podem ser criadas ou importadas em alguns locais, como global. Não é possível mover uma chave para um keyring diferente.

É possível criar a chave e o keyring de destino usando a ferramenta de linha de comando gcloud ou o Console do Google Cloud.

gcloud

  1. Crie o keyring de segmentação. Se você pretende importar para uma chave do Cloud HSM, selecione um local compatível com o Cloud HSM.

    gcloud kms keyrings create key-ring-name \
      --location location
    

    Saiba mais sobre como criar keyring.

  2. Crie a chave de segmentação.

    • Defina a finalidade da chave:
      • Para uma chave simétrica, defina a finalidade como encryption.
      • Para uma chave assimétrica, defina a finalidade como asymmetric-signing ou asymmetric-encryption.
    • Impeça que uma versão inicial seja criada usando a sinalização --skip-initial-version-creation.
    • Não defina o nível de proteção.
    • Não especifique um algoritmo para a chave de segmentação. Você especifica o algoritmo da chave importada como parte da solicitação de importação.
    gcloud kms keys create key-name \
      --location location \
      --keyring key-ring-name \
      --purpose purpose \
      --skip-initial-version-creation
    

    Saiba mais sobre como criar chaves do Cloud KMS ou chaves do Cloud HSM.

Console

  1. Acesse a página Chaves criptográficas no Console do Cloud.

    Acessar a página "Chaves criptográficas"

  2. Clique em Criar keyring.

  3. No campo Nome do keyring, digite o nome do seu keyring.

  4. No menu suspenso Local, selecione um local.

  5. Clique em Criar A página de detalhes do keyring é aberta.

  6. Clique em Criar chave.

  7. Selecione Chave importada. Isso impede que uma versão de chave inicial seja criada.

  8. No campo Nome da chave, insira o nome da sua chave.

  9. Defina o nível de proteção como Software ou HSM.

  10. [Opcional] Para chaves importadas, a rotação automática é desativada por padrão. Se você ativar a rotação automática, a versão da chave importada não será mais a versão padrão da chave após uma rotação.

  11. [Opcional] No campo Rótulos, clique em Adicionar rótulo se quiser [adicionar rótulos à chave][4].

  12. Clique em Criar

Agora o keyring e a chave existem, mas a chave não contém material de chave, não tem versão e não está ativa. Em seguida, crie um job de importação.

Criar o job de importação

Um job de importação define o nível de proteção e o método de importação das chaves importadas para o Cloud HSM ou o Cloud KMS, bem como o algoritmo usado para criar a chave de encapsulamento que protege as chaves importadas durante o trânsito do seu sistema local para o projeto de destino do Google Cloud.

É possível criar um job de importação usando a ferramenta gcloud, o Console do Cloud ou a API Cloud Key Management Service.

gcloud

Use um comando como o seguinte para criar um job de importação.

gcloud kms import-jobs create import-job \
  --location location \
  --keyring key-ring-name \
  --import-method import-method \
  --protection-level protection-level

  • Use o mesmo keyring e local da chave de segmentação.
  • Defina o método de importação como rsa-oaep-3072-sha1-aes-256 ou rsa-oaep-4096-sha1-aes-256. A menos que você tenha requisitos específicos, rsa-oaep-3072-sha1-aes-256 é recomendado.
  • Defina o nível de proteção como software ou hsm.

Console

  1. Acesse a página Chaves criptográficas no Console do Cloud.

    Acessar a página "Chaves criptográficas"

  2. Clique no nome do keyring de destino.

  3. Defina o Nível de proteção como Software ou HSM. Use o mesmo nível de proteção que você definiu para a chave de destino.

  4. Clique em Criar job de importação.

  5. No campo Nome, digite o nome do job de importação.

  6. No menu suspenso Método de importação, selecione um método. A menos que você tenha requisitos específicos, recomenda-se RSA de 3072 bits.

  7. Clique em Criar

API

  1. Crie uma instância do tipo [ImportJob][importjob_api]. Forneça valores iniciais para os campos ImportJob.protectionLevel e ImportJob.importMethod.

  2. Usando a instância de ImportJob como corpo da solicitação, chame o método ImportJob.create.

Como verificar o estado do job de importação

O estado inicial de um job de importação é PENDING_GENERATION. Quando o estado é ACTIVE, você pode usá-lo para importar chaves.

Um job de importação expira após três dias. Se o job de importação tiver expirado, você precisará criar um novo.

Você pode verificar o status de um job de importação usando a ferramenta de linha de comando gcloud, o Console do Google Cloud ou a API Cloud Key Management Service.

gcloud

Quando um job de importação está ativo, você pode usá-lo para importar chaves. Talvez isso leve alguns minutos. Use este comando para verificar se o job de importação está ativo. Use o local e o keyring em que você criou o job de importação.

gcloud kms import-jobs describe import-job \
  --location location \
  --keyring key-ring-name \
  --format="value(state)"
state: ACTIVE

Console

  1. Acesse a página Chaves criptográficas no Console do Cloud.

    Acessar a página "Chaves criptográficas"

  2. Clique no nome do keyring que contém o job de importação.

  3. Clique na guia Jobs de importação na parte superior da página.

  4. O estado ficará visível em Status, ao lado do nome do job de importação.

API

Chame o método ImportJob.get e verifique o campo state. Se state for PENDING_GENERATION, o job de importação ainda está sendo criado. Verifique periodicamente o estado até que ele seja ACTIVE.

Assim que o job de importação estiver ativo, você poderá fazer uma solicitação para importar uma chave.

Como impedir a modificação de jobs de importação

O job de importação determina muitas características da chave importada, incluindo o algoritmo da chave e se uma chave importada é uma chave HSM ou uma chave de software. Você pode configurar as permissões do Cloud Identity and Access Management para impedir que os usuários criem jobs de importação ao mesmo tempo que permite que usem jobs de importação para importar chaves.

  1. Somente atribua administradores de chaves a importjobs.create.
  2. Conceda a permissão importjobs.useToImport para um job de importação específico ao operador que usará esse job para importar chaves.
  3. Ao criar o job de importação, use-o para especificar o nível de proteção e o algoritmo das chaves importadas.

Até que o job de importação expire, os usuários que têm a permissão importjobs.useToImport e não têm a permissão importjobs.create para um determinado job de importação podem importar chaves, mas não podem modificar as características do job de importação.

Importar a chave

Depois de verificar o status do job de importação, você pode fazer uma solicitação de importação.

Use sinalizações diferentes para fazer a solicitação de importação, dependendo se você quer que a ferramenta de linha de comando gcloud encapsule a chave automaticamente ou se já a encapsulou manualmente.

Independentemente de você ter encapsulado sua chave manualmente ou automaticamente, defina o algoritmo como compatível com o tipo de chave que você quer importar. Por exemplo, defina o algoritmo como google-symmetric-encryption para chaves simétricas. Uma variedade de algoritmos é compatível com chaves assimétricas.

Encapsulamento e importação automáticos de uma chave

Se você quiser usar o encapsulamento automático, use a ferramenta de linha de comando gcloud. Use um comando como o seguinte. Defina --target-key-file como o local da chave não encapsulada para encapsular e importar. Não defina -rsa-aes-wrapped-key-file.

Como opção, você pode definir a sinalização --public-key-file como o local em que já foi feito o download da chave pública. Importar um grande número de chaves impede o download da chave pública durante cada importação. Por exemplo, você pode escrever um script que fez o download da chave pública uma vez e forneceu o local ao importar cada chave.

gcloud kms keys versions import \
  --import-job import-job \
  --location location \
  --keyring key-ring-name \
  --key KEY_NAME \
  --algorithm algorithm-name \
  --target-key-file path-to-unwrapped-key-to-import

Como importar uma chave com quebra automática manual

Use as instruções nesta seção para importar uma chave que você encapsulou manualmente. Defina --rsa-aes-wrapped-key-file ao local da chave que você encapsulou manualmente. Não defina --target-key-file.

Como opção, você pode definir a sinalização --public-key-file como o local em que já foi feito o download da chave pública. Importar um grande número de chaves impede o download da chave pública durante cada importação. Por exemplo, você pode escrever um script que fez o download da chave pública uma vez e forneceu o local ao importar cada chave.

gcloud

Use um comando como o seguinte.

gcloud kms keys versions import \
  --import-job import-job \
  --location location \
  --keyring key-ring-name \
  --key KEY_NAME \
  --algorithm algorithm-name \
  --rsa-aes-wrapped-key-file path-to-wrapped-key-to-import

Para mais informações, consulte a saída do comando gcloud kms keys versions import --help.

Console

  1. Abra a página Chaves criptográficas no Console do Cloud.

  2. Clique no nome do keyring que contém o job de importação. A chave de destino é mostrada, juntamente com todas as outras chaves do keyring.

  3. Clique no nome da chave de destino e, em seguida, clique em Importar versão da chave.

  4. Selecione seu job de importação no menu suspenso Selecionar job de importação.

  5. No seletor Fazer upload da chave encapsulada, selecione a chave que você já encapsulou.

  6. Se você estiver importando uma chave assimétrica, selecione o algoritmo no menu suspenso Algoritmo. A página Importar versão da chave será semelhante a:

    Importar versão da chave

  7. Clique em Importar.

API

  1. Para o corpo da solicitação do método cryptoKeyVersions.import, defina o campo algorithm para o algoritmo da chave que está sendo importada. Esse valor não precisa corresponder ao versionTemplate do CryptoKey que está importando esta versão. O campo algorithm é do tipo CryptoKeyVersionAlgorithm.

  2. Também para o corpo da solicitação, defina o campo wrappedKeyMaterial como o material da chave que você já encapsulou.

  3. Chame o método cryptoKeyVersions.import. A resposta cryptoKeyVersions.import é do tipo CryptoKeyVersion. Quando uma chave é importada, o estado dela é ENABLED e você pode usá-la no Cloud KMS.

A solicitação de importação de chave é iniciada. Você pode monitorar o status.

Verificar o estado da chave importada

O estado inicial de uma chave importada é PENDING_IMPORT. Quando o estado é ENABLED, a chave foi importada. Se a importação falhar, o status será IMPORT_FAILED.

É possível verificar o status de uma solicitação de importação usando a ferramenta de linha de comando gcloud, o Console do Google Cloud ou a API Cloud Key Management Service.

gcloud

Use o comando versions list para verificar o estado. Use o mesmo local, keyring e chave de destino que você criou anteriormente neste tópico.

gcloud kms keys versions list \
  --keyring keyring \
  --location location \
  --key key

Console

  1. Abra a página Chaves criptográficas no Console do Cloud.

  2. Clique no nome do keyring que contém o job de importação.

  3. Clique na guia Jobs de importação na parte superior da página.

  4. O estado ficará visível em Status, ao lado do nome do job de importação.

API

Chame o método ImportJob.get e verifique o campo state. Se state for PENDING_GENERATION, o job de importação ainda está sendo criado. Verifique periodicamente o estado até que ele seja ACTIVE.

Depois que a chave é importada, o status dela muda para Ativa. Para chaves simétricas, você precisa definir a versão da chave importada como a versão principal antes de usá-la.

Chaves simétricas: definir a versão principal

Esta etapa é obrigatória ao importar chaves simétricas e não é relevante para chaves assimétricas. Uma chave assimétrica não tem uma versão principal. Use a ferramenta de linha de comando gcloud para definir a versão principal.

gcloud kms keys set-primary-version key-name --version=version-number

A seguir