Utiliser les clés de chiffrement gérées par le client

Présentation

Cette page explique comment utiliser une clé de chiffrement Cloud Key Management Service avec Cloud Storage, y compris la définition de clés par défaut sur des buckets et l'ajout de clés à des objets individuels. Une clé de chiffrement Cloud KMS est une clé de chiffrement gérée par le client. Ces clés sont créées et gérées via Cloud KMS et stockées sous forme de clés logicielles, dans un cluster HSM ou en externe.

Avant de commencer

Avant d'utiliser cette fonctionnalité dans Cloud Storage, vous devez répondre aux critères suivants :

Avoir activé l'API Cloud KMS pour le projet qui stockera vos clés de chiffrement

Activer l'API
Disposer des autorisations suffisantes pour le projet qui stockera vos clés de chiffrement :
- Si vous êtes le propriétaire du projet qui stockera les clés, vous disposez probablement de l'autorisation nécessaire.
- Si vous envisagez de créer des trousseaux de clés et des clés de chiffrement, vous devez disposer des autorisations cloudkms.keyRings.create et cloudkms.cryptoKeys.create
- Que vous prévoyiez d'utiliser des clés et des trousseaux de clés nouveaux ou existants, vous devez disposer de l'autorisation cloudkms.cryptoKeys.setIamPolicy pour les clés qui serviront au chiffrement.
  
  Cette autorisation vous permet d'accorder aux agents de service Cloud Storage un accès aux clés Cloud KMS.
- Les autorisations ci-dessus sont comprises dans le rôle Administrateur Cloud KMS.
  
  Reportez-vous à la page Utiliser IAM avec Cloud KMS pour savoir comment obtenir ce rôle ou d'autres rôles de Cloud KMS.
Disposer d'un trousseau de clés Cloud KMS qui compte au moins une clé

Le trousseau de clés doit se trouver au même emplacement que les données que vous souhaitez chiffrer, mais il peut se trouver dans un projet différent. Pour connaître les emplacements Cloud KMS disponibles, consultez la section Emplacements Cloud KMS.
Remarque : Pour la plupart des emplacements birégionaux, vous devez créer le trousseau de clés dans l'emplacement multirégional associé, mais pour les emplacements birégionaux prédéfinis ASIA1, EUR4 et NAM4, vous devez créer le trousseau de clés dans l'emplacement birégional prédéfini.
Disposer des autorisations suffisantes pour utiliser des objets dans votre bucket Cloud Storage :
- Si vous êtes propriétaire du projet contenant le bucket, vous disposez probablement de l'autorisation nécessaire.
- Si vous utilisez IAM, vous devez disposer de l'autorisation storage.objects.create pour écrire des objets dans le bucket et de l'autorisation storage.objects.get pour lire des objets à partir de ce bucket. Consultez la page Utiliser des autorisations Cloud IAM pour savoir comment obtenir un rôle doté de ces autorisations, par exemple Administrateur des objets Storage.
- Si vous utilisez des LCA (Listes de contrôle des accès), vous devez disposer de l'autorisation WRITER (rédacteur) au niveau du bucket pour écrire des objets sur le bucket et de l'autorisation READER (lecteur) au niveau des objets pour lire des objets à partir de ce bucket. Pour savoir comment procéder, consultez la section Configurer des LCA.
Remarque : L'étape suivante n'est pas nécessaire si vous utilisez la Google Cloud CLI.

Obtenir l'adresse e-mail de l'agent de service associé au projet contenant votre bucket Cloud Storage. En effectuant cette étape, vous créez automatiquement l'agent de service s'il n'existe pas.

Attribuer une clé Cloud KMS à un agent de service

Pour utiliser les clés de chiffrement gérées par le client, accordez à l'agent de service Cloud Storage associé à votre bucket l'autorisation d'utiliser votre clé Cloud KMS pour le chiffrement et le déchiffrement :

Console

