Kundenverwaltete Verschlüsselungsschlüssel verwenden

Overview

Auf dieser Seite wird beschrieben, wie Sie einen Cloud Key Management Service-Verschlüsselungsschlüssel mit Cloud Storage verwenden und z. B. Standardschlüssel für Buckets festlegen und einzelnen Objekten Schlüssel hinzufügen. Ein Cloud KMS-Verschlüsselungsschlüssel ist ein vom Kunden verwalteter Verschlüsselungsschlüssel. Solche Schlüssel werden über Cloud KMS erstellt und verwaltet und als Softwareschlüssel in einem HSM-Cluster oder extern gespeichert.

Hinweis

Vor der Verwendung dieses Features in Cloud Storage müssen Sie folgende Maßnahmen ergreifen:

Aktivieren Sie die Cloud KMS API für das Projekt, in dem Ihre Verschlüsselungsschlüssel gespeichert werden.

API aktivieren
Sie benötigen ausreichende Berechtigungen für das Projekt, in dem Ihre Verschlüsselungsschlüssel gespeichert werden:
- Wenn Sie der Inhaber des Projekts sind, in dem Ihre Schlüssel gespeichert werden, haben Sie wahrscheinlich die erforderliche Berechtigung.
- Wenn Sie neue Verschlüsselungsschlüssel und -schlüsselbunde erstellen möchten, benötigen Sie die Berechtigungen cloudkms.keyRings.create und cloudkms.cryptoKeys.create.
- Unabhängig davon, ob Sie neue oder vorhandene Schlüsselbunde und Schlüssel verwenden möchten, benötigen Sie die Berechtigung cloudkms.cryptoKeys.setIamPolicy für die Schlüssel, die Sie für die Verschlüsselung verwenden.
  
  Mit dieser Berechtigung können Sie Cloud Storage-Dienst-Agents Zugriff auf Cloud KMS-Schlüssel gewähren.
- Die oben genannten Berechtigungen sind in der Rolle Cloud KMS-Administrator enthalten.
  
  Unter IAM mit Cloud KMS verwenden wird beschrieben, wie Sie diese oder andere Cloud KMS-Rollen erhalten.
Sie benötigen einen Cloud KMS-Schlüsselbund und mindestens einen Schlüssel innerhalb des Schlüsselbunds.

Der Schlüsselbund muss sich am selben Speicherort wie die Daten befinden, die Sie verschlüsseln möchten. Er kann sich jedoch in einem anderen Projekt befinden. Informationen zu verfügbaren Cloud KMS-Standorten finden Sie unter Cloud KMS-Standorte.
Hinweis: Für die meisten Dual-Regionen müssen Sie den Schlüsselbund in der zugehörigen Multiregion erstellen, aber für die vordefinierten Dual-Regionen ASIA1, EUR4 und NAM4müssen Sie den Schlüsselbund in derselben vordefinierten Dual-Region erstellen.
Achten Sie auf ausreichende Berechtigungen, um mit Objekten in Ihrem Cloud Storage-Bucket zu arbeiten:
- Wenn Sie der Inhaber des Projekts sind, zu dem der Bucket gehört, haben Sie wahrscheinlich die erforderliche Berechtigung.
- Wenn Sie IAM verwenden, benötigen Sie die storage.objects.create-Berechtigung zum Schreiben von Objekten in den Bucket und die storage.objects.get-Berechtigung zum Lesen von Objekten aus dem Bucket. Unter IAM-Berechtigungen verwenden wird gezeigt, wie Sie eine Rolle wie Storage-Objekt-Administrator mit diesen Berechtigungen erhalten.
- Wenn Sie ACLs verwenden, benötigen Sie die Bucket-bezogene WRITER-Berechtigung, um Objekte in den Bucket zu schreiben, und die objektbezogene READER-Berechtigung, um Objekte aus dem Bucket zu lesen. Weitere Informationen dazu finden Sie unter ACLs festlegen.
Hinweis: Der folgende Schritt ist nicht erforderlich, wenn Sie die Google Cloud CLI verwenden.

Rufen Sie die E-Mail-Adresse des Dienst-Agents ab, der mit dem Projekt verknüpft ist, in dem sich Ihr Cloud Storage-Bucket befindet. Mit diesem Schritt erstellen Sie den Dienst-Agent automatisch, wenn er noch nicht vorhanden ist.

Cloud KMS-Schlüssel einem Dienst-Agent zuweisen

Damit Sie kundenverwaltete Verschlüsselungsschlüssel nutzen können, müssen Sie dem mit Ihrem Bucket verknüpften Cloud Storage-Dienstagent die Berechtigung zur Verwendung Ihres Cloud KMS-Schlüssels für Verschlüsseln und Entschlüsseln erteilen:

Console

Öffnen Sie in der Google Cloud Console den Browser für Cloud Key Management Service-Schlüssel.
Zum Browser für Cloud KMS-Schlüssel
Klicken Sie auf den Namen des Schlüsselbunds, der den Schlüssel enthält, den Sie verwenden möchten.
Klicken Sie das Kästchen für den gewünschten Schlüssel an.

Der Tab Berechtigungen im rechten Fensterbereich wird verfügbar.
Geben Sie im Dialogfeld Hauptkonten hinzufügen die E-Mail-Adresse des Cloud Storage-Dienst-Agents ein, dem Sie Zugriff gewähren möchten.
Wählen Sie im Drop-down-Menü Rolle auswählen die Option Cloud KMS CryptoKey-Verschlüsseler/Entschlüsseler aus.
Klicken Sie auf Add (Hinzufügen).

