Chaves do Cloud KMS gerenciadas pelo cliente

Observação: esse recurso pode não estar disponível ao usar reservas criadas com determinadas edições do BigQuery. Para mais informações sobre quais recursos estão ativados em cada edição, consulte Introdução às edições do BigQuery.

Por padrão, o BigQuery criptografa seu conteúdo armazenado em repouso. O BigQuery lida e gerencia essa criptografia padrão para você sem nenhuma ação adicional da sua parte. Primeiro, os dados de uma tabela do BigQuery são criptografados usando uma chave de criptografia de dados. Em seguida, essas chaves de criptografia de dados são criptografadas com chaves de criptografia de chaves, o que é conhecido como criptografia de envelope. As chaves de criptografia de chaves não criptografam diretamente seus dados, mas são usadas para criptografar as chaves de criptografia de dados que o Google usa para criptografar seus dados.

Para você controlar a criptografia, use as chaves de criptografia gerenciadas pelo cliente (CMEK) para o BigQuery. Em vez de o Google gerenciar as chaves de criptografia de chaves que protegem seus dados, você controla e gerencia as chaves de criptografia de chaves no Cloud KMS. Este documento fornece detalhes sobre essa técnica.

Saiba mais sobre opções de criptografia no Google Cloud. Para informações específicas sobre CMEK, incluindo as vantagens e limitações, consulte Chaves de criptografia gerenciadas pelo cliente.

Antes de começar

• Todos os recursos de dados que residem no armazenamento gerenciado do BigQuery são compatíveis com CMEK. No entanto, se você também estiver consultando dados armazenados em uma fonte de dados externa, como o Cloud Storage, que tem dados criptografados por CMEK, a criptografia de dados é gerenciada pelo Cloud Storage.. Por exemplo, as tabelas do BigLake são compatíveis com dados criptografados com CMEK no Cloud Storage.

  As tabelas do BigLake e do BigQuery não são compatíveis com chaves de criptografia fornecidas pelo cliente (CSEK, na sigla em inglês).

• Decida se você executará o BigQuery e o Cloud KMS no mesmo projeto do Google Cloud ou em projetos diferentes. Para fins de exemplo de documentação, usamos a convenção a seguir:

  • PROJECT_ID: o ID do projeto que executa o BigQuery
  • PROJECT_NUMBER: o número do projeto que executa o BigQuery
  • KMS_PROJECT_ID: o ID do projeto que executa o Cloud KMS, mesmo que seja o mesmo projeto que executa o BigQuery
  Para informações sobre os códigos de projeto e os números de projeto do Google Cloud, consulte Como identificar projetos.

• O BigQuery é ativado automaticamente em novos projetos. Se você estiver usando um projeto pré-existente para executar o BigQuery, ative a API BigQuery.

• Para o projeto do Google Cloud que executa o Cloud KMS, ative a API Cloud Key Management Service.

Uma chamada de descriptografia é realizada usando o Cloud KMS uma vez por consulta para uma tabela criptografada pelo CMEK. Para mais informações, consulte os preços do Cloud KMS.

Especificação de criptografia

As chaves do Cloud KMS usadas para proteger seus dados no BigQuery são chaves AES-256. Elas são usadas como chaves de criptografia de chaves no BigQuery porque criptografam as chaves de criptografia de dados que criptografam seus dados.

Criação manual ou automatizada de chaves

É possível criar as chaves CMEK manualmente ou usar a chave automática do Cloud KMS (Visualização). A Autokey simplifica a criação e o gerenciamento das chaves de CMEK ao automatizar o provisionamento e a atribuição. Com ele, você não precisa provisionar keyrings, chaves e contas de serviço com antecedência. Eles são gerados sob demanda como parte da criação de recursos do BigQuery. Para ver mais informações, consulte a Visão geral das chaves automáticas.

Criar um keyring e uma chave manualmente

Para o projeto do Google Cloud que executa o Cloud KMS, crie um keyring e uma chave, conforme descrito em Como criar keyrings e chaves. Crie o keyring em um local que corresponda ao local do conjunto de dados do BigQuery:

• Qualquer conjunto de dados multirregional deve usar um keyring multirregional de um local correspondente. Por exemplo, um conjunto de dados na região US deve ser protegido com um keyring da região us e um conjunto de dados na região EU deve ser protegido com um keyring da região europe.

• Conjuntos de dados regionais devem usar as chaves regionais correspondentes. Por exemplo, um conjunto de dados na região asia-northeast1 deve ser protegido com um keyring da região asia-northeast1.

• Não é possível usar a região global ao configurar a CMEK para o BigQuery no console do Google Cloud. No entanto, é possível usar a região global ao configurar a CMEK para o BigQuery usando a ferramenta de linha de comando bq ou o GoogleSQL.

Para mais informações sobre os locais compatíveis com o BigQuery e o Cloud KMS, consulte Locais do Cloud.

Conceder permissões de criptografia e descriptografia

Para proteger seus dados do BigQuery com uma chave CMEK, conceda permissão à conta de serviço do BigQuery para criptografar e descriptografar com essa chave. O papel Criptografador/Descriptografador de CryptoKey do Cloud KMS concede essa permissão.

Certifique-se de que a conta de serviço foi criada e use o Console do Google Cloud para determinar o ID da conta de serviço do BigQuery. Em seguida, forneça à conta de serviço o papel apropriado para criptografar e descriptografar usando o Cloud KMS.

Acionar a criação da sua conta de serviço

Sua conta de serviço do BigQuery não é criada inicialmente quando você cria um projeto. Para acionar a criação da conta de serviço, insira um comando que a use, como o comando bq show --encryption_service_account, ou chame o comando método da API projects.getServiceAccount. Por exemplo:

bq show --encryption_service_account --project_id=PROJECT_ID

Determinar o ID da conta de serviço

O ID da conta de serviço do BigQuery está no formato:

[e-mail]

As técnicas a seguir mostram como você pode determinar o ID da conta de serviço do BigQuery para seu projeto.

Console

1. Acesse a página Painel no console do Google Cloud:

   Ir para a página "Painel"

2. Clique na lista suspensa Selecionar de na parte superior da página. Na janela Selecionar de exibida, selecione o projeto.

3. O código e o número do projeto são exibidos no cartão Informações do projeto no Painel:

   

4. Na string a seguir, substitua PROJECT_NUMBER pelo número do projeto. A nova string identifica o ID da conta de serviço do BigQuery.

   [e-mail]
   