Ouvrez le navigateur Clés Cloud Key Management Service dans Google Cloud Console.
Ouvrir le navigateur de clés Cloud KMS
Cliquez sur le nom du trousseau de clés contenant la clé que vous souhaitez utiliser.
Cochez la case correspondant à la clé souhaitée.

L'onglet Autorisations s'affiche dans le volet de droite.
Dans la boîte de dialogue Ajouter des entités principales, indiquez l'adresse e-mail de l'agent de service Cloud Storage auquel vous accordez l'accès.
Dans le menu déroulant Sélectionner un rôle, sélectionnez Chiffreur/Déchiffreur de clés cryptographiques Cloud KMS.
Cliquez sur Ajouter.

Pour savoir comment obtenir des informations détaillées sur les erreurs liées aux opérations Cloud Storage ayant échoué dans la console Google Cloud, consultez la section Dépannage.

Ligne de commande

Exécutez la commande gcloud storage service-agent avec l'option --authorize-cmek pour autoriser l'agent de service associé à votre bucket à chiffrer et déchiffrer des objets à l'aide de votre clé Cloud KMS :

gcloud storage service-agent --project=PROJECT_STORING_OBJECTS --authorize-cmek=KEY_RESOURCE

Où :

PROJECT_STORING_OBJECTS correspond à l'ID ou au numéro du projet contenant les objets que vous souhaitez chiffrer ou déchiffrer. Exemple :my-pet-project
KEY_RESOURCE correspond à votre ressource de clé Cloud KMS.

Bibliothèques clientes

C#

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


using Google.Cloud.Iam.V1;
using Google.Cloud.Kms.V1;

public class IamAddMemberSample
{
    public Policy IamAddMember(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key",
      string member = "user:foo@example.com")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the resource name.
        CryptoKeyName resourceName = new CryptoKeyName(projectId, locationId, keyRingId, keyId);

        // The resource name could also be a key ring.
        // var resourceName = new KeyRingName(projectId, locationId, keyRingId);

        // Get the current IAM policy.
        Policy policy = client.IAMPolicyClient.GetIamPolicy(
            new GetIamPolicyRequest
            { 
                ResourceAsResourceName = resourceName
            });

        // Add the member to the policy.
        policy.AddRoleMember("roles/cloudkms.cryptoKeyEncrypterDecrypter", member);

        // Save the updated IAM policy.
        Policy result = client.IAMPolicyClient.SetIamPolicy(
            new SetIamPolicyRequest
            {
                ResourceAsResourceName = resourceName,
                Policy = policy
            });

        // Return the resulting policy.
        return result;
    }
}

Go

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
)

// iamAddMember adds a new IAM member to the Cloud KMS key
func iamAddMember(w io.Writer, name, member string) error {
	// NOTE: The resource name can be either a key or a key ring. If IAM
	// permissions are granted on the key ring, the permissions apply to all keys
	// in the key ring.
	//
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key"
	// member := "user:foo@example.com"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Get the current IAM policy.
	handle := client.ResourceIAM(name)
	policy, err := handle.Policy(ctx)
	if err != nil {
		return fmt.Errorf("failed to get IAM policy: %w", err)
	}

	// Grant the member permissions. This example grants permission to use the key
	// to encrypt data.
	policy.Add(member, "roles/cloudkms.cryptoKeyEncrypterDecrypter")
	if err := handle.SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("failed to save policy: %w", err)
	}

	fmt.Fprintf(w, "Updated IAM policy for %s\n", name)
	return nil
}

Java

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import java.io.IOException;

public class IamAddMember {

  public void iamAddMember() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String keyId = "my-key";
    String member = "user:foo@example.com";
    iamAddMember(projectId, locationId, keyRingId, keyId, member);
  }

  // Add the given IAM member to the key.
  public void iamAddMember(
      String projectId, String locationId, String keyRingId, String keyId, String member)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the key version name from the project, location, key ring, key,
      // and key version.
      CryptoKeyName resourceName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // The resource name could also be a key ring.
      // KeyRingName resourceName = KeyRingName.of(projectId, locationId, keyRingId);

      // Get the current policy.
      Policy policy = client.getIamPolicy(resourceName);

      // Create a new IAM binding for the member and role.
      Binding binding =
          Binding.newBuilder()
              .setRole("roles/cloudkms.cryptoKeyEncrypterDecrypter")
              .addMembers(member)
              .build();

      // Add the binding to the policy.
      Policy newPolicy = policy.toBuilder().addBindings(binding).build();

      client.setIamPolicy(resourceName, newPolicy);
      System.out.printf("Updated IAM policy for %s%n", resourceName.toString());
    }
  }
}

