Migrar chaves externas

Neste documento, mostramos como migrar suas chaves do Cloud EKM entre os níveis de proteção externo pela Internet (EXTERNAL) e externo pela VPC (EXTERNAL_VPC). A migração de chaves externas só é compatível com a CLI gcloud e a API Cloud KMS.

Casos de uso de migração

Quando uma chave tem o nível de proteção EXTERNAL ou EXTERNAL_VPC, é possível fazer o seguinte:

  • Faça a rotação da chave, criando uma nova versão com um nível de proteção do Cloud EKM diferente da chave principal. Por exemplo, você pode girar uma chave no nível de proteção EXTERNAL para criar uma nova versão de chave no nível de proteção EXTERNAL_VPC.
  • Atualize uma versão de chave para usar um nível de proteção do Cloud EKM diferente para o mesmo material de chave. Por exemplo, é possível atualizar uma versão de chave no nível de proteção EXTERNAL para usar o mesmo material e o mesmo recurso de versão de chave com o nível de proteção EXTERNAL_VPC.
  • Rotacione uma chave EXTERNAL_VPC ou atualize uma versão de chave EXTERNAL_VPC para usar um EkmConnection diferente da chave principal.

Migrar uma versão de chave entre os dois níveis de proteção do Cloud EKM permite mudar a forma de acessar o material de chave externa sem precisar reconfigurar os aplicativos ou recriptografar os dados, e sem tempo de inatividade. A chave migrada usa o mesmo material e identificador de recurso.

Ao migrar uma versão de chave do nível de proteção EXTERNAL para o EXTERNAL_VPC, você associa um recurso EkmConnection à versão da chave e adiciona o ekmConnectionKeyPath. Ao migrar uma versão de chave do nível de proteção EXTERNAL_VPC para EXTERNAL, você adiciona um externalKeyUri para substituir EkmConnection e ekmConnectionKeyPath.

Se uma versão de chave tiver um EkmConnection associado a ela, essa conexão será usada em todas as operações de versão de chave, mesmo que a chave principal tenha um EkmConnection diferente.

Migrar para externo via VPC

A migração do nível de proteção externa pela Internet para o nível externa pela VPC melhora a confiabilidade das chaves do Cloud EKM. Você aproveita os benefícios das redes de nuvem privada virtual (VPC), incluindo isolamento robusto e melhor suporte operacional.

Também é possível migrar entre diferentes configurações de VPC. Por exemplo, para fazer upgrade do uso da VPC com a Interconexão por parceiro para o uso da VPC com a Interconexão dedicada.

Antes de começar

Antes de migrar chaves do Cloud EKM, você precisa ter o seguinte:

  1. Um projeto do Google Cloud com o faturamento e a API Cloud KMS ativados.

  2. Para ter a permissão necessária para migrar chaves externas, peça ao administrador que conceda a você o papel do IAM Administrador do Cloud KMS (roles/cloudkms.admin) no projeto ou em um recurso pai. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Esse papel predefinido contém a permissão cloudkms.cryptoKeys.update, necessária para migrar chaves externas.

    Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

  3. Se você estiver migrando para o nível de proteção externo pela Internet (EXTERNAL), configure o Cloud EKM pela Internet, se ainda não tiver feito isso.
  4. Se você estiver migrando para o nível de proteção externa sobre VPC (EXTERNAL_VPC) ou para uma nova rede VPC, crie uma conexão do EKM, se ainda não tiver feito isso.

Criar uma nova versão de chave externa gerenciada manualmente via VPC

gcloud

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

Para criar uma nova versão de chave externa sobre VPC em uma chave do Cloud EKM existente, use o comando kms keys versions create com as flags --protection-level, --crypto-key-backend e --ekm-connection-key-path:

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

Substitua:

  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EKM_CONNECTION_PATH: o identificador do recurso da conexão do EKM que você quer usar para a nova versão da chave. Por exemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH: o caminho para a nova versão da chave externa da sua conexão do EKM. Por exemplo, v0/path/to/my/key.

Se a chave principal for

Se a chave for de criptografia simétrica e você quiser definir a nova versão como a principal, adicione a flag --primary.

Para informações sobre todas as sinalizações e valores possíveis, execute o comando com a sinalização --help.

REST

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.

Para criar uma nova versão de chave externa por VPC em uma chave do Cloud EKM existente, crie uma versão de chave chamando o método CryptoKeyVersions.create.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID: o identificador do projeto que contém a chave que você quer girar.
  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EKM_CONNECTION_PATH: o identificador do recurso da conexão do EKM que você quer usar para a nova versão da chave. Por exemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH: o caminho para a nova versão da chave externa da sua conexão do EKM. Por exemplo, v0/path/to/my/key.