bq

Use o comando bq show com a sinalização --encryption_service_account para determinar o ID da conta de serviço:

bq show --encryption_service_account

O comando exibe o ID da conta de serviço:

                  ServiceAccountID
-------------------------------------------------------------
[e-mail]

Atribuir o papel criptografador/descriptografador

Atribua o papel "Criptografador/Descriptografador de CryptoKey do Cloud KMS" à conta de serviço do sistema do BigQuery que você copiou para a área de transferência. O formato da conta é:

[e-mail]

Console

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

   Abrir a página "Chaves criptográficas".

2. Clique no nome do keyring que contém a chave.

3. Clique na caixa de seleção da chave de criptografia à qual você quer adicionar o papel. A guia Permissões será aberta.

4. Clique em Adicionar membro.

5. Digite o endereço de e-mail da conta de serviço, [e-mail].

   • Se já estiver na lista de membros, a conta de serviço tem papéis. Clique na lista suspensa de funções atual para a conta de serviço [e-mail].

6. Clique na lista suspensa Selecionar um papel, clique em Cloud KMS e, depois, clique no papel Criptografador/Descriptografador de CryptoKey do Cloud KMS.

7. Clique em Salvar para aplicar o papel à conta de serviço [e-mail].

gcloud

Use a Google Cloud CLI para atribuir a função:

gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member serviceAccount:[e-mail] \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY

Substitua:

• KMS_PROJECT_ID: o ID do projeto do Google Cloud que está executando o Cloud KMS.
• PROJECT_NUMBER: o número (não o ID do projeto) do Google Cloud que está executando o BigQuery
• KMS_KEY_LOCATION: o nome do local da chave do Cloud KMS.
• KMS_KEY_RING: o nome do keyring da chave do Cloud KMS
• KMS_KEY: o nome da chave do Cloud KMS.

ID de recurso da chave

O ID do recurso da chave do Cloud KMS é necessário para o uso de CMEK, como mostrado nos exemplos. Essa chave diferencia maiúsculas de minúsculas e está no formato:

projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY

Observação: não é possível especificar um ID de recurso importante que inclua o token /cryptoKeyVersions/. O BigQuery sempre usa a versão de chave marcada como primary para proteger uma tabela quando ela é criada.

Recuperar o ID do recurso da chave

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

   Abrir a página "Chaves criptográficas".

2. Clique no nome do keyring que contém a chave.

3. Na chave referente ao código de recurso que está sendo recuperado, clique em Mais .

4. Clique em Copiar nome do recurso. O código do recurso da chave é copiado para a área de transferência. O ID do recurso também é conhecido como o nome do recurso.

Criar uma tabela protegida pelo Cloud KMS

Para criar uma tabela protegida pelo Cloud KMS:

Console

1. Abra a página do BigQuery no console do Google Cloud.

   Acesse a página do BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

3. Expanda a opção Ações e clique em Abrir.

4. No painel de detalhes, clique em Criar tabela .

5. Na página Criar tabela, preencha as informações necessárias para criar uma tabela vazia com uma definição de esquema. Antes de clicar em Criar tabela, configure o tipo de criptografia e especifique a chave do Cloud KMS a ser usada com a tabela:

   1. Clique em Opções avançadas.
   2. Clique em Chave gerenciada pelo cliente.
   3. Selecione a chave. Se a chave que você quer usar não estiver listada, insira o ID do recurso da chave.

6. Clique em Criar tabela.

SQL

Use a instrução CREATE TABLE com a opção kms_key_name:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE TABLE DATASET_ID.TABLE_ID (
     name STRING, value INT64
   ) OPTIONS (
       kms_key_name
         = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY');
   

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

É possível usar a ferramenta de linha de comando bq com a flag --destination_kms_key para criar a tabela. A flag --destination_kms_key especifica o ID de recurso da chave a ser usada com a tabela.

Para criar uma tabela vazia com um esquema:

bq mk --schema name:string,value:integer -t \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET_ID.TABLE_ID

Para criar uma tabela de uma consulta:

bq query --destination_table=DATASET_ID.TABLE_ID \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
"SELECT name,count FROM DATASET_ID.TABLE_ID WHERE gender = 'M' ORDER BY count DESC LIMIT 6"

Para mais informações sobre a ferramenta de linha de comando bq, consulte Como usar a ferramenta de linha de comando bq.

Terraform

Use o recurso google_bigquery_table.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir cria uma tabela chamada mytable e também usa os recursos google_kms_crypto_key e google_kms_key_ring para especificar uma chave do Cloud Key Management Service para a tabela.

Para executar este exemplo, é necessário ativar a API Cloud Resource Manager e a API Cloud Key Management Service.

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

  encryption_configuration {
    kms_key_name = google_kms_crypto_key.crypto_key.id
  }

  depends_on = [google_project_iam_member.service_account_access]
}

resource "google_kms_crypto_key" "crypto_key" {
  name     = "example-key"
  key_ring = google_kms_key_ring.key_ring.id
}

resource "random_id" "default" {
  byte_length = 8
}

resource "google_kms_key_ring" "key_ring" {
  name     = "${random_id.default.hex}-example-keyring"
  location = "us"
}

# Enable the BigQuery service account to encrypt/decrypt Cloud KMS keys
data "google_project" "project" {
}

resource "google_project_iam_member" "service_account_access" {
  project = data.google_project.project.project_id
  role    = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
  member  = "serviceAccount:bq-${data.google_project.project.number}@bigquery-encryption.iam.gserviceaccount.com"
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Observação: as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no projeto do Google Cloud.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// createTableWithCMEK demonstrates creating a table protected with a customer managed encryption key.
func createTableWithCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta := &bigquery.TableMetadata{
		EncryptionConfig: &bigquery.EncryptionConfig{
			// TODO: Replace this key with a key you have created in Cloud KMS.
			KMSKeyName: "projects/cloud-samples-tests/locations/us/keyRings/test/cryptoKeys/test",
		},
	}
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create a cmek table
public class CreateTableCMEK {

  public static void runCreateTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KEY_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    // i.e. projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{cryptoKey}
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    createTableCMEK(datasetName, tableName, schema, encryption);
  }

  public static void createTableCMEK(
      String datasetName, String tableName, Schema schema, EncryptionConfiguration configuration) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo =
          TableInfo.newBuilder(tableId, tableDefinition)
              .setEncryptionConfiguration(configuration)
              .build();

      bigquery.create(tableInfo);
      System.out.println("Table cmek created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table cmek was not created. \n" + e.toString());
    }
  }
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Proteja uma nova tabela com uma chave de criptografia gerenciada pelo cliente definindo a propriedade Table.encryption_configuration como um objeto EncryptionConfiguration antes de criar a tabela.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

