Esta página se ha traducido con Cloud Translation API.

Claves de Cloud KMS gestionadas por el cliente

De forma predeterminada, BigQuery encripta el contenido almacenado en reposo. BigQuery gestiona este cifrado predeterminado por ti sin que tengas que hacer nada más. En primer lugar, los datos de una tabla de BigQuery se cifran con una clave de cifrado de datos. A continuación, esas claves de encriptado de datos se encriptan con claves de encriptado de claves, lo que se conoce como encriptado envolvente. Las claves de cifrado de claves no cifran directamente tus datos, sino que se usan para cifrar las claves de cifrado de datos que Google usa para cifrar tus datos.

Si quieres controlar el cifrado, puedes usar claves de cifrado gestionadas por el cliente (CMEK) en BigQuery. En lugar de que Google sea el propietario y gestione las claves de cifrado de claves que protegen tus datos, tú controlas y gestionas las claves de cifrado de claves en Cloud KMS. En este documento se proporcionan detalles sobre cómo crear manualmente claves de Cloud KMS para BigQuery.

Consulta más información sobre las opciones de cifrado en Google Cloud. Para obtener información específica sobre las CMEK, incluidas sus ventajas y limitaciones, consulta el artículo Claves de cifrado gestionadas por el cliente.

Antes de empezar

Todos los recursos de datos que residen en el almacenamiento gestionado de BigQuery admiten CMEK. Sin embargo, si también consultas datos almacenados en una fuente de datos externa, como Cloud Storage, que tiene datos cifrados con CMEK, el cifrado de datos lo gestiona Cloud Storage. Por ejemplo, las tablas de BigLake admiten datos cifrados con CMEK en Cloud Storage.

BigQuery y las tablas de BigLake no admiten claves de cifrado proporcionadas por el cliente (CSEK).
Decide si vas a ejecutar BigQuery y Cloud KMS en el mismo proyecto o en proyectos diferentes. Google Cloud En los ejemplos de documentación, se utiliza la siguiente convención:
- PROJECT_ID: el ID del proyecto que ejecuta BigQuery
- PROJECT_NUMBER: el número del proyecto que ejecuta BigQuery
- KMS_PROJECT_ID: el ID del proyecto que ejecuta Cloud KMS (aunque sea el mismo proyecto que ejecuta BigQuery)
Para obtener información sobre los IDs y los números de proyecto, consulta el artículo sobre cómo identificar proyectos. Google Cloud
BigQuery se habilita automáticamente en los proyectos nuevos. Si vas a usar un proyecto que ya tengas para ejecutar BigQuery, habilita la API de BigQuery.
En el Google Cloud proyecto que ejecuta Cloud KMS, habilita la API de Cloud Key Management Service.

Se realiza una llamada de desencriptado mediante Cloud KMS una vez por cada consulta a una tabla encriptada con CMEK. Para obtener más información, consulta los precios de Cloud KMS.

Especificación de cifrado

Las claves de Cloud KMS que se usan para proteger tus datos en BigQuery son claves AES-256. Estas claves se utilizan como claves de cifrado de claves en BigQuery, ya que cifran las claves de cifrado de datos que cifran tus datos.

Creación de claves manual o automática

Puedes crear tus claves CMEK manualmente o usar Autokey de Cloud KMS. Autokey simplifica la creación y la gestión de tus claves CMEK automatizando el aprovisionamiento y la asignación. Con Autokey, no tienes que aprovisionar llaveros de claves, claves ni cuentas de servicio con antelación. En su lugar, se generan a petición como parte de la creación de recursos de BigQuery. Para obtener más información, consulta el resumen de Autokey.

Crear manualmente un conjunto de claves y una clave

En el Google Cloud proyecto que ejecuta Cloud KMS, crea un conjunto de claves y una clave tal como se describe en Crear conjuntos de claves y claves. Crea el conjunto de claves en una ubicación que coincida con la de tu conjunto de datos de BigQuery:

Cualquier conjunto de datos multirregional debe usar un conjunto de claves multirregional de una ubicación coincidente. Por ejemplo, un conjunto de datos de la región US debe protegerse con un conjunto de claves de la región us, y un conjunto de datos de la región EU debe protegerse con un conjunto de claves de la región europe.
Los conjuntos de datos regionales deben usar claves regionales coincidentes. Por ejemplo, un conjunto de datos de la región asia-northeast1 debe protegerse con un conjunto de claves de la región asia-northeast1.
No puedes usar la región global al configurar CMEK para BigQuery en la consola de Google Cloud . Sin embargo, puede usar la región global al configurar CMEK para BigQuery con la herramienta de línea de comandos bq o GoogleSQL.

Para obtener más información sobre las ubicaciones admitidas de BigQuery y Cloud KMS, consulta Ubicaciones de Cloud.

Conceder permiso de cifrado y descifrado

