Protéger les données avec des clés Cloud KMS

Par défaut, BigQuery chiffre le contenu client stocké au repos, puis traite et gère ce chiffrement sans aucune action supplémentaire de votre part. Les données d'une table BigQuery sont tout d'abord chiffrées à l'aide de clés de chiffrement de données. Ces clés sont ensuite chiffrées par des clés de chiffrement de clés, dans le cadre du processus appelé chiffrement encapsulé. Les clés de chiffrement de clés ne chiffrent pas directement les données, mais plutôt les clés de chiffrement de données utilisées par Google pour les chiffrer. Pour en savoir plus, consultez la section Gestion des clés.

Si vous souhaitez contrôler vous-même le chiffrement, vous pouvez utiliser des clés gérées par le client (CMEK, Customer-Managed Encryption Keys) pour BigQuery. Au lieu de laisser Google gérer les clés de chiffrement de clés qui protègent vos données, c'est vous qui vous chargez de cette tâche dans Cloud KMS. Cet article décrit en détail cette technique.

Découvrez les options de chiffrement disponibles dans Google Cloud.

Avant de commencer

  1. Assurez-vous de bien comprendre le fonctionnement des ensembles de données, des tables et des requêtes.

  2. Déterminez si vous allez exécuter BigQuery et Cloud KMS dans le même projet Google Cloud ou dans des projets différents. Dans cette documentation, voici les conventions qui sont utilisées :

    • PROJECT_ID : ID du projet exécutant BigQuery
    • PROJECT_NUMBER : numéro du projet exécutant BigQuery
    • KMS_PROJECT_ID : ID du projet exécutant Cloud KMS (même s'il correspond également au projet exécutant BigQuery)
    Pour en savoir plus sur les ID et numéros de projet Cloud, consultez la section Identifier des projets.

  3. BigQuery est automatiquement activé dans les nouveaux projets. Si vous exécutez BigQuery à partir d'un projet préexistant, activez l'API BigQuery.

  4. Pour le projet Cloud qui exécute Cloud KMS, procédez comme suit :

    1. Activez l'API Cloud Key Management Service.
    2. Créez un trousseau de clés ainsi qu'une clé en suivant la procédure décrite à la section Créer des trousseaux de clés et des clés. Créez le trousseau de clés dans le même emplacement que celui de votre ensemble de données BigQuery :
      • Les ensembles de données multirégionaux doivent utiliser un trousseau de clés multirégional issu du même emplacement. Par exemple, un ensemble de données situé dans la région US doit être protégé par un trousseau de clés de la région us. De même, un ensemble de données se trouvant dans la région EU doit être protégé par un trousseau de clés de la région europe.
      • Les ensembles de données régionaux doivent utiliser des clés régionales correspondantes. Par exemple, un ensemble de données dans la région asia-northeast1 doit être protégé par un trousseau de clés de la région asia-northeast1.
      • La région global n'est pas compatible avec BigQuery.
      Pour en savoir plus sur les emplacements compatibles avec BigQuery et Cloud KMS, consultez la section Emplacements cloud.

Spécification du chiffrement

Les clés Cloud KMS qui servent à protéger les données dans BigQuery sont des clés de type AES-256. Elles servent de clés de chiffrement de clés dans BigQuery, dans la mesure où elles chiffrent les clés de chiffrement de données qui chiffrent les données.

Accorder une autorisation de chiffrement et de déchiffrement

Pour protéger vos données BigQuery à l'aide d'une clé CMEK, accordez au compte de service BigQuery l'autorisation de chiffrer et de déchiffrer des données à l'aide de cette clé. Le rôle Chiffreur/Déchiffreur de CryptoKeys Cloud KMS accorde cette autorisation.

Dans la Google Cloud Console, identifiez l'ID du compte de service BigQuery afin d'accorder à ce compte le rôle nécessaire au chiffrement et au déchiffrement à l'aide de Cloud KMS.

Identifier l'ID du compte de service

L'ID du compte de service BigQuery se présente sous la forme suivante :

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

Les techniques suivantes montrent comment déterminer l'ID du compte de service BigQuery pour votre projet.

Console

  1. Accédez à la page Tableau de bord de Cloud Console.

    Accéder à la page "Tableau de bord"

  2. Cliquez sur la liste déroulante Sélectionner située en haut de la page. Sélectionnez votre projet dans la fenêtre Sélectionner qui s'affiche.

  3. L'ID et le numéro du projet sont tous deux affichés sur la carte Informations sur le projet du tableau de bord du projet :

    Fiche info concernant le projet

  4. Dans la chaîne suivante, remplacez PROJECT_NUMBER par votre numéro de projet. La nouvelle chaîne identifie l'ID de votre compte de service BigQuery.

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

bq

Exécutez la commande bq show avec l'option --encryption_service_account pour déterminer l'ID du compte de service :

bq show --encryption_service_account

La commande affiche l'ID du compte de service :

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

Affecter le rôle Chiffreur/Déchiffreur

Attribuez le rôle "Chiffreur/Déchiffreur de CryptoKeys Cloud KMS" au compte de service système BigQuery que vous avez copié dans votre presse-papiers. Ce compte apparaît au format suivant :

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

Console

  1. Ouvrez la page Clés cryptographiques dans Cloud Console.

    Ouvrir la page "Clés cryptographiques"

  2. Cliquez sur le nom du trousseau de clés contenant la clé.

  3. Cochez la case correspondant à la clé de chiffrement à laquelle vous souhaitez ajouter le rôle. L'onglet Autorisations s'ouvre.

  4. Cliquez sur Ajouter un membre.

  5. Saisissez l'adresse e-mail du compte de service (bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com).

    • Si le compte de service figure déjà sur la liste des membres, il possède des rôles. Cliquez sur la liste déroulante du rôle actuellement affecté au compte de service bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com.
  6. Cliquez sur la liste déroulante Sélectionnez un rôle, sélectionnez Cloud KMS, puis cliquez sur le rôle Chiffreur/Déchiffreur de CryptoKeys Cloud KMS.

  7. Cliquez sur Enregistrer pour appliquer le rôle au compte de service bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com.

gcloud

Pour attribuer le rôle, vous pouvez utiliser l'outil de ligne de commande gcloud comme suit :

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

Remplacez l'élément suivant :

  • KMS_PROJECT_ID : ID de votre projet Google Cloud exécutant Cloud KMS
  • PROJECT_NUMBER : numéro de votre projet Cloud exécutant BigQuery (et non son ID)
  • KMS_KEY_LOCATION : nom de l'emplacement de votre clé Cloud KMS
  • KMS_KEY_RING : nom du trousseau de clés contenant votre clé Cloud KMS
  • KMS_KEY : nom de votre clé Cloud KMS

ID de ressource de la clé

Pour pouvoir utiliser des clés CMEK, vous devez disposer de l'ID de ressource de la clé Cloud KMS, comme décrit dans les exemples de cette page. Cette clé est sensible à la casse et se présente au format suivant :

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

Récupérer l'ID de ressource de la clé

  1. Ouvrez la page Clés cryptographiques dans Cloud Console.

    Ouvrir la page "Clés cryptographiques"

  2. Cliquez sur le nom du trousseau de clés contenant la clé.

  3. Pour la clé dont vous voulez récupérer l'ID de ressource, cliquez sur Plus .

  4. Cliquez sur Copier l'ID de ressource. L'ID de ressource pour la clé est copié dans votre presse-papiers.

Créer une table protégée par Cloud KMS

Créer une table vide protégée par Cloud KMS

Pour créer une table protégée par Cloud KMS, procédez comme suit :

Console

  1. Ouvrez la page BigQuery dans Cloud Console.

    Accéder à BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données.

  3. Cliquez sur Créer une table.

  4. Sur la page Créer une table, spécifiez les informations nécessaires pour créer une table vide avec une définition de schéma. Avant de cliquer sur Créer une table, définissez le type de chiffrement et spécifiez la clé Cloud KMS à utiliser avec la table :

    1. Cliquez sur Options avancées.
    2. Cliquez sur Clé gérée par le client.
    3. Sélectionnez la clé. Si la clé que vous souhaitez utiliser ne figure pas dans la liste, saisissez son ID de ressource.
  5. Cliquez sur Créer une table.

bq

Vous pouvez également créer la table à l'aide de l'outil de ligne de commande bq et de l'option --destination_kms_key. L'option --destination_kms_key spécifie l'ID de ressource de la clé à utiliser avec la table.

Pour créer une table vide à l'aide d'un schéma, exécutez la commande suivante :

bq mk --schema name:string,value:integer -t \
--destination_kms_key projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
mydataset.newtable

Vous pouvez également utiliser une instruction LDD :

bq query --use_legacy_sql=false "
  CREATE TABLE mydataset.newtable (name STRING, value INT64)
  OPTIONS(
    kms_key_name='projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY'
  )
"

Pour créer une table à partir d'une requête, exécutez la commande suivante :

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

Pour en savoir plus sur l'outil de ligne de commande bq, consultez la section Utiliser l'outil de ligne de commande bq.

Go

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

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

Pour protéger une nouvelle table à l'aide d'une clé de chiffrement gérée par le client, définissez la propriété Table.encryption_configuration sur un objet EncryptionConfiguration avant de créer la table.

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

table_ref = dataset.table("my_table")
table = bigquery.Table(table_ref)

# 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/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
    "cloud-samples-tests", "us", "test", "test"
)
table.encryption_configuration = bigquery.EncryptionConfiguration(
    kms_key_name=kms_key_name
)