# Set the encryption key to use for the table.
# TODO: Replace this key with a key you have created in Cloud KMS.
kms_key_name = "projects/your-project/locations/us/keyRings/test/cryptoKeys/test"

table = bigquery.Table(table_id)
table.encryption_configuration = bigquery.EncryptionConfiguration(
    kms_key_name=kms_key_name
)
table = client.create_table(table)  # API request

print(f"Created {table_id}.")
print(f"Key: {table.encryption_configuration.kms_key_name}.")

Consultar uma tabela protegida por uma chave do Cloud KMS

Nenhuma disposição especial é necessária para consultar uma tabela protegida pelo Cloud KMS. O nome da chave usada para criptografar o conteúdo da tabela é armazenado no BigQuery e essa chave é usada quando houver uma consulta a uma tabela protegida pelo Cloud KMS.

Todas as ferramentas, o console do BigQuery e a interface de linha de comando bq são executados da mesma maneira que as tabelas criptografadas por padrão, desde que o BigQuery tenha acesso à chave do Cloud KMS usada para criptografar o conteúdo da tabela.

Proteja os resultados da consulta com uma chave do Cloud KMS

Por padrão, os resultados de consulta são armazenados em uma tabela temporária criptografada com Chave de propriedade do Google e gerenciada pelo Google. Se o projeto já tiver uma chave padrão, a chave é aplicada à tabela temporária (padrão) de resultados da consulta. Para usar uma chave do Cloud KMS para criptografar os resultados da consulta, selecione uma das seguintes opções:

Console

1. Abra a página do BigQuery no console do Google Cloud.

   Acesse a página do BigQuery

2. Clique em Escrever nova consulta.

3. Insira uma consulta GoogleSQL válida na área de texto da consulta.

4. Clique em Mais, em Configurações de consulta e em Opções avançadas.

5. Selecione Criptografia gerenciada pelo cliente.

6. Selecione a chave. Se a chave que você quer usar não estiver listada, insira o ID do recurso da chave.

7. Clique em Salvar.

8. Clique em Executar.

bq

Especifique a sinalização --destination_kms_key para proteger a tabela de destino ou os resultados da consulta (se estiver usando uma tabela temporária) com a chave do Cloud KMS. A sinalização --destination_kms_key especifica o código de recurso da chave a ser usada com a tabela de destino ou resultante.

Se preferir, use a sinalização --destination_table para especificar o destino dos resultados da consulta. Se --destination_table não for usado, os resultados da consulta serão gravados em uma tabela temporária.

Para consultar uma tabela:

bq query \
--destination_table=DATASET_ID.TABLE_ID \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
"SELECT name,count FROM DATASET_ID.TABLE_ID WHERE gender = 'M' ORDER BY count DESC LIMIT 6"

Para mais informações sobre a ferramenta de linha de comando bq, consulte Como usar a ferramenta de linha de comando bq.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Proteja uma nova tabela com uma chave de criptografia gerenciada pelo cliente definindo a propriedade Table.encryption_configuration como um objeto EncryptionConfiguration antes de criar a tabela.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryWithDestinationCMEK demonstrates saving query results to a destination table and protecting those results
// by specifying a customer managed encryption key.
func queryWithDestinationCMEK(w io.Writer, projectID, dstDatasetID, dstTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query("SELECT 17 as my_col")
	q.Location = "US" // Location must match the dataset(s) referenced in query.
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)
	q.DestinationEncryptionConfig = &bigquery.EncryptionConfig{
		// TODO: Replace this key with a key you have created in Cloud KMS.
		KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/test",
	}
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Proteja uma nova tabela com uma chave de criptografia gerenciada pelo cliente definindo a propriedade Table.encryption_configuration como um objeto EncryptionConfiguration antes de criar a tabela.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

// Sample to query on destination table with encryption key
public class QueryDestinationTableCMEK {