Para proteger tus datos de BigQuery con una clave CMEK, concede a la cuenta de servicio de BigQuery permiso para cifrar y descifrar con esa clave. El rol Encargado del encriptado y desencriptado de la clave criptográfica Cloud KMS otorga este permiso.

Asegúrate de que se ha creado tu cuenta de servicio y, a continuación, usa laGoogle Cloud consola para determinar el ID de la cuenta de servicio de BigQuery. A continuación, asigna a la cuenta de servicio el rol adecuado para cifrar y descifrar con Cloud KMS.

Activar la creación de tu cuenta de servicio

Tu cuenta de servicio de BigQuery no se crea inicialmente cuando creas un proyecto. Para activar la creación de tu cuenta de servicio, introduce un comando que la utilice, como el comando bq show --encryption_service_account, o llama al método de la API projects.getServiceAccount. Por ejemplo:

bq show --encryption_service_account --project_id=PROJECT_ID

Determinar el ID de la cuenta de servicio

El ID de la cuenta de servicio de BigQuery tiene el siguiente formato:

bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com

En las siguientes técnicas se muestra cómo determinar el ID de la cuenta de servicio de BigQuery de tu proyecto.

Consola

Ve a la página Panel de control de la Google Cloud consola.

Ir a la página Panel de control
En la parte superior de la página, haz clic en la lista desplegable Seleccionar de. En la ventana Seleccionar de que aparece, selecciona tu proyecto.
Tanto el ID como el número del proyecto se muestran en la tarjeta Información del proyecto del panel de control del proyecto:
En la siguiente cadena, sustituye PROJECT_NUMBER por el número de tu proyecto. La nueva cadena identifica el ID de tu cuenta de servicio de BigQuery.
```
bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com
```

bq

Usa el comando bq show con la marca --encryption_service_account para determinar el ID de la cuenta de servicio:

bq show --encryption_service_account

El comando muestra el ID de la cuenta de servicio:

                  ServiceAccountID
-------------------------------------------------------------
bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com

Asignar el rol Encrypter/Decrypter

Asigna el rol Encargado del encriptado y desencriptado de la clave criptográfica Cloud KMS a la cuenta de servicio del sistema de BigQuery que has copiado en el portapapeles. Esta cuenta tiene el siguiente formato:

bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com

Consola

Abre la página Claves criptográficas en la Google Cloud consola.
Abre la página Claves criptográficas
Haga clic en el nombre del conjunto de claves que contiene la clave.
Haz clic en la casilla de verificación de la clave de cifrado a la que quieras añadir el rol. Se abrirá la pestaña Permisos.
Haz clic en Añadir miembro.
Introduce la dirección de correo de la cuenta de servicio, bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com.
- Si la cuenta de servicio ya está en la lista de miembros, tiene roles asignados. Haz clic en la lista desplegable del rol actual de la cuenta de servicio bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com.
Haz clic en la lista desplegable Seleccionar un rol, en Cloud KMS y, a continuación, en el rol Encargado del encriptado y desencriptado de la clave criptográfica Cloud KMS.
Haz clic en Guardar para aplicar el rol a la cuenta de servicio bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com.

gcloud

Puedes usar Google Cloud CLI para asignar el rol:

gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member serviceAccount:bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY

Haz los cambios siguientes:

KMS_PROJECT_ID: el ID de tu Google Cloud proyecto que ejecuta Cloud KMS
PROJECT_NUMBER: el número de proyecto (no el ID de proyecto) de tu Google Cloud proyecto que ejecuta BigQuery
KMS_KEY_LOCATION: el nombre de la ubicación de tu clave de Cloud KMS
KMS_KEY_RING: el nombre del conjunto de claves de tu clave de Cloud KMS
KMS_KEY: el nombre de clave de tu clave de Cloud KMS

ID de recurso de clave

El ID de recurso de la clave de Cloud KMS es obligatorio para usar la CMEK, tal como se muestra en los ejemplos. Esta clave distingue entre mayúsculas y minúsculas, y tiene el siguiente formato:

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

Obtener el ID de recurso de la clave

Abre la página Claves criptográficas en la Google Cloud consola.
Abre la página Claves criptográficas
Haga clic en el nombre del conjunto de claves que contiene la clave.
En la clave cuyo ID de recurso quieras obtener, haz clic en Más .
Haz clic en Copiar nombre de recurso. El ID del recurso de la clave se copia en el portapapeles. El ID de recurso también se conoce como nombre de recurso.

Crear una tabla protegida con Cloud KMS

Para crear una tabla protegida con Cloud KMS, sigue estos pasos:

Consola

Abre la página de BigQuery en la Google Cloud consola.