table = client.create_table(table)  # API request

assert table.encryption_configuration.kms_key_name == kms_key_name

Interroger une table protégée par une clé Cloud KMS

L'interrogation d'une table protégée par Cloud KMS ne requiert aucune démarche spécifique. BigQuery stocke le nom de la clé permettant de chiffrer le contenu de la table et l'utilise lorsqu'une table protégée par Cloud KMS est interrogée.

Tant que BigQuery a accès à la clé Cloud KMS qui sert à chiffrer le contenu de la table, vous pouvez utiliser les outils existants, la console BigQuery et l'interface de ligne de commande bq de la même manière qu'avec les tables chiffrées par défaut.

Protéger les résultats de requête à l'aide d'une clé Cloud KMS

Console

  1. Ouvrez la page BigQuery dans Cloud Console.

    Accéder à BigQuery

  2. Cliquez sur Saisir une nouvelle requête.

  3. Saisissez une requête SQL BigQuery valide dans la zone de texte de la requête.

  4. Cliquez sur Plus, puis sur Paramètres de requête et enfin sur Options avancées.

  5. Sélectionnez Chiffrement géré par le client.

  6. Sélectionnez la clé. Si la clé que vous souhaitez utiliser ne figure pas dans la liste, saisissez son ID de ressource.

  7. Cliquez sur Enregistrer.

  8. Cliquez sur Run (Exécuter).

