Como importar uma chave encapsulada para o Cloud KMS

Este tópico mostra como encapsular manualmente a chave criada a partir de uma fonte externa e depois importá-la para o Cloud KMS.

Se você quiser que o Cloud KMS encapsule a chave de forma automática em vez de manualmente, consulte Como importar uma chave bruta.

Introdução

O Cloud KMS permite importar chaves criptográficas fornecidas pelo usuário. Por exemplo, é possível ter chaves que você usa em um ambiente com várias nuvens e/ou no local, com um armazenamento de chaves diferente do Cloud KMS. Outra opção é importar essas chaves caso você queira usar o material de chave atual com o Cloud KMS.

Para importar as chaves, primeiro crie um job de importação, que é um recurso temporário usado apenas com esse fim. Quando você cria um job de importação, o Cloud KMS gera uma "chave de encapsulamento", que é um par de chaves públicas/privadas. A parte de chave pública da chave de encapsulamento é usada para criptografar (processo também conhecido como encapsulamento) o material de chave preexistente para protegê-lo durante o processo de importação. Depois que o material de chave é encapsulado, ele pode ser importado para uma nova chave ou versão de chave. A parte de chave privada da chave de encapsulamento fica disponível apenas no Cloud HSM. Se você restringi-la ao Cloud HSM, o Google não poderá desencapsular o material de chave fora dele.

É possível usar o mesmo job de importação repetidamente para encapsular várias chaves a serem importadas. Os jobs de importação expiram três dias após a criação. Depois de expirados, o Cloud KMS não poderá mais importar ou desencapsular qualquer material de chave que tenha sido encapsulado pela chave pública do job de importação.

Antes de começar

  1. Neste tópico, presume-se que você já esteja usando o Cloud KMS. Caso ainda não esteja, siga as etapas descritas no guia de início rápido do Cloud KMS.
  2. Crie um keyring em uma região que seja compatível com o Cloud HSM, conforme descrito em Como criar keyrings.
  3. Crie uma chave com nível de proteção HSM, conforme descrito em Como criar chaves.
  4. Configure as permissões do Cloud Identity e Access Management para o keyring e a chave.

Fluxo de importação de chaves

Para importar uma chave, siga estas etapas:

  1. Crie um job de importação
  2. Recupere a chave de encapsulamento do job de importação.
  3. Encapsule a chave a ser importada.
  4. Faça uma solicitação de importação.

Criar um job de importação

Jobs de importação são recursos ImportJob. Ao criar um job de importação, você precisa especificar o nível de proteção e o ImportMethod que será usado para incorporar a chave.

Para criar um job de importação:

gcloud

gcloud beta kms import-jobs create \
--location LOCATION \
--keyring KEYRING_NAME \
IMPORTJOB_NAME \
--import-method IMPORT_METHOD \
--protection-level hsm

Substitua IMPORT_METHOD por rsa-oaep-3072-sha1-aes-256 ou rsa-oaep-4096-sha1-aes-256.

API

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

  2. Use a instância do ImportJob como corpo da solicitação para chamar o método ImportJob.create.

Verificar o estado do job de importação

O estado inicial de um job de importação é PENDING_GENERATION. Quando ele muda para ACTIVE, significa que o job está pronto para uso.

Para verificar o estado:

gcloud

Use o comando gcloud beta kms import-jobs describe para verificar o estado.

gcloud beta kms import-jobs \
describe IMPORTJOB_NAME \
--location LOCATION \
--keyring KEYRING_NAME

API

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

Recuperar a chave de encapsulamento

Para recuperar a chave de encapsulamento:

gcloud

Execute o comando gcloud beta kms import-jobs describe.

gcloud beta kms import-jobs \
describe IMPORTJOB_NAME \
--location LOCATION \
--keyring KEYRING_NAME

Se o estado do job de importação mudar para ACTIVE, o campo pem no campo public_key será a chave pública codificada no formato PEM.

name: projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEYRING_NAME]/importJobs/[IMPORTJOB_NAME]
createTime: '2019-03-21T17:10:10.864211749Z'
generateTime: '2019-03-21T17:10:10.864211749Z'
importMethod: [IMPORT_METHOD]
protectionLevel: [PROTECTION_LEVEL]
state: ACTIVE
public_key:
  pem: -----BEGIN PUBLIC KEY-----
[PUBLIC_KEY]
-----END PUBLIC KEY-----

API

  1. Chame o método ImportJob.get.

  2. Recupere a chave pública por meio do campo publicKey da resposta ImportJob.get. Esse valor é do tipo WrappingPublicKey. O campo pem do tipo WrappingPublicKey é a chave pública codificada no formato Privacy Enhanced Mail (PEM).

Para mais informações sobre o formato de codificação PEM, consulte as seções RFC 7468 (em inglês) referentes a Considerações gerais e Codificação textual de informações de chave pública do assunto.

Encapsular o material de chave

Encapsule o material de chave preexistente usando a chave pública do job de importação, que é o valor PEM recuperado na etapa anterior.