Ir a la página de BigQuery
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
Abre la opción Acciones y haz clic en Abrir.
En el panel de detalles, haz clic en Crear tabla .
En la página Crear tabla, rellena la información necesaria para crear una tabla vacía con una definición de esquema. Antes de hacer clic en Crear tabla, define el tipo de cifrado y especifica la clave de Cloud KMS que se va a usar con la tabla:
1. Haz clic en Advanced options (Opciones avanzadas).
2. Haz clic en Clave gestionada por el cliente.
3. Selecciona la llave. Si la clave que quieres usar no aparece en la lista, introduce su ID de recurso.
Haz clic en Crear tabla.

SQL

Usa la instrucción CREATE TABLE con la opción kms_key_name:

En la Google Cloud consola, ve a la página BigQuery.

Ir a BigQuery

En el editor de consultas, introduce la siguiente instrucción:

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');

Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Puedes usar la herramienta de línea de comandos bq con la marca --destination_kms_key para crear la tabla. La marca --destination_kms_key especifica el ID de recurso de la clave que se va a usar con la tabla.

Para crear una tabla vacía con un esquema, sigue estos pasos:

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 crear una tabla a partir de una consulta, sigue estos pasos:

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 obtener más información sobre la herramienta de línea de comandos bq, consulta el artículo Usar la herramienta de línea de comandos bq.

Terraform

Usa el recurso google_bigquery_table.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configurar la autenticación para bibliotecas de cliente.

En el ejemplo siguiente se crea una tabla llamada mytable y también se usan los recursos google_kms_crypto_key y google_kms_key_ring para especificar una clave de Cloud Key Management Service para la tabla.

Para ejecutar este ejemplo, debes habilitar la API Cloud Resource Manager y la 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 la configuración de Terraform en un proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

Abre Cloud Shell.
Define el Google Cloud proyecto Google Cloud predeterminado en el que quieras aplicar tus configuraciones de Terraform.

Solo tiene que ejecutar este comando una vez por proyecto y puede hacerlo en cualquier directorio.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

En Cloud Shell, crea un directorio y un archivo nuevo en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

Copia el código de ejemplo en el archivo main.tf que acabas de crear.

También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.
Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
Guarda los cambios.
Inicializa Terraform. Solo tienes que hacerlo una vez por directorio.
```
terraform init
```
Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade:
```
terraform init -upgrade
```

Aplica los cambios

Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas:
```
terraform plan
```
Haga las correcciones necesarias en la configuración.
Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición:
```
terraform apply
```
Espera hasta que Terraform muestre el mensaje "Apply complete!".
Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para asegurarte de que Terraform los ha creado o actualizado.

Go

Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación 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 probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

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 probar este ejemplo, sigue las Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Protege una tabla nueva con una clave de cifrado gestionada por el cliente. Para ello, asigna a la propiedad Table.encryption_configuration un objeto EncryptionConfiguration antes de crear la tabla.

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 una tabla protegida por una clave de Cloud KMS

No es necesario configurar nada especial para consultar una tabla protegida por Cloud KMS. BigQuery almacena el nombre de la clave usada para cifrar el contenido de la tabla y usa esa clave cuando se consulta una tabla protegida por Cloud KMS.

Todas las herramientas, la consola de BigQuery y la herramienta de línea de comandos bq funcionan igual que con las tablas cifradas de forma predeterminada, siempre que BigQuery tenga acceso a la clave de Cloud KMS utilizada para cifrar el contenido de la tabla.

Proteger los resultados de las consultas con una clave de Cloud KMS

De forma predeterminada, los resultados de las consultas se almacenan en una tabla temporal cifrada con una Google-owned and Google-managed encryption key. Si el proyecto ya tiene una clave predeterminada, se aplica a la tabla de resultados de la consulta temporal (predeterminada). Para usar una clave de Cloud KMS para encriptar los resultados de la consulta, selecciona una de las siguientes opciones:

Consola

Abre la página de BigQuery en la Google Cloud consola.

Ir a la página de BigQuery
Haz clic en Redactar nueva consulta.
Introduce una consulta de GoogleSQL válida en el área de texto de la consulta.
Haz clic en Más, Configuración de la consulta y, a continuación, Opciones avanzadas.
Selecciona Cifrado gestionado por el cliente.
Selecciona la llave. Si la clave que quieres usar no aparece en la lista, introduce su ID de recurso.
Haz clic en Guardar.
Haz clic en Ejecutar.

bq

Especifica la marca --destination_kms_key para proteger la tabla de destino o los resultados de la consulta (si usas una tabla temporal) con tu clave de Cloud KMS. La marca --destination_kms_key especifica el ID de recurso de la clave que se va a usar con el destino o la tabla resultante.

También puede usar la marca --destination_table para especificar el destino de los resultados de la consulta. Si no se usa --destination_table, los resultados de la consulta se escriben en una tabla temporal.

Para consultar una tabla, sigue estos pasos:

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 obtener más información sobre la herramienta de línea de comandos bq, consulta el artículo Usar la herramienta de línea de comandos bq.

Go

Protege una tabla nueva con una clave de cifrado gestionada por el cliente. Para ello, asigna a la propiedad Table.encryption_configuration un objeto EncryptionConfiguration antes de crear la tabla.

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