  public static void runQueryDestinationTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KMS_KEY_NAME";
    String query =
        String.format("SELECT stringField, booleanField FROM %s.%s", datasetName, tableName);
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    queryDestinationTableCMEK(query, encryption);
  }

  public static void queryDestinationTableCMEK(String query, EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      QueryJobConfiguration config =
          QueryJobConfiguration.newBuilder(query)
              // Set the encryption key to use for the destination.
              .setDestinationEncryptionConfiguration(encryption)
              .build();

      TableResult results = bigquery.query(config);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));
      System.out.println("Query performed successfully with encryption key.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Para proteger uma tabela de destino de consulta com uma chave de criptografia gerenciada pelo cliente, defina a propriedade QueryJobConfig.destination_encryption_configuration como EncryptionConfiguration e execute a consulta.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Set the encryption key to use for the destination.
# TODO(developer): Replace this key with a key you have created in KMS.
# kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
#     your-project, location, your-ring, your-key
# )

job_config = bigquery.QueryJobConfig(
    destination=table_id,
    destination_encryption_configuration=bigquery.EncryptionConfiguration(
        kms_key_name=kms_key_name
    ),
)

# Start the query, passing in the extra configuration.
query_job = client.query(
    "SELECT 17 AS my_col;", job_config=job_config
)  # Make an API request.
query_job.result()  # Wait for the job to complete.

table = client.get_table(table_id)  # Make an API request.
if table.encryption_configuration.kms_key_name == kms_key_name:
    print("The destination table is written using the encryption configuration")

Carregar uma tabela protegida pelo Cloud KMS

Para carregar um arquivo de dados em uma tabela protegida pelo Cloud KMS:

Console

Para proteger uma tabela de destino do job de carga com uma chave de criptografia gerenciada pelo cliente, especifique a chave ao carregar a tabela.

1. Abra a página do BigQuery no console do Google Cloud.

   Acesse a página do BigQuery

2. No painel Explorer, expanda o projeto e selecione um conjunto de dados.

3. No painel de detalhes, clique em Criar tabela.

4. Insira as opções a serem usadas no carregamento da tabela antes de clicar em Criar tabela e Opções avançadas.

5. Em Criptografia, selecione Chave gerenciada pelo cliente.

6. Clique na lista suspensa Selecionar uma chave gerenciada pelo cliente e selecione a chave a ser usada. Caso não veja nenhuma chave disponível, insira um código de recurso de chave.

   

7. Clique em Criar tabela.

bq

Para proteger uma tabela de destino do job de carregamento com uma chave de criptografia gerenciada pelo cliente, defina a sinalização --destination_kms_key.

bq --location=LOCATION load \
--autodetect \
--source_format=FORMAT \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET.TABLE \
path_to_source

Por exemplo:

bq load \
--autodetect \
--source_format=NEWLINE_DELIMITED_JSON \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
test2.table4 \
gs://cloud-samples-data/bigquery/us-states/us-states.json

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importJSONWithCMEK demonstrates loading newline-delimited JSON from Cloud Storage,
// and protecting the data with a customer-managed encryption key.
func importJSONWithCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty
	loader.DestinationEncryptionConfig = &bigquery.EncryptionConfig{
		// TODO: Replace this key with a key you have created in KMS.
		KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/test",
	}

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}

	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data with configuration key from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCSCMEK {

  public static void runLoadJsonFromGCSCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KMS_KEY_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    // i.e. projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{cryptoKey}
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    loadJsonFromGCSCMEK(datasetName, tableName, sourceUri, encryption);
  }

  public static void loadJsonFromGCSCMEK(
      String datasetName, String tableName, String sourceUri, EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              // Set the encryption key to use for the destination.
              .setDestinationEncryptionConfiguration(encryption)
              .setFormatOptions(FormatOptions.json())
              .setAutodetect(true)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table loaded succesfully from GCS with configuration key");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Para proteger uma tabela de destino da tarefa de carregamento com uma chave de criptografia gerenciada pelo cliente, defina a propriedade LoadJobConfig.destination_encryption_configuration como EncryptionConfiguration e carregue a tabela.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

# Set the encryption key to use for the destination.
# TODO: Replace this key with a key you have created in KMS.
# kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
#     "cloud-samples-tests", "us", "test", "test"
# )

job_config = bigquery.LoadJobConfig(
    autodetect=True,
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
    destination_encryption_configuration=bigquery.EncryptionConfiguration(
        kms_key_name=kms_key_name
    ),
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    job_config=job_config,
)  # Make an API request.

assert load_job.job_type == "load"

load_job.result()  # Waits for the job to complete.

assert load_job.state == "DONE"
table = client.get_table(table_id)

if table.encryption_configuration.kms_key_name == kms_key_name:
    print("A table loaded with encryption configuration key")

Fazer streaming em uma tabela protegida pelo Cloud KMS

Faça o streaming de dados na sua tabela do BigQuery protegida pelo CMEK sem especificar um parâmetro adicional. Observe que esses dados são criptografados usando sua chave do Cloud KMS no buffer e no local final. Antes de usar streaming com uma tabela CMEK, revise os requisitos em disponibilidade e acessibilidade da chave.

Saiba mais sobre streaming em Como fazer streaming de dados usando a API BigQuery Storage Write.

Alterar uma tabela da criptografia padrão para proteção do Cloud KMS

bq

É possível usar o comando bq cp com a sinalização --destination_kms_key para copiar uma tabela protegida por criptografia padrão para uma nova tabela ou para a tabela original, protegida pelo Cloud KMS. A sinalização --destination_kms_key especifica o código de recurso da chave a ser usada com a tabela de destino.

Para copiar uma tabela com criptografia padrão para uma nova tabela com proteção do Cloud KMS:

bq cp \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
SOURCE_DATASET_ID.SOURCE_TABLE_ID DESTINATION_DATASET_ID.DESTINATION_TABLE_ID

Caso você queira copiar uma tabela com criptografia padrão para a mesma tabela com proteção do Cloud KMS:

bq cp -f \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET_ID.TABLE_ID DATASET_ID.TABLE_ID

Se quiser alterar uma tabela da proteção do Cloud KMS para a criptografia padrão, copie o arquivo para si mesmo executando bq cp sem usar a sinalização --destination_kms_key.

Para mais informações sobre a ferramenta de linha de comando bq, consulte Como usar a ferramenta de linha de comando bq.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// copyTableWithCMEK demonstrates creating a copy of a table and ensuring the copied data is
// protected with a customer managed encryption key.
func copyTableWithCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcTable := client.DatasetInProject("bigquery-public-data", "samples").Table("shakespeare")
	copier := client.Dataset(datasetID).Table(tableID).CopierFrom(srcTable)
	copier.DestinationEncryptionConfig = &bigquery.EncryptionConfig{
		// TODO: Replace this key with a key you have created in Cloud KMS.
		KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/test",
	}
	job, err := copier.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CopyJobConfiguration;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.TableId;

// Sample to copy a cmek table
public class CopyTableCMEK {

  public static void runCopyTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String destinationDatasetName = "MY_DESTINATION_DATASET_NAME";
    String destinationTableId = "MY_DESTINATION_TABLE_NAME";
    String sourceDatasetName = "MY_SOURCE_DATASET_NAME";
    String sourceTableId = "MY_SOURCE_TABLE_NAME";
    String kmsKeyName = "MY_KMS_KEY_NAME";
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    copyTableCMEK(
        sourceDatasetName, sourceTableId, destinationDatasetName, destinationTableId, encryption);
  }

  public static void copyTableCMEK(
      String sourceDatasetName,
      String sourceTableId,
      String destinationDatasetName,
      String destinationTableId,
      EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId sourceTable = TableId.of(sourceDatasetName, sourceTableId);
      TableId destinationTable = TableId.of(destinationDatasetName, destinationTableId);

      // For more information on CopyJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/JobConfiguration.html
      CopyJobConfiguration configuration =
          CopyJobConfiguration.newBuilder(destinationTable, sourceTable)
              .setDestinationEncryptionConfiguration(encryption)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to copy table due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Table cmek copied successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table cmek copying job was interrupted. \n" + e.toString());
    }
  }
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Para proteger o destino de uma cópia de tabela com uma chave de criptografia gerenciada pelo cliente, defina a propriedade QueryJobConfig.destination_encryption_configuration como EncryptionConfiguration e copie a tabela.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dest_table_id to the ID of the destination table.
# dest_table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set orig_table_id to the ID of the original table.
# orig_table_id = "your-project.your_dataset.your_table_name"