Node.js

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const keyId = 'my-key';
// const member = 'user:foo@example.com';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the resource name
const resourceName = client.cryptoKeyPath(
  projectId,
  locationId,
  keyRingId,
  keyId
);

// The resource name could also be a key ring.
// const resourceName = client.keyRingPath(projectId, locationId, keyRingId);

async function iamAddMember() {
  // Get the current IAM policy.
  const [policy] = await client.getIamPolicy({
    resource: resourceName,
  });

  // Add the member to the policy.
  policy.bindings.push({
    role: 'roles/cloudkms.cryptoKeyEncrypterDecrypter',
    members: [member],
  });

  // Save the updated policy.
  const [updatedPolicy] = await client.setIamPolicy({
    resource: resourceName,
    policy: policy,
  });

  console.log('Updated policy');
  return updatedPolicy;
}

return iamAddMember();

PHP

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

use Google\Cloud\Iam\V1\Binding;
use Google\Cloud\Iam\V1\GetIamPolicyRequest;
use Google\Cloud\Iam\V1\SetIamPolicyRequest;
use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;

function iam_add_member(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key',
    string $member = 'user:foo@example.com'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the resource name.
    $resourceName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // The resource name could also be a key ring.
    // $resourceName = $client->keyRingName($projectId, $locationId, $keyRingId);

    // Get the current IAM policy.
    $getIamPolicyRequest = (new GetIamPolicyRequest())
        ->setResource($resourceName);
    $policy = $client->getIamPolicy($getIamPolicyRequest);

    // Add the member to the policy.
    $bindings = $policy->getBindings();
    $bindings[] = (new Binding())
        ->setRole('roles/cloudkms.cryptoKeyEncrypterDecrypter')
        ->setMembers([$member]);
    $policy->setBindings($bindings);

    // Save the updated IAM policy.
    $setIamPolicyRequest = (new SetIamPolicyRequest())
        ->setResource($resourceName)
        ->setPolicy($policy);
    $updatedPolicy = $client->setIamPolicy($setIamPolicyRequest);
    printf('Added %s' . PHP_EOL, $member);

    return $updatedPolicy;
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

from google.cloud import kms
from google.iam.v1 import policy_pb2 as iam_policy


def iam_add_member(
    project_id: str, location_id: str, key_ring_id: str, key_id: str, member: str
) -> iam_policy.Policy:
    """
    Add an IAM member to a resource.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        key_id (string): ID of the key to use (e.g. 'my-key').
        member (string): Member to add (e.g. 'user:foo@example.com')

    Returns:
        Policy: Updated Cloud IAM policy.

    """

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Build the resource name.
    resource_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    # The resource name could also be a key ring.
    # resource_name = client.key_ring_path(project_id, location_id, key_ring_id);

    # Get the current policy.
    policy = client.get_iam_policy(request={"resource": resource_name})

    # Add the member to the policy.
    policy.bindings.add(
        role="roles/cloudkms.cryptoKeyEncrypterDecrypter", members=[member]
    )

    # Save the updated IAM policy.
    request = {"resource": resource_name, "policy": policy}

    updated_policy = client.set_iam_policy(request=request)
    print(f"Added {member} to {resource_name}")
    return updated_policy

Ruby

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"
# member      = "user:foo@example.com"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the resource name.
resource_name = client.crypto_key_path project:    project_id,
                                       location:   location_id,
                                       key_ring:   key_ring_id,
                                       crypto_key: key_id

# The resource name could also be a key ring.
# resource_name = client.key_ring_path project: project_id, location: location_id, key_ring: key_ring_id

# Create the IAM client.
iam_client = Google::Cloud::Kms::V1::IAMPolicy::Client.new

# Get the current IAM policy.
policy = iam_client.get_iam_policy resource: resource_name

# Add the member to the policy.
policy.bindings << Google::Iam::V1::Binding.new(
  members: [member],
  role:    "roles/cloudkms.cryptoKeyEncrypterDecrypter"
)

# Save the updated policy.
updated_policy = iam_client.set_iam_policy resource: resource_name, policy: policy
puts "Added #{member}"

API REST

API JSON

Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth. Pour obtenir des instructions, consultez la page Authentification des API.
Créez un fichier JSON contenant les informations suivantes :
```
{
  "policy": {
    "bindings": {
      "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
      "members": "serviceAccount:SERVICE_AGENT_EMAIL_ADDRESS"
    },
  }
}
```
Où SERVICE_AGENT_EMAIL_ADDRESS correspond à l'adresse e-mail associée à votre agent de service. Exemple : service-7550275089395@gs-project-accounts.iam.gserviceaccount.com.
Utilisez cURL pour appeler l'API Cloud KMS avec une requête POST setIamPolicy :
```
curl -X POST --data-binary @JSON_FILE_NAME \
-H "Authorization: Bearer OAUTH2_TOKEN" \
-H "Content-Type: application/json" \
"https://cloudkms.googleapis.com/v1/KEY_RESOURCE:setIamPolicy"
```
Où :
- JSON_FILE_NAME correspond au chemin d'accès au fichier JSON que vous avez créé à l'étape 2.
- OAUTH2_TOKEN correspond au jeton d'accès que vous avez généré à l'étape 1.
- KEY_RESOURCE correspond à votre ressource de clé Cloud KMS.

API XML

L'API XML ne peut pas être utilisée pour affecter un Cloud KMS à un agent de service. Utilisez plutôt un autre outil Cloud Storage, tel que gcloud CLI.

Utiliser les clés de chiffrement par défaut

Définir la clé par défaut d'un bucket

Pour ajouter, changer ou supprimer la clé Cloud KMS utilisée par défaut lorsque des objets sont écrits sur un bucket, procédez comme suit :

Console

Dans la console Google Cloud, accédez à la page Buckets Cloud Storage.
Accéder à la page "Buckets"
Dans la liste des buckets, cliquez sur le nom du bucket souhaité.
Sur la page Informations sur le bucket, cliquez sur l'onglet Configuration.
Cliquez sur l'icône en forme de crayon associée à l'entrée de type de chiffrement.
Définissez ou supprimez la clé Cloud KMS par défaut du bucket.
1. Si le bucket n'utilise pas actuellement de clé Cloud KMS, cochez la case d'option Clé gérée par le client, puis sélectionnez l'une des clés disponibles dans le menu déroulant associé.
2. Si le bucket utilise actuellement une clé Cloud KMS, modifiez-la dans le menu déroulant ou supprimez la clé Cloud KMS en sélectionnant la case d'optionClé gérée par Google.
Cliquez sur Save (Enregistrer).

Pour savoir comment obtenir des informations détaillées sur les erreurs liées aux opérations Cloud Storage ayant échoué dans la console Google Cloud, consultez la section Dépannage.

Ligne de commande

Exécutez la commande gcloud storage buckets update avec l'option appropriée :

gcloud storage buckets update gs://BUCKET_NAME FLAG

Où :

BUCKET_NAME correspond au nom du bucket concerné. Par exemple, my-bucket.
FLAG est le paramètre souhaité pour la clé par défaut sur le bucket. Utilisez l'un des formats suivants :
- --default-encryption-key= et une ressource de clé Cloud KMS, si vous souhaitez ajouter ou modifier une clé par défaut.
- --clear-default-encryption-key, si vous souhaitez supprimer la clé par défaut sur le bucket.

Si l'opération réussit, la réponse se présente comme suit :

Updating gs://my-bucket/...
  Completed 1

Bibliothèques clientes