bq

Spécifiez l'option --destination_kms_key pour protéger la table de destination ou les résultats de la requête (si vous utilisez une table temporaire) avec votre clé Cloud KMS. L'option --destination_kms_key spécifie l'ID de ressource de la clé à utiliser avec la table de destination ou la table résultante.

Vous pouvez également spécifier l'option --destination_table pour indiquer la destination des résultats de la requête. Si l'option --destination_table n'est pas spécifiée, les résultats de la requête seront écrits dans une table temporaire.

Pour interroger une table, exécutez la commande suivante :

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

Pour en savoir plus sur l'outil de ligne de commande bq, consultez la section Utiliser l'outil de ligne de commande bq.

Go

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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage 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.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

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

Charger une table protégée par Cloud KMS

Pour charger un fichier de données dans une table protégée par Cloud KMS, procédez comme suit :

Console

Pour protéger une table de destination de tâches de chargement à l'aide d'une clé de chiffrement gérée par le client, spécifiez la clé au moment de charger la table.

  1. Ouvrez la page BigQuery dans Cloud Console.

    Accéder à BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données.

  3. À droite de la fenêtre, dans le panneau de détails, cliquez sur Créer une table.

  4. Saisissez les options que vous souhaitez utiliser pour le chargement de la table, mais avant de cliquer sur Créer une table, sélectionnez Options avancées.

  5. Sous Chiffrement, sélectionnez Clé gérée par le client.

  6. Cliquez sur la liste déroulante Sélectionner une clé gérée par le client et choisissez la clé à utiliser. Si vous ne voyez aucune clé, saisissez un ID de ressource de clé.

    Options avancées.

  7. Cliquez sur Créer une table.