# Set the encryption key to use for the destination.
# TODO(developer): Replace this key with a key you have created in KMS.
# kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
#     your-project, location, your-ring, your-key
# )

job_config = bigquery.CopyJobConfig(
    destination_encryption_configuration=bigquery.EncryptionConfiguration(
        kms_key_name=kms_key_name
    )
)
job = client.copy_table(orig_table_id, dest_table_id, job_config=job_config)
job.result()  # Wait for the job to complete.

dest_table = client.get_table(dest_table_id)  # Make an API request.
if dest_table.encryption_configuration.kms_key_name == kms_key_name:
    print("A copy of the table created")

Determinar se uma tabela é protegida pelo Cloud KMS

1. No console do Google Cloud, clique na seta azul à esquerda do conjunto de dados para expandi-lo ou clique duas vezes no nome dele. Isso exibe as tabelas e visualizações no conjunto de dados.

2. Clique no nome da tabela.

3. Clique em Detalhes. A página Detalhes da tabela exibe a descrição e as informações da tabela.

4. Caso a tabela esteja protegida pelo Cloud KMS, o campo Chave de criptografia gerenciada pelo cliente exibirá o ID do recurso da chave.

   

Para cada uma das chaves que você criou ou que protegem suas tabelas, é possível ver quais recursos essa chave protege com o rastreamento de uso da chave. Para mais informações, consulte Ver o uso da chave.

Alterar a chave do Cloud KMS para uma tabela do BigQuery

Para alterar a chave do Cloud KMS de uma tabela protegida pelo CMEK, é possível realizar uma consulta ALTER TABLE, usar a API ou usar a ferramenta de linha de comando bq. Há duas maneiras de modificar a chave do Cloud KMS usando a API e a ferramenta de linha de comando bq: update ou cp.

Se você usar update, poderá alterar a chave do Cloud KMS usada em uma tabela protegida pela CMEK.

Se você usar cp, poderá alterar a chave do Cloud KMS usada em uma tabela protegida pela CMEK, alterar uma tabela da criptografia padrão para a proteção de CMEK ou alterar uma tabela da proteção de CMEK para o padrão criptografia.

Uma vantagem de update é que é mais rápido que cp e permite usar decoradores de tabela.

SQL

Use a instrução ALTER TABLE SET OPTIONS para atualizar o campo kms_key_name de uma tabela:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   ALTER TABLE DATASET_ID.mytable
   SET OPTIONS (
     kms_key_name
       = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY');
   

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

É possível usar o comando bq cp com a sinalização --destination_kms_key para alterar a chave de uma tabela protegida pelo Cloud KMS. A sinalização --destination_kms_key especifica o código de recurso da chave a ser usada com a tabela.

bq update \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
-t DATASET_ID.TABLE_ID

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateTableChangeCMEK demonstrates how to change the customer managed encryption key that protects a table.
func updateTableChangeCMEK(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	update := bigquery.TableMetadataToUpdate{
		EncryptionConfig: &bigquery.EncryptionConfig{
			// TODO: Replace this key with a key you have created in Cloud KMS.
			KMSKeyName: "projects/cloud-samples-tests/locations/us-central1/keyRings/test/cryptoKeys/otherkey",
		},
	}
	if _, err := tableRef.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.EncryptionConfiguration;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;

// Sample to update a cmek table
public class UpdateTableCMEK {

  public static void runUpdateTableCMEK() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String kmsKeyName = "MY_KEY_NAME";
    // Set a new encryption key to use for the destination.
    // i.e. projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{cryptoKey}
    EncryptionConfiguration encryption =
        EncryptionConfiguration.newBuilder().setKmsKeyName(kmsKeyName).build();
    updateTableCMEK(datasetName, tableName, encryption);
  }

  public static void updateTableCMEK(
      String datasetName, String tableName, EncryptionConfiguration encryption) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      bigquery.update(table.toBuilder().setEncryptionConfiguration(encryption).build());
      System.out.println("Table cmek updated successfully");
    } catch (BigQueryException e) {
      System.out.println("Table cmek was not updated. \n" + e.toString());
    }
  }
}

Python

Altere a chave de criptografia gerenciada pelo cliente de uma tabela alterando a propriedade Table.encryption_configuration para um novo objeto EncryptionConfiguration e atualize a tabela.

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

# from google.cloud import bigquery
# client = bigquery.Client()

assert table.encryption_configuration.kms_key_name == original_kms_key_name

# Set a new encryption key to use for the destination.
# TODO: Replace this key with a key you have created in KMS.
updated_kms_key_name = (
    "projects/cloud-samples-tests/locations/us/keyRings/test/cryptoKeys/otherkey"
)
table.encryption_configuration = bigquery.EncryptionConfiguration(
    kms_key_name=updated_kms_key_name
)

table = client.update_table(table, ["encryption_configuration"])  # API request

assert table.encryption_configuration.kms_key_name == updated_kms_key_name
assert original_kms_key_name != updated_kms_key_name

Definir uma chave padrão do conjunto de dados

É possível definir uma chave padrão do Cloud KMS para o conjunto de dados inteiro. Ela é aplicada a todas as tabelas recém-criadas nesse conjunto, exceto se outra chave do Cloud KMS for especificada na criação da tabela. A chave padrão não se aplica às tabelas atuais. A alteração da chave padrão não modifica nenhuma tabela e se aplica somente às novas tabelas criadas após a alteração.

Para aplicar, alterar ou remover uma chave padrão do conjunto de dados

• especificando a chave padrão no campo EncryptionConfiguration.kmsKeyName ao chamar os métodos datasets.insert ou datasets.patch

• especificando a chave padrão na sinalização --default_kms_key ao executar o comando bq mk --dataset.

  bq mk \
  --default_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
  --dataset DATASET_ID
  

  bq update \
  --default_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
  --dataset DATASET_ID
  

Observação: em um conjunto de dados com uma chave padrão do Cloud KMS aplicada, não é possível criptografar tabelas com outra chave além da chave de criptografia gerenciada pelo cliente. Ou seja, se o conjunto de dados tiver uma chave padrão do Cloud KMS, não será possível usar uma chave que não seja a de criptografia gerenciada pelo cliente para criptografar tabelas novas no conjunto de dados.

Definir uma chave padrão de projeto

