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 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 do seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar 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 está executando a importação precisa das seguintes permissões do 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 papéis e permissões de 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

Verifique se o algoritmo e o comprimento da chave são compatíveis. Os algoritmos permitidos para uma chave dependem se ela é usada para criptografia simétrica, criptografia assimétrica ou assinatura assimétrica, bem como se a chave está armazenada em software ou em um HSM. Você especifica o algoritmo da chave como parte da solicitação de importação.

Separadamente, você também precisa verificar como a chave está codificada e fazer ajustes, se necessário.

Não é possível alterar o nome de uma versão de chave depois que ela é criada ou importada:

  • O nível de proteção da chave indica se a chave persiste no software, em um HSM ou em um sistema de gerenciamento de chaves externo. Não é possível mover o material da chave de um desses ambientes de armazenamento para outro. Todas as versões de uma chave têm o mesmo nível de proteção.

  • A finalidade da chave indica se as versões da chave são usadas para criptografia simétrica, criptografia assimétrica ou assinatura assimétrica. A finalidade de uma chave limita os possíveis algoritmos que podem ser usados para criar versões dessa chave. Todas as versões de uma chave têm a mesma finalidade.

Se você não tiver uma chave para importar, mas quiser validar o procedimento para importação de chaves, 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.

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

Uma chave do Cloud KMS é um objeto de contêiner que contém zero ou mais versões de chave. Cada versão de chave contém uma chave criptográfica.

Quando você importa uma chave para o Cloud KMS ou o Cloud HSM, a chave importada se torna uma nova versão de chave em uma chave atual do Cloud KMS ou do Cloud HSM. No restante deste tópico, essa chave é chamada de chave de segmentação. A chave de segmentação já precisa existir para que seja possível importar o material da chave para ela.

Importar uma versão de chave não afeta as versões existentes dessa chave. No entanto, é recomendável criar uma chave vazia ao testar a importação de chaves. Uma chave vazia não tem versão, não está ativa e não pode ser usada.

Uma chave existe em um keyring. Neste tópico, esse keyring é chamado de keyring de segmentação. O local do keyring de segmentação determina o local em que o material da chave estará disponível após a importação. Não é possível criar ou importar chaves do Cloud HSM em alguns locais. Depois que uma chave é criada, ela não pode ser movida para um keyring ou local diferente.

Siga estas etapas para criar uma chave vazia em um novo keyring usando a ferramenta de linha de comando gcloud ou o Console do Google Cloud.

IU da Web

  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, as novas versões das chaves serão geradas no Cloud KMS, e a versão importada da chave 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.

Linha de comando

Para usar o Cloud KMS na linha de comando, primeiro instale ou faça upgrade para a versão mais recente do SDK do Cloud.

  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.
    • [Opcional] Não especifique uma política de rotação. Se você ativar a rotação automática, as novas versões das chaves serão geradas no Cloud KMS, e a versão importada da chave não será mais a versão padrão da chave após uma rotaçã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.

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 as características das chaves importadas, incluindo propriedades que não podem ser alteradas após a importação da chave.

O nível de proteção define se as chaves resultantes desse job de importação residirão no software, em um HSM ou em um sistema de gerenciamento de chaves externo. O nível de proteção não pode ser alterado depois que a chave for importada.

O método de importação define o algoritmo usado para criar a chave de encapsulamento que protege as chaves importadas durante a transmissão do seu sistema local para o projeto de destino do Google Cloud. É possível escolher uma chave RSA de 3072 bits ou 4096 bits. A menos que você tenha requisitos específicos, é recomendável usar a chave de encapsulamento de 3072 bits.

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

IU da Web

  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. Na lista suspensa Método de importação, defina o método de importação como RSA de 3072 bits ou RSA de 4096 bits.

  7. Clique em Criar.

Linha de comando

Para usar o Cloud KMS na linha de comando, primeiro instale ou faça upgrade para a versão mais recente do SDK do Cloud.

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 nível de proteção como software ou hsm.
  • Defina o método de importação como rsa-oaep-3072-sha1-aes-256 ou rsa-oaep-4096-sha1-aes-256.

API

Estes exemplos usam curl como um cliente HTTP para demonstrar o uso da API. Para mais informações sobre controle de acesso, consulte Como acessar a API Cloud KMS.

  1. Crie uma instância do tipo ImportJob e especifique os valores dos 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.

IU da Web

  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.

Linha de comando

Para usar o Cloud KMS na linha de comando, primeiro instale ou faça upgrade para a versão mais recente do SDK do Cloud.

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

API

Estes exemplos usam curl como um cliente HTTP para demonstrar o uso da API. Para mais informações sobre controle de acesso, consulte Como acessar a API Cloud KMS.

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. É possível configurar as permissões de gerenciamento de identidade e acesso para impedir que os usuários criem jobs de importação e permitir 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ê encapsular a chave de maneira manual ou automática, é necessário definir o algoritmo como um algoritmo compatível que corresponda ao comprimento da chave real a ser importada e que especifique a finalidade da chave.

  • As chaves com a finalidade ENCRYPT_DECRYPT usam o algoritmo google-symmetric-encryption e têm um comprimento de 32.

  • As chaves com finalidade ASYMMETRIC_ENCRYPT ou ASYMMETRIC_SIGN são compatíveis com diversos algoritmos e comprimentos.

    Não é possível alterar a finalidade de uma chave depois que ela é criada. No entanto, as versões de chave subsequentes podem ser criadas com comprimentos diferentes em relação à versão inicial da chave.

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

A chave é encapsulada pela chave de encapsulamento associada ao job de importação, transmitida ao Google Cloud e importada como uma nova versão de chave na chave de segmentação.

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.

IU da Web

  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 tarefa 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.

Linha de comando

Para usar o Cloud KMS na linha de comando, primeiro instale ou faça upgrade para a versão mais recente do SDK do Cloud.

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.

API

Estes exemplos usam curl como um cliente HTTP para demonstrar o uso da API. Para mais informações sobre controle de acesso, consulte Como acessar a API Cloud KMS.

  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.

IU da Web

  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.

Linha de comando

Para usar o Cloud KMS na linha de comando, primeiro instale ou faça upgrade para a versão mais recente do SDK do Cloud.

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

API

Estes exemplos usam curl como um cliente HTTP para demonstrar o uso da API. Para mais informações sobre controle de acesso, consulte Como acessar a API Cloud KMS.

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