Protege una tabla nueva con una clave de cifrado gestionada por el cliente. Para ello, asigna a la propiedad Table.encryption_configuration un objeto EncryptionConfiguration antes de crear la tabla.

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

Para proteger una tabla de destino de una consulta con una clave de encriptado gestionada por el cliente, asigna a la propiedad QueryJobConfig.destination_encryption_configuration un objeto EncryptionConfiguration y ejecuta la 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")

Cargar una tabla protegida con Cloud KMS

Para cargar un archivo de datos en una tabla protegida por Cloud KMS, sigue estos pasos:

Consola

Protege una tabla de destino de una tarea de carga con una clave de cifrado gestionada por el cliente. Para ello, especifica la clave al cargar la tabla.

Abre la página de BigQuery en la Google Cloud consola.

Ir a la página de BigQuery
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
En el panel de detalles, haz clic en Crear tabla.
Introduce las opciones que quieras usar para cargar la tabla, pero antes de hacer clic en Crear tabla, haz clic en Opciones avanzadas.
En Cifrado, selecciona Clave gestionada por el cliente.
Haz clic en la lista desplegable Seleccionar una clave gestionada por el cliente y elige la clave que quieras usar. Si no ves ninguna clave disponible, introduce un ID de recurso de clave.
Haz clic en Crear tabla.

bq

Protege una tabla de destino de un trabajo de carga con una clave de encriptado gestionada por el cliente definiendo la marca --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 ejemplo:

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

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

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

Para proteger una tabla de destino de una tarea de carga con una clave de encriptado gestionada por el cliente, asigna a la propiedad LoadJobConfig.destination_encryption_configuration un objeto EncryptionConfiguration y carga la tabla.

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")

Insertar datos en una tabla protegida con Cloud KMS

Puedes transmitir datos a tu tabla de BigQuery protegida con CMEK sin especificar ningún parámetro adicional. Ten en cuenta que estos datos se cifran con tu clave de Cloud KMS en el búfer y en la ubicación final. Antes de usar la transmisión con una tabla CMEK, consulta los requisitos sobre la disponibilidad y la accesibilidad de las claves.

Consulta más información sobre la transmisión en Transmisión de datos mediante la API Storage Write de BigQuery.

Cambiar el encriptado predeterminado de una tabla por la protección con Cloud KMS

bq

Puedes usar el comando bq cp con la marca --destination_kms_key para copiar una tabla protegida con el encriptado predeterminado en una tabla nueva o en la tabla original, protegida con Cloud KMS. La marca --destination_kms_key especifica el ID de recurso de la clave que se va a usar con la tabla de destino.

Para copiar una tabla con encriptado predeterminado en una tabla nueva con protección de Cloud KMS, sigue estos pasos:

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

Si quieres copiar una tabla que tiene el encriptado predeterminado en la misma tabla con protección de Cloud KMS, sigue estos pasos:

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

Si quieres cambiar la protección de una tabla de Cloud KMS al encriptado predeterminado, copia el archivo en sí mismo ejecutando bq cp sin usar la marca --destination_kms_key.

Para obtener más información sobre la herramienta de línea de comandos bq, consulta el artículo Usar la herramienta de línea de comandos bq.

Go

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

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

Protege el destino de una copia de una tabla con una clave de cifrado gestionada por el cliente. Para ello, asigna a la propiedad QueryJobConfig.destination_encryption_configuration el valor EncryptionConfiguration y copia la tabla.

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 si una tabla está protegida por Cloud KMS

En la Google Cloud consola, haz clic en la flecha azul situada a la izquierda de tu conjunto de datos para desplegarlo o haz doble clic en el nombre del conjunto de datos. Se muestran las tablas y las vistas del conjunto de datos.
Haz clic en el nombre de la tabla.
Haz clic en Detalles. En la página Detalles de la tabla se muestra la descripción y la información de la tabla.
Si la tabla está protegida por Cloud KMS, el campo Clave de cifrado gestionada por el cliente muestra el ID de recurso de la clave.

En cada una de las claves que hayas creado o que protejan tus tablas, puedes ver qué recursos protege la clave con el seguimiento del uso de claves. Para obtener más información, consulta Ver el uso de las claves.

Cambiar la clave de Cloud KMS de una tabla de BigQuery

Para cambiar la clave de Cloud KMS de una tabla protegida con CMEK, puedes ejecutar una consulta ALTER TABLE, usar la API o usar la herramienta de línea de comandos bq. Hay dos formas de modificar la clave de Cloud KMS con la API y la herramienta de línea de comandos bq: update o cp.

Si usas update, puedes cambiar la clave de Cloud KMS que se usa en una tabla protegida por CMEK.

Si usas cp, puedes cambiar la clave de Cloud KMS que se usa en una tabla protegida con CMEK, cambiar una tabla del cifrado predeterminado a la protección con CMEK o cambiar una tabla de la protección con CMEK al cifrado predeterminado.