Esse comando cria uma nova versão de chave, mas não a define como a principal.

Para definir sua nova versão de chave como principal, consulte Como configurar uma versão atual como principal.

Criar uma nova versão de chave externa pela Internet

gcloud

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

Para criar uma versão de chave externa pela Internet em uma chave do Cloud EKM, use o comando kms keys versions create com as flags --protection-level e --external-key-uri:

gcloud kms keys versions create \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

Substitua:

  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EXTERNAL_KEY_URI: o URI da nova versão da chave externa.

Se a chave for de criptografia simétrica e você quiser tornar a nova versão a principal, adicione a flag --primary.

Para informações sobre todas as sinalizações e valores possíveis, execute o comando com a sinalização --help.

REST

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.

Para criar uma nova versão de chave externa pela Internet em uma chave do Cloud EKM, chame o método CryptoKeyVersions.create.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \
    --request "POST" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID: o identificador do projeto que contém a chave que você quer girar.
  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EXTERNAL_KEY_URI: o URI da nova versão da chave externa.

Esse comando cria uma nova versão de chave, mas não a define como a principal.

Para definir sua nova versão de chave como principal, consulte Como configurar uma versão atual como principal.

Atualizar uma versão da chave para usar o modo de proteção externa por VPC

gcloud

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

Para atualizar uma versão de chave external para o nível de proteção external-vpc, use o comando kms keys versions update com as flags --protection-level, --crypto-key-backend e --ekm-connection-key-path:

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external-vpc" \
    --crypto-key-backend EKM_CONNECTION_PATH \
    --ekm-connection-key-path EXTERNAL_KEY_PATH

Substitua:

  • KEY_VERSION: o número da versão da chave que você quer migrar. Por exemplo, 3.
  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EKM_CONNECTION_PATH: o identificador do recurso da conexão do EKM que você quer usar para a versão da chave. Por exemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH: o novo caminho para o material de chave externa existente da sua conexão do EKM. Por exemplo, v0/path/to/my/key. A conexão do EKM e o caminho da chave precisam apontar para o mesmo material da chave que o URI atual.

Para informações sobre todas as sinalizações e valores possíveis, execute o comando com a sinalização --help.

REST

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.

Para atualizar uma versão de chave external para o nível de proteção external-vpc, chame o método CryptoKeyVersions.patch.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL_VPC",
            "externalProtectionLevelOptions": {
              "ekmConnectionKeyPath": "EXTERNAL_KEY_PATH",
              "ekmConnectionBackendOverride": "EKM_CONNECTION_PATH"
              },
            }'
  • PROJECT_ID: o identificador do projeto que contém a chave que você quer migrar.
  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EKM_CONNECTION_PATH: o identificador do recurso da conexão do EKM que você quer usar para a versão da chave. Por exemplo, projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
  • EXTERNAL_KEY_PATH: o novo caminho para o material de chave externa existente da sua conexão do EKM. Por exemplo, v0/path/to/my/key. A conexão do EKM e o caminho da chave precisam apontar para o mesmo material da chave que o URI atual.

Atualizar uma versão de chave para usar o modo de proteção externa pela Internet

gcloud

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

Para atualizar uma versão de chave external-vpc para o nível de proteção external, use o comando kms keys versions update com as flags --protection-level e --external-key-uri:

gcloud kms keys versions update KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --protection-level "external" \
    --external-key-uri EXTERNAL_KEY_URI

Substitua:

  • KEY_VERSION: o número da versão da chave que você quer migrar. Por exemplo, 3.
  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EXTERNAL_KEY_URI: o novo URI para o material de chave externa existente no EKM. O URI precisa apontar para o mesmo material de chave que a conexão EKM e a chave externa atuais.

Para informações sobre todas as sinalizações e valores possíveis, execute o comando com a sinalização --help.

REST

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.

Para atualizar uma versão de chave external-vpc para o nível de proteção external, chame o método CryptoKeyVersions.patch.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION?updateMask=protectionLevel,externalProtectionLevelOptions" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{
            "protectionLevel": "EXTERNAL",
            "externalProtectionLevelOptions": {
              "externalKeyUri": "EXTERNAL_KEY_URI",
              },
            }'
  • PROJECT_ID: o identificador do projeto que contém a chave que você quer migrar.
  • KEY_NAME: o nome da chave;
  • KEY_RING: o nome do keyring que contém a chave.
  • LOCATION: o local do Cloud KMS do keyring.
  • EXTERNAL_KEY_URI: o novo URI para o material de chave externa existente no EKM. O URI precisa apontar para o mesmo material de chave que a conexão EKM e a chave externa atuais.