bq

Pour protéger une table de destination de tâches de chargement à l'aide d'une clé de chiffrement gérée par le client, spécifiez l'option --destination_kms_key.

bq --location=LOCATION load \
--autodetect \
--source_format=FORMAT \
--destination_kms_key projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
DATASET.TABLE \
path_to_source
Exemple :
bq load \
--autodetect \
--source_format=NEWLINE_DELIMITED_JSON \
--destination_kms_key projects/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

Pour protéger une table de destination de tâches de chargement à l'aide d'une clé de chiffrement gérée par le client, définissez la propriété LoadJobConfig.destination_encryption_configuration sur un objet EncryptionConfiguration et chargez la table.

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

Insérer des données en flux continu dans une table protégée par Cloud KMS

Vous pouvez insérer des données en flux continu dans votre table BigQuery protégée par une clé CMEK sans spécifier de paramètres supplémentaires. Notez que ces données sont chiffrées dans le tampon et à l'emplacement final grâce à votre clé Cloud KMS. Avant de diffuser des données dans une table protégée par une clé CMEK, vérifiez les exigences de disponibilité et d'accessibilité des clés.

Pour en savoir plus sur la diffusion de données, consultez la page Insérer des données en flux continu dans BigQuery.

Remplacer le chiffrement par défaut d'une table par la protection Cloud KMS

bq

Vous pouvez exécuter la commande bq cp en spécifiant l'option --destination_kms_key pour copier une table protégée avec le chiffrement par défaut dans une nouvelle table ou dans la table d'origine, protégée par Cloud KMS. L'option --destination_kms_key spécifie l'ID de ressource de la clé à utiliser avec la table de destination.

Pour copier une table utilisant le chiffrement par défaut dans une nouvelle table protégée par Cloud KMS, exécutez la commande suivante :

bq cp \
--destination_kms_key projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
sourceDataset.sourceTableId destinationDataset.destinationTableId

Si vous souhaitez copier une table protégée par le chiffrement par défaut dans la même table, mais en utilisant la protection Cloud KMS, exécutez la commande suivante :

bq cp -f \
--destination_kms_key projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY \
sourceDataset.sourceTableId sourceDataset.sourceTableId

Si vous souhaitez remplacer la protection de Cloud KMS d'une table par le chiffrement par défaut, copiez le fichier à son propre emplacement en exécutant la commande bq cp sans spécifier l'option --destination_kms_key.

Pour en savoir plus sur l'outil de ligne de commande bq, consultez la section Utiliser l'outil de ligne de commande 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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

Pour protéger la destination d'une opération de copie de table à l'aide d'une clé de chiffrement gérée par le client, définissez la propriété QueryJobConfig.destination_encryption_configuration sur un objet EncryptionConfiguration et copiez la table.

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

Vérifier si une table est protégée par Cloud KMS

  1. Dans Cloud Console, développez l'ensemble de données en cliquant sur la flèche bleue située à gauche de son nom ou en double-cliquant sur son nom. Les tables et les vues de l'ensemble de données s'affichent.

  2. Cliquez sur le nom de la table.

  3. Cliquez sur Détails. La page Détails de la table affiche la description et les informations de la table.

  4. Si la table est protégée par Cloud KMS, le champ Clé de chiffrement gérée par le client affiche l'ID de ressource de la clé.

    Table protégée.

Modifier la clé Cloud KMS d'une table BigQuery

Pour modifier la clé Cloud KMS d'une table existante protégée par une clé de chiffrement gérée par le client, vous pouvez exécuter une requête ALTER TABLE, utiliser l'API ou l'outil de ligne de commande bq. Il existe deux façons de modifier la clé Cloud KMS à l'aide de l'API et de l'outil de ligne de commande bq : update et cp. La commande update sert à modifier la clé Cloud KMS d'une table protégée par KMS. À l'inverse, la commande cp vous permet de modifier la clé Cloud KMS d'une table protégée par une clé CMEK, de remplacer le chiffrement par défaut par la protection CMEK, ou de remplacer la protection CMEK par le chiffrement par défaut. La commande update présente l'avantage d'être plus rapide que cp et de permettre l'utilisation de décorateurs de table.