Una de las ventajas de update es que es más rápido que cp y te permite usar decoradores de tablas.

SQL

Usa la declaración ALTER TABLE SET OPTIONS para actualizar el campo kms_key_name de una tabla:

En la Google Cloud consola, ve a la página BigQuery.

Ir a BigQuery

En el editor de consultas, introduce la siguiente instrucción:

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

Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Puedes usar el comando bq cp con la marca --destination_kms_key para cambiar la clave de una tabla protegida por Cloud KMS. La marca --destination_kms_key especifica el ID de recurso de la clave que se va a usar con la tabla.

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

Go

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

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

Para cambiar la clave de encriptado gestionada por el cliente de una tabla, cambia la propiedad Table.encryption_configuration a un nuevo objeto EncryptionConfiguration y actualiza la tabla.

# 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 una clave predeterminada de un conjunto de datos

Puedes definir una clave de Cloud KMS predeterminada para todo el conjunto de datos que se aplique a todas las tablas que se creen en él, a menos que se especifique otra clave de Cloud KMS al crear la tabla. La clave predeterminada no se aplica a las tablas ya creadas. Al cambiar la clave predeterminada, no se modifican las tablas y solo se aplica a las tablas nuevas que se creen después del cambio.

Puedes aplicar, cambiar o quitar una clave predeterminada de un conjunto de datos de las siguientes formas:

especificando la clave predeterminada en el campo EncryptionConfiguration.kmsKeyName cuando llames a los métodos datasets.insert o datasets.patch

especificando la clave predeterminada en la marca --default_kms_key al ejecutar el 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

Definir una clave predeterminada de proyecto

Puedes definir claves de Cloud KMS predeterminadas para el proyecto que se apliquen a todos los resultados de las consultas y a las tablas recién creadas en el proyecto de esa ubicación, a menos que especifiques otra clave de Cloud KMS. La clave predeterminada no se aplica a las tablas que ya existen. Al cambiar la clave predeterminada, no se modifican las tablas y solo se aplica a las tablas nuevas que se creen después del cambio.

SQL

Usa la instrucción ALTER PROJECT SET OPTIONS para actualizar el campo default_kms_key_name de un proyecto. Puedes encontrar el nombre del recurso de la clave en la página de Cloud KMS.

En la Google Cloud consola, ve a la página BigQuery.

Ir a BigQuery

En el editor de consultas, introduce la siguiente instrucción:

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

Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Puedes usar el comando bq para ejecutar una instrucción ALTER PROJECT SET OPTIONS y actualizar el campo default_kms_key_name de un proyecto:

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 de BigQuery ML

BigQuery ML admite CMEK. Además del cifrado predeterminado que ofrece BigQuery, puedes usar tus propias claves de Cloud Key Management Service para cifrar modelos de aprendizaje automático, incluidos los modelos de TensorFlow importados.

Crear un modelo cifrado con una clave de Cloud KMS

Para crear un modelo cifrado, usa la instrucción CREATE MODEL y especifica KMS_KEY_NAME en las opciones de entrenamiento:

    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

La misma sintaxis también se aplica a los modelos de TensorFlow importados:

    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

Limitaciones

Las claves de encriptado gestionadas por el cliente tienen las siguientes restricciones al encriptar modelos de aprendizaje automático:

No se admiten las claves de CMEK de la región Global para los siguientes tipos de modelos:
No se admiten las claves CMEK de la región Global ni las claves CMEK multirregionales, como EU o US, al crear los siguientes tipos de modelos:
- Modelos de AutoML Tables
Las claves de CMEK no se admiten en los modelos remotos:

Cambiar el cifrado predeterminado de un modelo por la protección con Cloud KMS

Puedes usar el comando bq cp con la marca --destination_kms_key para copiar un modelo protegido por el encriptado predeterminado en un modelo nuevo protegido por Cloud KMS. También puedes usar el comando bq cp con la marca -f para sobrescribir un modelo protegido con el cifrado predeterminado y actualizarlo para que use la protección de Cloud KMS. La marca --destination_kms_key especifica el ID de recurso de la clave que se va a usar con el modelo de destino.

Para copiar un modelo que tenga el encriptado predeterminado en un modelo nuevo que tenga protección con Cloud KMS, sigue estos pasos:

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 sobrescribir un modelo que tiene el cifrado predeterminado con el mismo modelo protegido con Cloud KMS, sigue estos pasos:

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 cambiar un modelo de la protección con Cloud KMS al cifrado predeterminado, sigue estos pasos:

bq cp -f \
DATASET_ID.MODEL_ID DATASET_ID.MODEL_ID

Para obtener más información sobre la herramienta de línea de comandos bq, consulta el artículo Usar la herramienta de línea de comandos bq.

Determinar si un modelo está protegido por Cloud KMS