Unter Fehlerbehebung erfahren Sie, wie Sie detaillierte Fehlerinformationen zu fehlgeschlagenen Cloud Storage-Vorgängen in der Google Cloud Console abrufen.

Befehlszeile

Verwenden Sie den Befehl gcloud storage service-agent mit dem Flag --authorize-cmek, um dem mit Ihrem Bucket verknüpften Dienst-Agent die Berechtigung zu erteilen, Objekte mit Ihrem Cloud KMS-Schlüssel zu verschlüsseln und zu entschlüsseln:

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

Wobei:

PROJECT_STORING_OBJECTS ist die ID oder Nummer des Projekts, das die Objekte enthält, die Sie verschlüsseln bzw. entschlüsseln möchten. Beispiel: my-pet-project.
KEY_RESOURCE ist Ihre Cloud KMS-Schlüsselressource.

Clientbibliotheken

C#

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C# API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Go API.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js API.

//
// 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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage PHP API.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Ruby API.

# 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}"

REST APIs

JSON API

Die gcloud CLI installieren und initialisieren, um ein Zugriffstoken für den Header Authorization zu generieren.

Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.
Erstellen Sie eine JSON-Datei, die folgende Informationen enthält:
```
{
  "policy": {
    "bindings": {
      "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
      "members": "serviceAccount:SERVICE_AGENT_EMAIL_ADDRESS"
    },
  }
}
```
Dabei ist SERVICE_AGENT_EMAIL_ADDRESS die mit Ihrem Dienstkonto verknüpfte E-Mail-Adresse. Beispiel: service-7550275089395@gs-project-accounts.iam.gserviceaccount.com
Verwenden Sie cURL, um die Cloud KMS API mit einer POST setIamPolicy-Anfrage aufzurufen:
```
curl -X POST --data-binary @JSON_FILE_NAME \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://cloudkms.googleapis.com/v1/KEY_RESOURCE:setIamPolicy"
```
Wobei:
- JSON_FILE_NAME ist der Pfad für die JSON-Datei, die Sie in Schritt 2 erstellt haben.
- KEY_RESOURCE ist Ihre Cloud KMS-Schlüsselressource.

XML API

Die XML API kann nicht verwendet werden, um Cloud KMS einem Dienst-Agent zuzuweisen. Verwenden Sie stattdessen eines der anderen Cloud Storage-Tools, z. B. die gcloud CLI.

Standardverschlüsselungsschlüssel verwenden

Standardschlüssel für einen Bucket einstellen

So können Sie den Cloud KMS-Standardschlüssel hinzufügen, ändern oder entfernen, wenn Objekte in einen Bucket geschrieben werden:

Console

Wechseln Sie in der Cloud Console zur Seite Cloud Storage-Buckets.

Buckets aufrufen
Klicken Sie in der Bucket-Liste auf den Namen des gewünschten Buckets.
Klicken Sie auf der Seite Bucket-Details auf den Tab Konfiguration.
Klicken Sie auf das Stiftsymbol für den Eintrag Verschlüsselungstyp.
Legen Sie den Cloud KMS-Standardschlüssel für den Bucket fest oder entfernen Sie ihn.
1. Wenn der Bucket derzeit keinen Cloud KMS-Schlüssel verwendet, wählen Sie das Optionsfeld Vom Kunden verwalteter Schlüssel aus und wählen Sie dann einen der verfügbaren Schlüssel im zugehörigen Drop-down-Menü aus.
2. Wenn der Bucket derzeit einen Cloud KMS-Schlüssel verwendet, ändern Sie den Cloud KMS-Schlüssel im Drop-down-Menü oder entfernen Sie den Cloud KMS-Schlüssel. Wählen Sie dazu das Optionsfeld Von Google verwalteter Schlüssel.
Klicken Sie auf Speichern.

Unter Fehlerbehebung erfahren Sie, wie Sie detaillierte Fehlerinformationen zu fehlgeschlagenen Cloud Storage-Vorgängen in der Google Cloud Console abrufen.

Befehlszeile

Führen Sie den gcloud storage buckets update-Befehl mit dem geeigneten Flag aus.

gcloud storage buckets update gs://BUCKET_NAME FLAG

Dabei gilt:

BUCKET_NAME ist der Name des entsprechenden Buckets. Beispiel: my-bucket.
FLAG ist die gewünschte Einstellung für den Standardschlüssel im Bucket. Verwenden Sie eines der folgenden Formate:
- --default-encryption-key= und eine Cloud KMS-Schlüsselressource, wenn Sie einen Standardschlüssel hinzufügen oder ändern möchten.
- --clear-default-encryption-key, wenn Sie den Standardschlüssel für den Bucket entfernen möchten.

Wenn der Vorgang erfolgreich war, sieht die Antwort so aus:

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

Clientbibliotheken

C++

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ API.

Im folgenden Beispiel wird ein standardmäßig vom Kunden verwalteter Verschlüsselungsschlüssel für einen Bucket festgelegt:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& key_name) {
  StatusOr<gcs::BucketMetadata> updated = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().SetEncryption(
                       gcs::BucketEncryption{key_name}));
  if (!updated) throw std::move(updated).status();

  if (!updated->has_encryption()) {
    std::cerr << "The change to set the encryption attribute on bucket "
              << updated->name()
              << " was successful, but the encryption is not set."
              << "This is unexpected, maybe a concurrent change?\n";
    return;
  }

  std::cout << "Successfully set default KMS key on bucket "
            << updated->name() << " to "
            << updated->encryption().default_kms_key_name << "."
            << "\nFull metadata: " << *updated << "\n";
}