Console

  1. Ouvrez la page BigQuery dans Cloud Console.

    Accéder à BigQuery

  2. Cliquez sur Saisir une nouvelle requête.

  3. Saisissez votre instruction LDD dans la zone de texte Nouvelle requête. Dans le champ kms_key_name, spécifiez l'ID de ressource de la clé à utiliser pour protéger la table.

    #standardSQL
    ALTER TABLE mydataset.mytable
    SET OPTIONS (
    kms_key_name="projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY"
    )
    
  4. Cliquez sur Run (Exécuter).

bq

Vous pouvez exécuter la commande bq cp en spécifiant l'option --destination_kms_key pour modifier la clé d'une table protégée par Cloud KMS. L'option --destination_kms_key spécifie l'ID de ressource de la clé à utiliser avec la table.

bq update \
--destination_kms_key projects/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

Pour modifier la clé de chiffrement gérée par le client d'une table, spécifiez un autre objet EncryptionConfiguration pour la propriété Table.encryption_configuration et mettez à jour la table.

# 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

Définir une clé par défaut pour l'ensemble de données

Vous pouvez définir une clé Cloud KMS par défaut au niveau de l'ensemble de données. Celle-ci s'applique à toutes les tables nouvellement créées au sein de l'ensemble de données, à moins que vous ne spécifiiez une autre clé au moment de la création de la table. La clé par défaut ne s'applique pas aux tables existantes. La modification de la clé par défaut n'altère pas les tables existantes et s'applique uniquement aux tables créées après cette modification.

Vous pouvez définir, modifier ou supprimer la clé par défaut de l'ensemble de données de plusieurs manières :

Supprimer l'accès de BigQuery à la clé Cloud KMS

Vous pouvez supprimer l'accès de BigQuery à la clé Cloud KMS à tout moment en révoquant l'autorisation IAM associée à cette clé.

La révocation de l'accès de BigQuery à une clé Cloud KMS peut affecter considérablement l'expérience utilisateur et entraîner des pertes de données :

  • Les données des tables protégées par des clés de chiffrement gérées par le client (CMEK) ne sont plus accessibles. Les commandes query, cp, extract et tabledata.list échoueront toutes.

  • Aucune nouvelle donnée ne peut être ajoutée aux tables protégées par des clés CMEK.

  • Une fois l'accès rétabli, les performances des requêtes sur ces tables peuvent être réduites pendant plusieurs jours.

Impact de la rotation des clés Cloud KMS

BigQuery n'aligne pas automatiquement la rotation d'une clé de chiffrement de table avec la rotation de la clé Cloud KMS associée à cette table. Les tables existantes continuent à utiliser la version de clé avec laquelle elles ont été créées. Les nouvelles tables utilisent la version de clé actuelle.

Limites

Accès de BigQuery à la clé Cloud KMS

Une clé Cloud KMS est considérée comme disponible et accessible par BigQuery si elle répond aux exigences suivantes :

  • La clé est activée.
  • Le compte de service BigQuery détient des autorisations de chiffrement et de déchiffrement sur la clé.

Les sections suivantes décrivent l'impact qu'une clé inaccessible peut avoir sur les insertions en flux continu et sur les données inaccessibles à long terme.

Impact sur les insertions en flux continu

La clé Cloud KMS doit être disponible et accessible pendant au moins 24 heures consécutives au cours des 48 heures qui suivent une requête d'insertion en flux continu. Dans le cas contraire, il est possible que les données diffusées ne soient pas entièrement conservées, ce qui risque d'entraîner leur perte. Pour en savoir plus sur les insertions en flux continu, consultez la page Insérer des données en flux continu dans BigQuery.

Impact sur les données inaccessibles à long terme

Comme BigQuery assure un stockage géré, les données inaccessibles à long terme ne sont pas compatibles avec l'architecture de BigQuery. Si la clé Cloud KMS d'une table BigQuery donnée n'est pas disponible et accessible pendant 60 jours consécutifs, BigQuery peut choisir de supprimer cette table et les données associées. Au moins sept jours avant la suppression des données, BigQuery envoie un e-mail à l'adresse associée au compte de facturation.

Utiliser des décorateurs de table

