Usar chaves de criptografia gerenciadas pelo cliente

Esta página descreve como usar uma chave de criptografia do Cloud Key Management Service (Cloud KMS) com o Dataflow. Com uma chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês), é possível criptografar dados em repouso com uma chave controlada por meio do Cloud KMS. É possível criar um pipeline em lote ou de streaming protegido por uma CMEK ou acessar dados protegidos por CMEK em fontes e coletores.

Também é possível usar as chaves do Cloud EKM ou do Cloud HSM. Ao usar CMEK no Dataflow, os projetos podem consumir cotas de solicitações criptográficas do Cloud KMS. Por exemplo, os pipelines do Dataflow podem consumir essas cotas quando o pipeline acessa dados protegidos por CMEK em origens e coletores ou quando o estado de um pipeline criptografado por CMEK é recuperado. Para mais informações, consulte a seção Criptografia de locais de estado do pipeline nesta página. As operações de criptografia e descriptografia que usam chaves CMEK só afetam as cotas do Cloud KMS se você usar chaves de hardware (Cloud HSM) ou externas (Cloud EKM). Para mais informações, consulte Cotas do Cloud KMS.

Com o Cloud External Key Manager (Cloud EKM), é possível usar chaves gerenciadas em um parceiro de gerenciamento de chaves externo compatível para proteger dados no Google Cloud. É possível proteger dados em repouso nos serviços de integração compatíveis com CMEK ou chamando a API Dataflow diretamente.

Para mais informações, veja opções de criptografia no Google Cloud.

Suporte e limitações

O Cloud KMS é compatível com as seguintes versões do SDK do Apache Beam:
- SDK do Java versões 2.13.0 e posteriores
- SDK do Python versões 2.13.0 e posteriores
- SDK do Go versões 2.40.0 e posteriores
O Cloud KMS com Dataflow é compatível com chaves regionais. Se você substituir a região ou a zona do worker do pipeline para usar uma região diferente da associada às chaves regionais, elas não funcionam.
A região da CMEK e a região do job do Dataflow precisam ser as mesmas.
Locais multirregionais e globais não são compatíveis. Não é possível usar chaves globais e multirregionais com pipelines do Dataflow.

Criptografia de artefatos de estado do pipeline

Os dados que um pipeline do Dataflow lê a partir de fontes de dados especificadas pelo usuário são criptografados, exceto pelas chaves de dados especificadas para transformações baseadas em chaves em jobs de streaming.

Para jobs em lote, todos os dados, incluindo chaves de dados especificadas para transformações baseadas em chaves, são sempre protegidos pela criptografia CMEK.

Para jobs de streaming criados após 7 de março de 2024, todos os dados do usuário são criptografados com CMEK.

Para jobs de streaming criados antes de 7 de março de 2024, as chaves de dados usadas em operações baseadas em chaves, como janelamento, agrupamento e mesclagem, não são protegidas pela criptografia CMEK. Para ativar essa criptografia nos jobs, drene ou cancele o job e reinicie-o.

Os metadados do job não são criptografados com chaves do Cloud KMS. Eles incluem:

dados fornecidos pelo usuário, como nomes e valores de parâmetro de jobs e grafo de pipeline;
dados gerados pelo sistema, como IDs de jobs e endereços IP de workers.

Criptografia de locais de estado do pipeline

Os seguintes locais de armazenamento são protegidos com chaves do Cloud KMS:

Discos permanentes anexados a workers do Dataflow e usados para armazenamento de estado de streaming e embaralhamento baseados em disco permanente.
Estado Embaralhamento do Dataflow para pipelines de lote.
buckets do Cloud Storage que armazenam dados temporários de exportação ou importação. O Dataflow só é compatível com chaves padrão definidas pelo usuário no nível do bucket.
Buckets do Cloud Storage usados para armazenar arquivos binários contendo código de pipeline. O Dataflow só é compatível com chaves padrão definidas pelo usuário no nível do bucket.
Buckets do Cloud Storage usados para armazenar dados de pipeline de amostra quando a amostragem de dados está ativada.
Estado do Dataflow Streaming Engine para pipelines de streaming.

Chaves externas

Use o Cloud External Key Manager (Cloud EKM) para criptografar dados no Google Cloud usando chaves externas que você gerencia.

Quando você usa uma chave do Cloud EKM, o Google não tem controle sobre a disponibilidade da sua chave gerenciada externamente. Se a chave ficar indisponível durante o período de criação do job ou do pipeline, o job ou pipeline será cancelado.

Para mais considerações ao usar chaves externas, consulte Gerenciador de chaves externo do Cloud.

Antes de começar

Verifique se você tem o SDK do Apache Beam para Java 2.13.0 ou posterior, o SDK do Apache Beam para Python 2.13.0 ou posterior ou o SDK do Apache Beam para Go 2.40.0 ou posterior.