É possível definir chaves padrão do Cloud KMS que se aplicam a todos os resultados de consultas e tabelas recém-criadas no projeto para esse local, a menos que você especifique uma chave diferente do Cloud KMS. A chave padrão não se aplica às tabelas atuais. A alteração da chave padrão não modifica nenhuma tabela e se aplica somente às novas tabelas criadas após a alteração.

SQL

Use a instrução ALTER PROJECT SET OPTIONS para atualizar o campo default_kms_key_name de uma tabela: É possível encontrar o nome do recurso para a chave na página do Cloud KMS.

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   ALTER PROJECT PROJECT_ID
   SET OPTIONS (
     region-<var>LOCATION</var>.default_kms_key_name
       = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY');
   

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

É possível usar o comando bq para executar uma instrução ALTER PROJECT SET OPTIONS para atualizar o campo default_kms_key_name de um projeto:

bq query --nouse_legacy_sql \
  'ALTER PROJECT PROJECT_ID
  SET OPTIONS (
  `region-LOCATION.default_kms_key_name`
    ="projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY");'

Usar CMEK para proteger modelos do BigQuery ML

O BigQuery ML é compatível com CMEK. Além da criptografia padrão fornecida pelo BigQuery, é possível usar suas próprias chaves do Cloud Key Management Service para criptografar modelos de machine learning, incluindo modelos importados do TensorFlow.

Criar um modelo criptografado com uma chave do Cloud KMS

Para criar um modelo criptografado, use a instrução CREATE MODEL e especifique KMS_KEY_NAME nas opções de treinamento:

    CREATE MODEL my_dataset.my_model
    OPTIONS(
      model_type='linear_reg',
      input_label_cols=['your_label'],
      kms_key_name='projects/my_project/locations/my_location/keyRings/my_ring/cryptoKeys/my_key')
    AS SELECT * FROM my_dataset.my_data

A mesma sintaxe também se aplica a modelos importados do TensorFlow:

    CREATE MODEL my_dataset.my_model
    OPTIONS(
      model_type='tensorflow',
      path='gs://bucket/path/to/saved_model/*',
      kms_key_name='projects/my_project/locations/my_location/keyRings/my_ring/cryptoKeys/my_key')
    AS SELECT * FROM my_dataset.my_data

Limitações

As chaves de criptografia gerenciadas pelo cliente têm as seguintes restrições ao criptografar modelos de machine learning:

• As chaves CMEK da região Global não são compatíveis com os seguintes tipos de modelos:

  • DNN
  • Amplitude e profundidade
  • Codificador automático
  • Árvore aprimorada

• Global chaves CMEK da região e chaves CMEK multirregionais, por exemplo, EU ou US, não são compatíveis com a criação dos seguintes tipos de modelos:

  • Modelos do AutoML Tables

• As chaves CMEK não são compatíveis com modelos remotos:

  • Modelos remotos sobre modelos integrados da Vertex AI
  • Modelos remotos sobre modelos hospedados na Vertex AI
  • Modelos remotos em serviços de IA do Cloud

Alterar um modelo da criptografia padrão para proteção do Cloud KMS

Use o comando bq cp com a flag --destination_kms_key para copiar um modelo protegido por criptografia padrão em um novo modelo protegido pelo Cloud KMS. Como alternativa, use o comando bq cp com a flag -f para substituir um modelo protegido por criptografia padrão e atualizá-lo para usar a proteção do Cloud KMS. A flag --destination_kms_key especifica o ID de recurso da chave a ser usada com o modelo de destino.

Para copiar um modelo com criptografia padrão para um novo modelo com proteção do Cloud KMS:

bq cp \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
SOURCE_DATASET_ID.SOURCE_MODEL_ID DESTINATION_DATASET_ID.DESTINATION_MODEL_ID

Para substituir um modelo com criptografia padrão pelo mesmo modelo com proteção do Cloud KMS:

bq cp -f \
--destination_kms_key projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET_ID.MODEL_ID DATASET_ID.MODEL_ID

Para alterar um modelo de proteção do Cloud KMS para a criptografia padrão:

bq cp -f \
DATASET_ID.MODEL_ID DATASET_ID.MODEL_ID

Para mais informações sobre a ferramenta de linha de comando bq, consulte Como usar a ferramenta de linha de comando bq.

Determinar se um modelo é protegido pelo Cloud KMS

Use o comando bq show para saber se um modelo é protegido pela chave do Cloud KMS. A chave de criptografia está no campo kmsKeyName.

bq show -m my_dataset.my_model

Também é possível usar o console do Google Cloud para descobrir a chave do Cloud KMS de um modelo criptografado. As informações de CMEK estão no campo Chave gerenciada pelo cliente na seção Detalhes do modelo do painel Detalhes do modelo.

Alterar a chave do Cloud KMS para um modelo criptografado

Use o comando bq update com a flag --destination_kms_key para mudar a chave de um modelo protegido pelo Cloud KMS.

bq update --destination_kms_key \
projects/my_project/locations/my_location/keyRings/my_ring/cryptoKeys/my_key \
-t my_dataset.my_model

Usar chaves padrão do projeto ou do conjunto de dados

Se você tiver uma chave padrão do Cloud KMS definida no nível do projeto ou do conjunto de dados, o BigQuery ML usará essa chave automaticamente ao criar modelos. Use a instrução CREATE MODEL para especificar uma chave diferente para criptografar o modelo, caso não queira usar a chave padrão.

Usar funções do BigQuery ML com modelos criptografados

É possível usar todas as funções do BigQuery ML com um modelo criptografado sem especificar uma chave de criptografia.

Usar CMEK para proteger a API BigQuery Connection

Em conexões do Cloud SQL, é possível proteger suas credenciais da API BigQuery Connection usando CMEK.

Para mais informações sobre como criar uma conexão protegida por CMEK, consulte Criar conexões do Cloud SQL.

Remover o acesso do BigQuery à chave Cloud KMS

É possível remover o acesso do BigQuery à chave do Cloud KMS a qualquer momento, revogando a permissão de gerenciamento de identidade e acesso (IAM, na sigla em inglês) dessa chave.

Observação: se você remover o acesso do BigQuery a uma chave, essa alteração não ocorrerá instantaneamente, mas acontecerá em uma hora, enquanto a alteração da permissão do IAM é propagada. Se você estiver executando uma consulta no momento, ela ainda será concluída, mas os resultados podem não ser visíveis.

Se o BigQuery perder o acesso à chave do Cloud KMS, a experiência do usuário provavelmente será afetada e poderá ocorrer perda de dados:

• Os dados nestas tabelas protegidas pelo CMEK não poderão mais ser acessados: query, cp, extract e tabledata.list falharão.

• Nenhum dado novo será adicionado a essas tabelas protegidas pelo CMEK.

• Depois que o acesso for concedido novamente, o desempenho das consultas para essas tabelas poderá ser reduzido durante vários dias.

Controlar o uso de CMEK com a política da organização

O BigQuery se integra às restrições da política da organização do CMEK para permitir que você especifique os requisitos de conformidade de criptografia para os recursos do BigQuery na sua organização.

Com essa integração, é possível:

• Exija CMEKs para todos os recursos do BigQuery em um projeto.

• Restringir quais chaves do Cloud KMS podem ser usadas para proteger recursos em um projeto.

Exigir CMEKs para todos os recursos

Uma política comum é exigir que as CMEKs sejam usadas para proteger todos os recursos em um conjunto específico de projetos. É possível usar a restrição constraints/gcp.restrictNonCmekServices para aplicar essa política ao BigQuery.

Se definida, essa política da organização faz com que todas as solicitações de criação de recursos sem uma chave especificada do Cloud KMS falhem.

Após definir essa política, ela será aplicada somente a novos recursos no projeto. Os recursos atuais sem as chaves do Cloud KMS definidas continuam existindo e podem ser acessados sem problemas.

Observação: essa restrição se aplica apenas a recursos que contêm dados. Os recursos que usam apenas a chave especificada do Cloud KMS como padrão para novos recursos (por exemplo, conjuntos de dados e configuração do projeto) ainda podem ser criados ou atualizados sem uma chave do Cloud KMS.

Console

1. Abra a página Políticas da organização.

   Acessar as políticas da organização

2. No campo Filtro, insira constraints/gcp.restrictNonCmekServices e clique em Restringir quais serviços podem criar recursos sem CMEK.

3. Clique em Editar.

4. Selecione Personalizar, Substituir e clique em Adicionar regra.

5. Selecione Personalizar e clique em Negar.

6. No campo Valor personalizado, insira is:bigquery.googleapis.com.

7. Clique em Concluído e depois em Salvar.

gcloud

  gcloud resource-manager org-policies --project=PROJECT_ID \
    deny gcp.restrictNonCmekServices is:bigquery.googleapis.com

Para verificar se a política foi aplicada, tente criar uma tabela no projeto. O processo falhará a menos que você especifique uma chave do Cloud KMS.

Esta política também se aplica às tabelas de resultados da consulta no projeto. Especifique uma chave padrão do projeto para que os usuários não precisem especificar manualmente uma chave sempre que executarem uma consulta no projeto.

Restringir chaves do Cloud KMS para um projeto do BigQuery

É possível usar a restrição constraints/gcp.restrictCmekCryptoKeyProjects para restringir as chaves do Cloud KMS que podem ser usadas para proteger um recurso em um projeto do BigQuery.

É possível especificar uma regra, por exemplo, "Para todos os recursos do BigQuery em projects/my-company-data-project, as chaves do Cloud KMS usadas nesse projeto precisam vir de projects/my-company-central-keys OU projetos/chaves específicas da equipe."

Console

1. Abra a página Políticas da organização.

   Acessar as políticas da organização

2. No campo Filtro, insira constraints/gcp.restrictCmekCryptoKeyProjects e clique em Restringir quais projetos podem fornecer CryptoKeys do KMS para CMEK.

3. Clique em Editar.

4. Selecione Personalizar, Substituir e clique em Adicionar regra.

5. Selecione Personalizar e clique em Permitir.

6. No campo Valor personalizado, insira under:projects/<var>KMS_PROJECT_ID</var>.

7. Clique em Concluído e depois em Salvar.

gcloud

  gcloud resource-manager org-policies --project=PROJECT_ID \
    allow gcp.restrictCmekCryptoKeyProjects under:projects/KMS_PROJECT_ID

Para verificar se a política foi aplicada, tente criar uma tabela usando uma chave do Cloud KMS de um projeto diferente. O processo falhará.

Limitações das políticas da organização

Há limitações associadas à definição de uma política da organização.

Atraso na propagação

Depois que você define ou atualiza uma política da organização, pode levar até 15 minutos para a nova política entrar em vigor. O BigQuery armazena em cache políticas para não afetar negativamente a latência de criação de consultas e tabelas.

Permissões necessárias para definir uma política da organização

Pode ser difícil obter a permissão para definir ou atualizar a política da organização para fins de teste. É necessário receber o papel de administrador da política da organização, que só pode ser concedido no nível da organização, não no nível do projeto ou da pasta.

Embora o papel precise ser concedido no nível da organização, ainda é possível especificar uma política que se aplica apenas a um projeto ou pasta específicos.

Impacto do rodízio de chaves do Cloud KMS

O BigQuery não alterna automaticamente uma chave de criptografia de tabela quando a chave do Cloud KMS associada à tabela é alternada. Todos os dados nas tabelas atuais continuam sendo protegidos pela versão da chave com que foram criados.

Todas as tabelas recém-criadas usam a versão da chave primária no momento da criação delas.

Para atualizar uma tabela e usar a versão mais recente, altere-a para uma chave diferente do Cloud KMS e volte para a original.

Impacto no faturamento do Cloud KMS

Quando você cria ou trunca uma tabela protegida por CMEK, o BigQuery gera uma chave de criptografia de chaves intermediária que é criptografada com a chave do Cloud KMS especificada.

Para fins de faturamento, isso significa que nenhuma das suas chamadas para o Cloud KMS nem os custos associados aumentam com o tamanho da tabela. Para tabelas protegidas por CMEK, é possível esperar uma chamada para o Cloud KMS cryptoKeys.encrypt para cada criação ou truncamento de tabela e uma chamada para o Cloud KMS cryptoKeys.decrypt para cada tabela envolvida em uma consulta. Esses métodos pertencem à categoria de Operações de chave: criptográficas listadas em Preços do Cloud KMS.

Ler ou gravar em uma tabela protegida pelo CMEK invoca o Cloud KMS cryptoKeys.decrypt porque a chave intermediária precisa ser descriptografada.

Limitações

Acesso do BigQuery à chave do Cloud KMS

Uma chave do Cloud KMS é considerada disponível e acessível pelo BigQuery nas seguintes condições:

• a chave está ativada
• A conta de serviço do BigQuery tem permissões de criptografia e descriptografia na chave.

As próximas seções descrevem o impacto nas inserções de streaming e nos dados inacessíveis a longo prazo quando uma chave está inacessível.

Impacto em inserções de streaming

A chave do Cloud KMS precisa estar disponível e acessível por pelo menos 24 horas consecutivas no período de 48 horas após uma solicitação de inserção de streaming. Se a chave não estiver disponível e acessível, é possível que os dados transmitidos por streaming não sejam totalmente persistidos e possam ser perdidos. Para mais informações sobre inserções por streaming, consulte Como fazer streaming de dados para o BigQuery.

Impacto nos dados inacessíveis a longo prazo

Como o BigQuery fornece armazenamento gerenciado, os dados inacessíveis a longo prazo não são compatíveis com a arquitetura dele. Se a chave do Cloud KMS de uma determinada tabela do BigQuery não estiver disponível e acessível por sessenta dias consecutivos, o BigQuery poderá escolher excluir a tabela e os dados associados a ela. Pelo menos sete dias antes da exclusão dos dados, o BigQuery envia um e-mail para o endereço de e-mail associado à conta de faturamento.

Como usar fontes de dados externas

Se você estiver consultando dados armazenados em uma fonte de dados externa, como o Cloud Storage, que tem dados criptografados pela CMEK, a criptografia de dados é gerenciada pelo Cloud Storage. Por exemplo, as tabelas do BigLake são compatíveis com dados criptografados com CMEK no Cloud Storage.

As tabelas do BigLake e do BigQuery não são compatíveis com chaves de criptografia fornecidas pelo cliente (CSEK, na sigla em inglês).

Como alternar entre criptografia protegida pela CMEK e padrão

Não é possível alternar uma tabela no local entre as criptografias padrão e CMEK. Para alternar a criptografia, copie a tabela com o conjunto de informações de criptografia de destino ou use uma consulta SELECT * para selecionar a tabela em si com a disposição WRITE_TRUNCATE.

Como usar decoradores de tabela

Se você proteger uma tabela com o Cloud KMS e substituir os dados na tabela usando o valor WRITE_TRUNCATE para uma operação load, cp ou query, os decoradores de intervalos não funcionarão dentro do limite de mudança de criptografia. Ainda é possível usar decoradores de tabela, incluindo decoradores de intervalo, para consultar os dados antes ou depois do limite ou consultar o snapshot em um momento.

Consultas de tabelas de caractere curinga

As tabelas protegidas pelo CMEK não podem ser consultadas com um sufixo curinga.

Suporte a edições

O suporte do CMEK para o BigQuery está disponível apenas para o BigQuery Enterprise Plus e o BigQuery On-Demand. Os clientes do BigQuery de reservas de taxa fixa legadas antes de 5 de julho de 2023 mantêm todo o suporte atual para CMEK no nível Enterprise.

Suporte ao BigQuery Studio

Os recursos de código do BigQuery Studio, incluindo consultas salvas e notebooks, não são compatíveis com a CMEK.

Perguntas frequentes

Quem precisa de permissão para a chave do Cloud KMS?

Com as chaves de criptografia gerenciadas pelo cliente, não é necessário especificar permissões repetidamente. Enquanto a conta de serviço do BigQuery tiver permissão para usar a chave do Cloud KMS para criptografia e descriptografia, qualquer pessoa com permissão para a tabela do BigQuery terá acesso aos dados, mesmo sem acesso direto a essa chave.

Qual conta de serviço é usada?

A conta de serviço do BigQuery associada ao projeto do Google Cloud da tabela é usada para descriptografar os dados dessa tabela. As contas de serviço do BigQuery são exclusivas para cada projeto. Para um job que grava dados em uma tabela anônima protegida pelo Cloud KMS, é usada a conta de serviço do projeto desse job.

Como exemplo, considere três tabelas protegidas pelo CMEK: table1, table2 e table3. Para consultar dados de {project1.table1, project2.table2} com tabela de destino {project3.table3}:

• Use a conta de serviço project1 para project1.table1
• Use a conta de serviço project2 para project2.table2
• Use a conta de serviço project3 para project3.table3

Como o BigQuery usa minha chave do Cloud KMS?

O BigQuery usa a chave do Cloud KMS para descriptografar dados em resposta a uma consulta do usuário, por exemplo,tabledata.list ou jobs.insert.

O BigQuery também pode usar a chave para tarefas de manutenção de dados e otimização de armazenamento, como a conversão de dados em formato otimizado para leitura.

Quais bibliotecas de criptografia são usadas?

O BigQuery usa a funcionalidade de CMEK do Cloud KMS. O Cloud KMS usa a Tink (em inglês) para criptografia.

Como receber mais ajuda?

Se você tiver perguntas que não foram respondidas aqui, consulte o suporte do BigQuery.

Como solucionar erros

Confira a seguir os erros comuns e as mitigações recomendadas.

Erro	Recomendação
Atribua o papel criptografador/descriptografador da CryptoKey do Cloud KMS	A conta de serviço do BigQuery associada ao projeto não tem permissão do IAM suficiente para operar na chave do Cloud KMS especificada. Siga as instruções do erro ou desta documentação para conceder a permissão adequada do IAM.
As configurações de criptografia de tabela atuais não correspondem às configurações de criptografia especificadas na solicitação	Isso ocorre quando as configurações de criptografia da tabela de destino não correspondem às da sua solicitação. Como mitigação, use a disposição de gravação TRUNCATE para substituir a tabela ou especifique uma tabela de destino diferente.
Esta região não é compatível	A região da chave do Cloud KMS não corresponde à do conjunto de dados do BigQuery da tabela de destino. Como mitigação, selecione a chave em uma região que corresponda ao seu conjunto de dados ou carregue em um conjunto de dados que corresponda à região da chave.
Seu administrador exige que você especifique uma chave de criptografia para consultas no projeto PROJECT_ID.	Uma política da organização impediu a criação de um recurso ou a execução de uma consulta. Para saber mais sobre essa política, consulte Exigir CMEK para todos os recursos em um projeto do BigQuery.
O administrador impede o uso de chaves KMS do projeto KMS_PROJECT_ID para proteger recursos no projeto PROJECT_ID.	Uma política da organização impediu a criação de um recurso ou a execução de uma consulta. Para saber mais sobre essa política, consulte Restringir chaves do Cloud KMS para um projeto do BigQuery.