Lorsque les données d'une table protégée par Cloud KMS sont remplacées via la disposition d'écriture WRITE_TRUNCATE pour les opérations load, cp ou query, vous ne pouvez plus interroger la table par le biais de décorateurs de table, selon l'heure du décorateur d'instantané.

En supposant qu'une table ait été remplacée à l'instant T et que la valeur snapshot_time du décorateur d'instantané soit antérieure à T, le tableau suivant indique s'il est possible d'interroger snapshot_time ou non :

Type de chiffrement avant T Type de chiffrement après T snapshot_time
Chiffrement Cloud KMS Chiffrement Cloud KMS Interrogation non disponible
Chiffrement par défaut Chiffrement Cloud KMS Interrogation disponible
Chiffrement Cloud KMS Chiffrement par défaut Interrogation non disponible

Notez qu'une logique comparable s'applique à <time2> lorsqu'un décorateur de plage est utilisé.

Questions fréquentes

Qui doit détenir des autorisations sur la clé Cloud KMS ?

Si vous utilisez des clés de chiffrement gérées par le client, vous n'avez pas besoin de spécifier des autorisations à plusieurs reprises. Tant que le compte de service BigQuery est autorisé à utiliser la clé Cloud KMS pour effectuer des opérations de chiffrement et de déchiffrement, tous les membres ayant accès à la table BigQuery peuvent consulter les données (même s'ils ne disposent pas d'un accès direct à la clé Cloud KMS).

Quel compte de service est utilisé ?

Le compte de service BigQuery associé au projet Cloud de la table est utilisé pour déchiffrer les données qu'elle contient. Les comptes de service BigQuery sont uniques pour chaque projet. En outre, lorsque des données sont rédigées dans une table anonyme protégée par Cloud KMS, c'est le compte de service associé au projet où s'effectue la tâche qui est utilisé.

Prenons l'exemple de trois tables (table1, table2, table3) protégées par des clés de chiffrement gérées par le client. Pour interroger les données de {project1.table1, project2.table2} en utilisant la table de destination {project3.table3}, procédez comme suit :

  • Utiliser le compte de service project1 pour project1.table1
  • Utiliser le compte de service project2 pour project2.table2
  • Utiliser le compte de service project3 pour project3.table3

Comment BigQuery utilise-t-il ma clé Cloud KMS ?

BigQuery utilise la clé Cloud KMS pour déchiffrer des données en réponse à une requête utilisateur, par exemple, tabledata.list ou jobs.insert.

La clé permet également à BigQuery d'effectuer des tâches de maintenance des données et d'optimisation du stockage, telles que la conversion de données dans un format optimisé en lecture.

Quelles sont les bibliothèques de cryptographie utilisées ?

BigQuery s'appuie sur Cloud KMS pour gérer les fonctionnalités CMEK. Cloud KMS utilise Tink pour effectuer le chiffrement.

Comment obtenir de l'aide ?

Si vous ne trouvez pas la réponse à vos questions, consultez l'article Assistance BigQuery ou Assistance Cloud KMS.

Résoudre les erreurs

La section suivante décrit les erreurs courantes et présente les solutions recommandées.

Erreur Recommandation
Veuillez attribuer le rôle de chiffreur/déchiffreur de clés cryptographiques Cloud KMS Le compte de service BigQuery associé à votre projet ne dispose pas des autorisations IAM nécessaires pour utiliser la clé Cloud KMS spécifiée. Suivez les instructions fournies par l'erreur ou figurant dans cette documentation pour attribuer l'autorisation IAM appropriée.
Les paramètres de chiffrement de table existants ne correspondent pas aux paramètres spécifiés dans la requête Ce problème peut survenir lorsque la table de destination possède des paramètres de chiffrement différents de ceux de votre requête. Pour le résoudre, remplacez la table à l'aide de la disposition d'écriture TRUNCATE ou spécifiez une table de destination différente.
Vous ne pouvez pas sélectionner cette région La région de la clé Cloud KMS ne correspond pas à la région de l'ensemble de données BigQuery contenant la table de destination. Pour corriger cette erreur, sélectionnez une clé dans la région de votre ensemble de données ou chargez les données dans un ensemble de données appartenant à la même région que la clé.