Para mais informações, consulte Como instalar o SDK do Apache Beam.
Decida se você executará o Dataflow e o Cloud KMS no mesmo projeto do Google Cloud ou em projetos diferentes. Nesta página, usa-se a seguinte convenção:
- PROJECT_ID é o ID do projeto que está executando o Dataflow.
- PROJECT_NUMBER é o número do projeto que está executando o Dataflow.
- KMS_PROJECT_ID é o ID do projeto que está executando o Cloud KMS.
Para informações sobre os códigos de projeto e os números de projeto do Google Cloud, consulte Como identificar projetos.
No projeto do Google Cloud que você quer executar o Cloud KMS:
1. Ative a API Cloud KMS.
2. Crie um keyring e uma chave, conforme descrito em Como criar chaves simétricas. O Cloud KMS e o Dataflow são serviços regionalizados. A região da CMEK e a região do seu job do Dataflow precisam ser as mesmas. Não use chaves globais ou multirregionais com os pipelines do Dataflow. Em vez disso, use chaves regionais.

Conceder permissões para criptografar/descriptografar

Atribua o papel Cloud KMS CryptoKey Encrypter/Decrypter à conta de serviço do Dataflow. Isso concede à conta de serviço do Dataflow a permissão para criptografar e descriptografar com o CMEK especificado. Se você usa o Console do Google Cloud Platform e a página Criar job a partir de modelo, essa permissão é concedida automaticamente e esta etapa pode ser ignorada.

Use a Google Cloud CLI para atribuir o papel:
```
gcloud projects add-iam-policy-binding KMS_PROJECT_ID \
--member serviceAccount:service-PROJECT_NUMBER@dataflow-service-producer-prod.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
Substitua KMS_PROJECT_ID pelo ID do seu projeto do Google Cloud que está executando o Cloud KMS e substitua PROJECT_NUMBER pelo número do projeto do Google Cloud (não confundir com o ID do projeto) que executa os recursos do Dataflow.
Atribua o papel Cloud KMS CryptoKey Encrypter/Decrypter à conta de serviço do Compute Engine. Isso concede a ela a permissão para criptografar e descriptografar com a CMEK especificada.

Use a Google Cloud CLI para atribuir o papel:
```
gcloud projects add-iam-policy-binding KMS_PROJECT_ID \
--member serviceAccount:service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
Substitua KMS_PROJECT_ID pelo código do projeto do Google Cloud que está executando o Cloud KMS e substitua PROJECT_NUMBER pelo número do projeto (sem ser o código do projeto) do Google Cloud que executa os recursos do Compute Engine.

Criar um pipeline protegido pelo Cloud KMS

Ao criar um pipeline em lote ou de streaming, selecione uma chave do Cloud KMS para criptografar o estado dele. O estado do pipeline são os dados armazenados pelo Dataflow no armazenamento temporário.

Interface de linha de comando

Para criar um novo pipeline com estado de pipeline protegido por uma chave do Cloud KMS, adicione a sinalização relevante aos parâmetros dele. O exemplo a seguir demonstra a execução de um pipeline de contagem de palavras com o Cloud KMS.

Java

O Dataflow não é compatível com a criação de caminhos padrão do Cloud Storage para arquivos temporários ao usar uma chave do Cloud KMS. É necessário especificar gcpTempLocation.

mvn compile exec:java -Dexec.mainClass=org.apache.beam.examples.WordCount \
  -Dexec.args="--inputFile=gs://dataflow-samples/shakespeare/kinglear.txt \
               --output=gs://STORAGE_BUCKET/counts \
               --runner=DataflowRunner --project=PROJECT_ID \
               --gcpTempLocation=gs://STORAGE_BUCKET/tmp \
               --dataflowKmsKey=KMS_KEY"
  -Pdataflow-runner

Python

O Dataflow não é compatível com a criação de caminhos padrão do Cloud Storage para arquivos temporários ao usar uma chave do Cloud KMS. É necessário especificar gcpTempLocation.

python -m apache_beam.examples.wordcount \
  --input gs://dataflow-samples/shakespeare/kinglear.txt \
  --output gs://STORAGE_BUCKET/counts \
  --runner DataflowRunner \
  --region HOST_GCP_REGION \
  --project PROJECT_ID \
  --temp_location gs://STORAGE_BUCKET/tmp/ \
  --dataflow_kms_key=KMS_KEY

Go

O Dataflow não é compatível com a criação de caminhos padrão do Cloud Storage para arquivos temporários ao usar uma chave do Cloud KMS. É necessário especificar gcpTempLocation.