Caso o HSM de origem (ou outro provedor de chaves, se você não estiver usando o HSM) aceite exportar uma chave para um PKCS #11 com o mecanismo de encapsulamento de chaves AES do RSA (CKM_RSA_AES_KEY_WRAP), use o recurso de exportação do HSM e a chave pública do job de importação para criar um arquivo PKCS #11.

Caso o HSM de origem (ou outro provedor de chaves, se você não estiver usando o HSM) não aceite PKCS #11 usando o mecanismo de encapsulamento de chaves AES do RSA, será necessário criar manualmente um arquivo PKCS #11 usando a chave pública do job de importação. Para ver um exemplo de como fazer isso usando o OpenSSL, consulte Como encapsular uma chave usando o OpenSSL no Linux.

Estes são os itens resultantes do encapsulamento da chave:

  • A chave AES efêmera encapsulada, que é usada para encapsular a chave a ser importada.
  • A chave de segmentação encapsulada, que é para a chave a ser importada.

Fazer uma solicitação para importar a chave

No Cloud KMS, o material de chave é desencapsulado e armazenado na versão de chave resultante quando você o inclui, encapsulado, em uma solicitação para criar uma nova chave ou versão.

Para fazer uma solicitação de importação que inclua a chave encapsulada:

gcloud

Importe a chave usando o comando gcloud beta kms keys import.

gcloud beta kms keys import \
--location LOCATION \
--keyring KEYRING_NAME \
--key KEY_NAME \
--import-job IMPORTJOB_NAME \
--algorithm ALGORITHM_NAME \
--rsa-aes-wrapped-key-file=PATH_TO_WRAPPED_RSA_AES_KEY

Esta é a resposta do comando gcloud beta kms keys import.

algorithm: [ALGORITHM]
createTime: '2019-03-21T17:10:10.864211749Z'
generateTime: '2019-03-21T17:10:10.864211749Z'
name: projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEYRING_NAME]/cryptoKeys/[KEY_NAME]/cryptoKeyVersions/1
protectionLevel: [PROTECTION_LEVEL]
state: ENABLED

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 importado. Esse valor não precisa corresponder ao versionTemplate da CryptoKey que está importando essa versão. O campo algorithm é do tipo CryptoKeyVersionAlgorithm.

  2. Também para o corpo da solicitação, defina o campo wrappedKeyMaterial para o material da chave que você encapsulou na etapa Encapsular o material da chave.

  3. Chame o método cryptoKeyVersions.import. A resposta cryptoKeyVersions.import é do tipo CryptoKeyVersion. Quando uma chave é importada corretamente, ela tem o estado ENABLED e pode ser usada com o Cloud KMS.

Verificar o estado da chave importada

O estado inicial de uma chave importada é PENDING_IMPORT. Quando o estado for ENABLED, a chave importada estará pronta para o uso.

Para verificar o estado:

gcloud

Use o comando gcloud kms keys versions describe para verificar o estado.

gcloud kms keys versions \
describe VERSION \
--location LOCATION \
--keyring KEYRING_NAME \
--key KEY_NAME

API

Chame o método CryptoKeyVersions.get e verifique o campo state. Se state for PENDING_IMPORT, isso significa que a chave ainda está sendo importada. Verifique periodicamente o estado até que ele fique ENABLED.

Quando uma chave é importada com sucesso, ela tem o estado ENABLED e pode ser usada com o Cloud KMS.

Verificar a chave importada

Depois que a chave for importada, verifique se ela contém o material de chave e se é protegida por HSM.

Chaves simétricas

Use o atributo de chave Extended Key Checksum Value (EKCV) para verificar o material de chave. Esse valor é calculado seguindo a seção 2 do RFC 5869 (em inglês). O valor é derivado usando a Função de derivação de chaves com HMAC (HKDF, na sigla em inglês) baseada em SHA-256 com 32 arquivos de zero bytes como sal e expandindo com o valor de verificação de chaves de string fixa como informação. Esse valor pode ser recuperado analisando o atestado da chave. Para mais informações sobre como verificar o atributo EKCV da chave, consulte Como verificar as propriedades da chave.

Chaves assimétricas

Quando você faz a solicitação de importação para uma chave assimétrica, inclui a chave privada encapsulada. A chave privada contém informações suficientes para o Cloud KMS derivar a chave pública. Depois que a chave for importada, recupere a chave pública e verifique se ela corresponde à chave pública armazenada localmente. Para mais informações sobre como verificar o atributo da chave pública, consulte Para verificar a chave pública.

A verificação do EKCV também pode ser usada para chaves assimétricas. Nesse caso, o valor é o resumo de SHA-256 da chave pública codificada em DER. É possível recuperar esse valor analisando o atestado da chave. Para mais informações sobre como verificar o atributo da chave de EKCV, consulte Para verificar propriedades principais.

Para mais informações sobre como atestar chaves importadas, consulte Como verificar atestados.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…