Usa el comando bq show para ver si un modelo está protegido por una clave de Cloud KMS. La clave de cifrado se encuentra en el campo kmsKeyName.

bq show -m my_dataset.my_model

También puedes usar la Google Cloud consola para encontrar la clave de Cloud KMS de un modelo cifrado. La información de CMEK se encuentra en el campo Clave gestionada por el cliente de la sección Detalles del modelo del panel Detalles del modelo.

Cambiar la clave de Cloud KMS de un modelo cifrado

Usa el comando bq update con la marca --destination_kms_key para cambiar la clave de un modelo protegido por 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 las claves de proyecto o de conjunto de datos predeterminadas

Si tienes una clave de Cloud KMS predeterminada definida a nivel de proyecto o de conjunto de datos, BigQuery ML la usará automáticamente al crear modelos. Usa la instrucción CREATE MODEL para especificar otra clave con la que cifrar el modelo si no quieres usar la clave predeterminada.

Usar funciones de BigQuery ML con modelos cifrados

Puedes usar todas las funciones de BigQuery ML con un modelo cifrado sin especificar una clave de cifrado.

Usar CMEK para proteger la API Connection de BigQuery

En el caso de las conexiones de Cloud SQL, puedes proteger tus credenciales de la API Connection de BigQuery con CMEK.

Para obtener más información sobre cómo crear una conexión protegida con CMEK, consulta Crear conexiones de Cloud SQL.

Quitar el acceso de BigQuery a la clave de Cloud KMS

Puedes quitar el acceso de BigQuery a la clave de Cloud KMS en cualquier momento. Para ello, revoca el permiso de Gestión de Identidades y Accesos (IAM) de esa clave.

Si BigQuery pierde el acceso a la clave de Cloud KMS, la experiencia del usuario puede verse afectada de forma significativa y se pueden perder datos:

Ya no se podrá acceder a los datos de estas tablas protegidas con CMEK: query, cp, extract y tabledata.list fallarán.
No se pueden añadir datos nuevos a estas tablas protegidas con CMEK.
Una vez que se haya restaurado el acceso, el rendimiento de las consultas a estas tablas puede verse afectado durante varios días.

Controlar el uso de CMEK con la política de organización

BigQuery se integra con las restricciones de la política de la organización de CMEK para que puedas especificar los requisitos de cumplimiento de cifrado de los recursos de BigQuery de tu organización.

Esta integración te permite hacer lo siguiente:

Requerir CMEKs para todos los recursos de BigQuery de un proyecto.
Restringe las claves de Cloud KMS que se pueden usar para proteger los recursos de un proyecto.

Requerir CMEKs para todos los recursos

Una política habitual es requerir que se usen CMEKs para proteger todos los recursos de un conjunto específico de proyectos. Puede usar la restricción constraints/gcp.restrictNonCmekServices para aplicar esta política en BigQuery.

Si se define, esta política de organización provoca que fallen todas las solicitudes de creación de recursos sin una clave de Cloud KMS especificada.

Una vez que hayas configurado esta política, solo se aplicará a los recursos nuevos del proyecto. Los recursos que ya tengas y que no tengan claves de Cloud KMS seguirán existiendo y se podrá acceder a ellos sin problemas.

Consola

Abre la página Políticas de la organización.

Ir a Políticas de organización
En el campo Filtro, introduzca constraints/gcp.restrictNonCmekServices y, a continuación, haga clic en Restringir qué servicios pueden crear recursos sin CMEK.
Haz clic en Editar.
Selecciona Personalizar, Sustituir y, a continuación, Añadir regla.
Selecciona Personalizado y, a continuación, haz clic en Denegar.
En el campo Valor personalizado, introduce is:bigquery.googleapis.com.
Haz clic en Hecho y, a continuación, en Guardar.

gcloud

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

Para verificar que la política se ha aplicado correctamente, puedes intentar crear una tabla en el proyecto. El proceso falla a menos que especifiques una clave de Cloud KMS.

Esta política también se aplica a las tablas de resultados de las consultas del proyecto. Puedes especificar una clave predeterminada del proyecto para que los usuarios no tengan que especificar manualmente una clave cada vez que ejecuten una consulta en el proyecto.

Restringir las claves de Cloud KMS de un proyecto de BigQuery

Puedes usar la restricción constraints/gcp.restrictCmekCryptoKeyProjects para limitar las claves de Cloud KMS que puedes usar para proteger un recurso en un proyecto de BigQuery.

Por ejemplo, puedes especificar una regla como "Para todos los recursos de BigQuery del proyecto projects/my-company-data-project, las claves de Cloud KMS que se usen en este proyecto deben proceder de projects/my-company-central-keys O projects/team-specific-keys".

Consola

Abre la página Políticas de la organización.