wordcount
  --project HOST_PROJECT_ID \
  --region HOST_GCP_REGION \
  --runner dataflow \
  --staging_location gs://STORAGE_BUCKET/staging \
  --temp_location gs://STORAGE_BUCKET/temp \
  --input gs://dataflow-samples/shakespeare/kinglear.txt \
  --output gs://STORAGE_BUCKET/output \
  --dataflow_kms_key=KMS_KEY

Console do Google Cloud

Abra a interface de monitoramento do Dataflow.
Acessar a interface da Web do Dataflow
Selecione Criar job a partir do modelo.
Na seção Criptografia, selecione Chave gerenciada pelo cliente.

As opções de criptografia na página "Criar job usando um modelo" para usar
uma chave do Google ou gerenciada pelo cliente ou chaves gerenciadas pelo Google.

Na primeira tentativa de executar um job com uma determinada chave do Cloud KMS, a conta de serviço do Compute Engine e/ou a conta de serviço do Cloud Dataflow podem não ter recebido as permissões para criptografar e descriptografar com essa chave. Nesse caso, uma mensagem de aviso será exibida solicitando que você conceda a permissão para a conta de serviço.

Solicitações para a concessão de permissões para criptografar e descriptografar as contas de serviço do Compute Engine e do Cloud Dataflow usando uma CMEK específica.

Verificar o uso da chave do Cloud KMS

É possível verificar se o pipeline usa uma chave do Cloud KMS por meio do console do Google Cloud ou da Google Cloud CLI.

Console

Abra a interface de monitoramento do Dataflow.
Acessar a interface da Web do Dataflow
Para ver os detalhes do job, selecione o job do Dataflow.
No painel lateral Informações do job, para ver o tipo de chave, consulte o campo Tipo de criptografia.
- Para o tipo de criptografia : "Chave gerenciada pelo Google"
- Para o tipo de criptografia : "Chave gerenciada pelo cliente"

CLI

Execute o comando describe usando a CLI gcloud:

gcloud dataflow jobs describe JOB_ID

Busque a linha que contém serviceKmsKeyName. Essas informações mostram que uma chave do Cloud KMS foi usada para a criptografia de estado do pipeline do Dataflow.

É possível verificar o uso da chave do Cloud KMS para criptografar fontes e coletores usando as páginas e ferramentas do Console do Google Cloud dessas fontes e coletores, incluindo Pub/Sub, Cloud Storage e BigQuery. Você também pode verificar o uso da chave do Cloud KMS visualizando os registros de auditoria do Cloud KMS.

Desativar ou destruir a chave

Se por algum motivo for necessário desativar ou destruir a chave, use o Console do Google Cloud. Essas operações desativam e destroem os jobs usando essa chave. Essa operação é permanente.

Se você estiver usando o Cloud EKM, desative ou destrua a chave no gerenciador externo.

Se você estiver usando a opção do Streaming Engine, é recomendável criar um snapshot do job antes de desativar a chave.

Remover o acesso do Dataflow à chave do Cloud KMS

É possível remover o acesso do Dataflow à chave do Cloud KMS seguindo estas etapas:

Revogue o papel Cloud KMS CryptoKey Encrypter/Decrypter da conta de serviço do Dataflow usando o Console do Google Cloud ou a CLI gcloud.
Revogue o papel Cloud KMS CryptoKey Encrypter/Decrypter da conta de serviço do Compute Engine usando o Console do Google Cloud ou a CLI gcloud.
Opcionalmente, você também pode destruir o material da versão da chave para impedir ainda mais o Dataflow e outros serviços de acessar o estado do pipeline.

É possível destruir o material da versão da chave, mas não excluir as chaves e os keyrings. Os keyrings e as chaves não têm custos faturáveis ou limitações de cota. Portanto, a existência deles não afeta os custos nem os limites de produção.

Os jobs do Dataflow validam periodicamente se a conta de serviço do Dataflow pode usar com êxito a chave do Cloud KMS fornecida. Se uma solicitação de criptografia ou descriptografia falhar, o serviço do Dataflow interromperá toda a ingestão e o processamento de dados o mais rápido possível. O Dataflow começa imediatamente a limpar os recursos do Google Cloud anexados ao job.

Usar origens e coletores protegidos com chaves do Cloud KMS

O Dataflow pode acessar origens e coletores do Google Cloud protegidos por chaves do Cloud KMS. Se você não estiver criando novos objetos, não precisará especificar a chave do Cloud KMS dessas origens e coletores. Se o pipeline do Dataflow criar novos objetos em um coletor, será preciso definir os parâmetros do pipeline. Esses parâmetros especificam as chaves do Cloud KMS para esse coletor e transmitem essa chave para os métodos apropriados do conector de E/S.

Para origens e coletores de pipeline do Dataflow que não são compatíveis com CMEKs gerenciadas pelo Cloud KMS, as configurações de CMEKs do Dataflow são irrelevantes.

Permissões de chave do Cloud KMS