Ir a Políticas de organización
En el campo Filtro, introduce constraints/gcp.restrictCmekCryptoKeyProjects y, a continuación, haz clic en Restringe los proyectos que pueden proporcionar CryptoKeys de KMS para CMEK.
Haz clic en Editar.
Selecciona Personalizar, Sustituir y, a continuación, Añadir regla.
Selecciona Personalizada y, a continuación, haz clic en Permitir.
En el campo Valor personalizado, introduce under:projects/<var>KMS_PROJECT_ID</var>.
Haz clic en Hecho y, a continuación, en Guardar.

gcloud

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

Para verificar que la política se ha aplicado correctamente, puedes intentar crear una tabla con una clave de Cloud KMS de otro proyecto. El proceso fallará.

Limitaciones de las políticas de organización

Hay limitaciones asociadas a la configuración de una política de organización.

Retraso de propagación

Después de definir o actualizar una política de la organización, la nueva política puede tardar hasta 15 minutos en aplicarse. BigQuery almacena en caché las políticas para no afectar negativamente a la latencia de creación de consultas y tablas.

Permisos necesarios para definir una política de organización

Puede que sea difícil obtener el permiso para definir o actualizar la política de la organización con fines de prueba. Debes tener el rol Administrador de políticas de la organización, que solo se puede asignar a nivel de organización (no a nivel de proyecto o carpeta).

Aunque el rol debe concederse a nivel de organización, sigue siendo posible especificar una política que solo se aplique a un proyecto o una carpeta concretos.

Impacto de la rotación de claves de Cloud KMS

BigQuery no rota automáticamente la clave de cifrado de una tabla cuando se rota la clave de Cloud KMS asociada con esa tabla. Todos los datos de las tablas disponibles seguirán protegidos por la versión de clave con la que se crearon.

Las tablas que se creen usarán la versión de la clave principal en el momento de su creación.

Para actualizar una tabla y usar la versión de clave más reciente, actualízala con la misma clave de Cloud KMS. Esta actualización no comprobará ninguna política de la organización. Solo se comprobará la política de la organización si se actualiza la clave.

Repercusión en la facturación de Cloud KMS

Cuando creas o truncas una tabla protegida con CMEK, BigQuery genera una clave de cifrado de clave intermedia que se cifra con la clave de Cloud KMS especificada.

A efectos de facturación, esto significa que ni tus llamadas a Cloud KMS ni los costes asociados se escalan con el tamaño de la tabla. En el caso de las tablas protegidas con claves CMEK, se realizará una llamada a Cloud KMS cryptoKeys.encrypt por cada creación o truncamiento de tabla y una llamada a Cloud KMS cryptoKeys.decrypt por cada tabla incluida en una consulta. Ambos métodos pertenecen a la categoría Operaciones con claves: criptográficas, que se indica en la página Precios de Cloud KMS.

Al leer o escribir en una tabla protegida con CMEK, se invoca Cloud KMS cryptoKeys.decrypt porque la clave intermedia debe descifrarse.

Limitaciones

Acceso de BigQuery a la clave de Cloud KMS

BigQuery considera que una clave de Cloud KMS está disponible y es accesible en las siguientes condiciones:

La clave está habilitada
La cuenta de servicio de BigQuery tiene permisos de cifrado y descifrado en la clave.

En las secciones siguientes se describe el impacto en las inserciones de streaming y en los datos inaccesibles a largo plazo cuando una clave no está disponible.

Impacto en las inserciones de transmisión

La clave de Cloud KMS debe estar disponible y accesible durante al menos 24 horas consecutivas en el periodo de 48 horas posterior a una solicitud de inserción de streaming. Si la clave no está disponible y no se puede acceder a ella, es posible que los datos transmitidos no se conserven por completo y se pierdan. Para obtener más información sobre las inserciones en tiempo real, consulta el artículo Transmisión de datos en BigQuery.

Impacto en los datos inaccesibles a largo plazo

Como BigQuery proporciona almacenamiento gestionado, los datos inaccesibles a largo plazo no son compatibles con la arquitectura de BigQuery. Si la clave de Cloud KMS de una tabla de BigQuery determinada no está disponible y no se puede acceder a ella durante 60 días consecutivos, BigQuery puede eliminar la tabla y los datos asociados. Al menos 7 días antes de que se eliminen los datos, BigQuery envía un correo a la dirección asociada a la cuenta de facturación.

Utilizar fuentes de datos externas

Si consultas datos almacenados en una fuente de datos externa, como Cloud Storage, que tiene datos cifrados con CMEK, el cifrado de datos lo gestiona Cloud Storage. Por ejemplo, las tablas de BigLake admiten datos cifrados con CMEK en Cloud Storage.

BigQuery y las tablas de BigLake no admiten claves de cifrado proporcionadas por el cliente (CSEK).

Cambiar entre el encriptado predeterminado y el protegido con CMEK

No puedes cambiar una tabla in situ entre el cifrado predeterminado y el cifrado con CMEK. Para cambiar el cifrado, copia la tabla con la información de cifrado de destino definida o usa una consulta SELECT * para seleccionar la tabla en sí misma con la disposición WRITE_TRUNCATE.

Usar decoradores de tabla

Si proteges una tabla con Cloud KMS y, a continuación, sustituyes los datos de la tabla mediante el valor WRITE_TRUNCATE en una operación load, cp o query, los decoradores de intervalo no funcionarán en el límite del cambio de cifrado. Puedes seguir usando decoradores de tabla, incluidos los de intervalo, para consultar los datos antes o después del límite, o bien para consultar la instantánea en un momento concreto.

Consultas de tablas comodín

Las tablas protegidas con CMEK no se pueden consultar con un sufijo de comodín.

Compatibilidad con secuencias de comandos

Las secuencias de comandos no pueden definir tablas de destino para las operaciones de CMEK.

Ediciones compatibles

La compatibilidad con CMEK en BigQuery solo está disponible en BigQuery Enterprise, BigQuery Enterprise Plus y BigQuery On-Demand.

Compatibilidad con BigQuery Studio

Los recursos de código de BigQuery Studio, incluidas las consultas guardadas y los cuadernos, no admiten CMEK.

Preguntas frecuentes

¿Quién necesita permiso para acceder a la clave de Cloud KMS?

Con las claves de encriptado gestionadas por el cliente, no es necesario especificar los permisos repetidamente. Siempre que la cuenta de servicio de BigQuery tenga permiso para usar la clave de Cloud KMS para cifrar y descifrar, cualquier persona con permiso para acceder a la tabla de BigQuery podrá acceder a los datos, aunque no tenga acceso directo a la clave de Cloud KMS.

¿Qué cuenta de servicio se usa?

La cuenta de servicio de BigQuery asociada alGoogle Cloud proyecto de la tabla se usa para descifrar los datos de esa tabla. Las cuentas de servicio de BigQuery son únicas para cada proyecto. En el caso de un trabajo que escribe datos en una tabla anónima protegida con Cloud KMS, se usa la cuenta de servicio del proyecto del trabajo.

Por ejemplo, supongamos que tienes tres tablas protegidas con CMEK: table1, table2 y table3. Para consultar datos de {project1.table1, project2.table2} con la tabla de destino {project3.table3}, sigue estos pasos:

Usar la cuenta de servicio project1 para project1.table1
Usar la cuenta de servicio project2 para project2.table2
Usar la cuenta de servicio project3 para project3.table3

¿De qué formas puede usar BigQuery mi clave de Cloud KMS?

BigQuery usa la clave de Cloud KMS para descifrar los datos en respuesta a una consulta de usuario, por ejemplo, tabledata.list o jobs.insert.

BigQuery también puede usar la clave para tareas de mantenimiento y optimización del almacenamiento de datos, como la conversión de datos a un formato optimizado para lectura.

¿Qué bibliotecas de criptografía se usan?

BigQuery usa Cloud KMS para la funcionalidad de CMEK. Cloud KMS usa Tink para el cifrado.

¿Cómo puedo obtener más ayuda?

Si tienes alguna duda que no se responde aquí, consulta la página de asistencia de BigQuery.

Solucionar errores

A continuación, se describen los errores habituales y las mitigaciones recomendadas.

Error	Recomendación
Concede el rol Encargado del encriptado y desencriptado de la clave criptográfica Cloud KMS	La cuenta de servicio de BigQuery asociada a tu proyecto no tiene permisos de gestión de identidades y accesos suficientes para operar en la clave de Cloud KMS especificada. Sigue las instrucciones que se indican en el error o en esta documentación para conceder el permiso de IAM adecuado.
La configuración de cifrado de la tabla no coincide con la especificada en la solicitud	Esto puede ocurrir en situaciones en las que la tabla de destino tenga ajustes de cifrado que no coincidan con los de tu solicitud. Como medida de mitigación, usa la disposición de escritura `TRUNCATE` para sustituir la tabla o especifica otra tabla de destino.
Esta región no se admite	La región de la clave de Cloud KMS no coincide con la región del conjunto de datos de BigQuery de la tabla de destino. Como medida de mitigación, selecciona una clave de una región que coincida con tu conjunto de datos o carga los datos en un conjunto de datos que coincida con la región de la clave.
Tu administrador requiere que especifiques una clave de cifrado para las consultas del proyecto `PROJECT_ID.`	Una política de la organización ha impedido crear un recurso o ejecutar una consulta. Para obtener más información sobre esta política, consulta Requerir CMEKs para todos los recursos de un proyecto de BigQuery.
Tu administrador impide el uso de claves de KMS del proyecto `KMS_PROJECT_ID` para proteger los recursos del proyecto `PROJECT_ID`.	Una política de la organización ha impedido crear un recurso o ejecutar una consulta. Para obtener más información sobre esta política, consulta Restringir las claves de Cloud KMS a un proyecto de BigQuery.