Ao acessar os serviços protegidos com chaves do Cloud KMS, certifique-se de atribuir o papel Cloud KMS CryptoKey Encrypter/Decrypter a esse serviço. As contas têm o seguinte formato:

Cloud Storage: service-{project_number}@gs-project-accounts.iam.gserviceaccount.com
BigQuery: bq-{project_number}@bigquery-encryption.iam.gserviceaccount.com
Pub/Sub: service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com

Cloud Storage

Se quiser proteger os buckets temporários e de preparo especificados com os parâmetros de pipeline TempLocation/temp_location e stagingLocation/staging_location, consulte Como configurar buckets do Cloud Storage protegidos pela CMEK.

BigQuery

Java

Use o método with_kms_key() nos valores de retorno de BigQueryIO.readTableRows(), BigQueryIO.read(), BigQueryIO.writeTableRows() e BigQueryIO.write().

É possível encontrar um exemplo no repositório do GitHub do Apache Beam (em inglês).

Python

Use o argumento kms_key em BigQuerySource e BigQuerySink (links em inglês).

É possível encontrar um exemplo no repositório do GitHub do Apache Beam (em inglês).

Go

Os pedidos de veiculação do BigQuery não são compatíveis com o uso da chave KMS no Go.

Pub/Sub

O Dataflow processa o acesso a tópicos protegidos pelo CMEK usando a configuração de tópico do CMEK.

Para ler e gravar tópicos do Pub/Sub protegidos pelo CMEK, consulte as instruções de Pub/Sub para usar o CMEK.

Geração de registros de auditoria para uso da chave do Cloud KMS

O Dataflow permite que o Cloud KMS use o Cloud Audit Logs para registrar operações importantes, como criptografar e descriptografar. O Dataflow fornece o ID do job como contexto para um autor da chamada do Cloud KMS. Com esse ID, você rastreia cada instância que usa uma chave específica do Cloud KMS em um job do Dataflow.

O Cloud Audit Logs mantém registros de auditoria para cada projeto, pasta e organização do Google Cloud. Você tem várias opções para visualizar seus registros de auditoria do Cloud KMS.

O Cloud KMS grava registros de auditoria de Atividades do administrador para seus jobs do Dataflow com a criptografia CMEK. Esses registros gravam operações que modificam a configuração ou os metadados de um recurso. Não é possível desativar os registros de auditoria de Atividades do administrador.

Se ativado explicitamente, o Cloud KMS grava registros de auditoria de acesso a dados dos jobs do Dataflow com a criptografia CMEK. Os registros de auditoria de acesso a dados contêm as chamadas de API que leem a configuração ou os metadados dos recursos. Esses registros também contêm chamadas de API orientadas ao usuário que criam, modificam ou leem dados de recursos fornecidos pelo usuário. Para instruções sobre como ativar alguns ou todos os registros de auditoria de acesso a dados, acesse Como configurar registros de acesso a dados.

Preços

É possível usar as chaves de criptografia do Cloud KMS com o Dataflow em todas as regiões do Dataflow em que o Cloud KMS está disponível.

Essa integração não gera custos adicionais além das operações com chaves, que são faturadas no seu projeto do Google Cloud. Sempre que a conta de serviço do Dataflow usa sua chave do Cloud KMS, a operação é faturada com base nas operações de chave do Cloud KMS.

Para mais informações, consulte Detalhes do preço do Cloud KMS.

Solução de problemas

Use as sugestões desta seção para resolver erros.

Não é possível validar o Cloud KMS

O job pode falhar com o seguinte erro:

Workflow failed. Causes: Cloud KMS key <key-name> cannot be validated.

Para corrigir isso, verifique se você passou o caminho completo da chave. O caminho é parecido com projects/<project-id>/locations/<gcp-region>/keyRings/<key-ring-name>/cryptoKeys/<key-name>. Procure possíveis erros de digitação no caminho da chave.

Permissão de chave do Cloud KMS negada

O job pode falhar com o seguinte erro:

Workflow failed. Causes: Cloud KMS key Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource
'projects/<project-id>/locations/<gcp-region>/keyRings/<key-ring-name>/cryptoKeys/<key-name>' (or it may not exist). cannot be validated.

Para corrigir isso, verifique se o ID do projeto mencionado no caminho da chave está correto. Além disso, verifique se você tem a permissão para usar a chave.

O local da chave do Cloud KMS não corresponde ao local do job do Dataflow

O job pode falhar com o seguinte erro:

Workflow failed. Causes: Cloud KMS key projects/<project-id>/locations/<gcp-region>/keyRings/<key-ring-name>/cryptoKeys/<key-name>
can't protect resources for this job. Make sure the region of the KMS key matches the Dataflow region.

Para corrigir esse problema, se você estiver usando uma chave regional, verifique se a chave do Cloud KMS está na mesma região do job do Dataflow.