Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo delle chiavi di crittografia gestite dal cliente

Questa pagina descrive come utilizzare una chiave di crittografia di Cloud Key Management Service con Cloud Storage, incluse l'impostazione di chiavi predefinite sui bucket e l'aggiunta di chiavi a singoli oggetti. Una chiave di crittografia Cloud KMS è una chiave di crittografia gestita dal cliente. Queste chiavi vengono create e gestite tramite Cloud KMS e archiviate come chiavi software, in un cluster HSM o esternamente.

Prima di iniziare

Prima di utilizzare questa funzionalità in Cloud Storage, devi:

Abilita l'API Cloud KMS per il progetto che archivierà le chiavi di crittografia.

Abilitare l'API
Disponi di autorizzazioni sufficienti per il progetto in cui verranno archiviate le tue chiavi di crittografia:
- Se sei il proprietario del progetto in cui verranno archiviate le chiavi, molto probabilmente hai l'autorizzazione necessaria.
- Se prevedi di creare nuovi keyring e chiavi di crittografia, devi disporre delle autorizzazioni cloudkms.keyRings.create e cloudkms.cryptoKeys.create.
- Se prevedi di utilizzare chiavi e keyring nuovi o esistenti, devi avere l'autorizzazione cloudkms.cryptoKeys.setIamPolicy per le chiavi che utilizzerai per la crittografia.
  
  Questa autorizzazione consente di concedere agli agenti di servizio Cloud Storage l'accesso alle chiavi Cloud KMS.
- Le autorizzazioni precedenti sono contenute nel ruolo Amministratore Cloud KMS.
  
  Per istruzioni su come ottenere questo o altri ruoli di Cloud KMS, consulta Utilizzo di IAM con Cloud KMS.
Disporre di un keyring Cloud KMS e di almeno una chiave all'interno del keyring.

Il keyring deve trovarsi nella stessa località dei dati che intendi criptare, ma può trovarsi in un progetto diverso. Per le località di Cloud KMS disponibili, consulta le località di Cloud KMS.

Nota: per la maggior parte delle regioni doppie, devi creare il keyring nella più regioni associata, mentre per le due regioni predefinite ASIA1, EUR4 e NAM4 devi creare il keyring nella stessa due regioni predefinita.
Disporre di autorizzazioni sufficienti per lavorare con gli oggetti nel bucket Cloud Storage:
- Se sei il proprietario del progetto che contiene il bucket, molto probabilmente hai l'autorizzazione necessaria.
- Se utilizzi IAM, devi disporre dell'autorizzazione storage.objects.create per scrivere oggetti nel bucket e dell'autorizzazione storage.objects.get per leggere gli oggetti dal bucket. Per istruzioni su come ottenere un ruolo, ad esempio Amministratore oggetti Storage, consulta Utilizzo delle autorizzazioni IAM.
- Se utilizzi gli ACL, devi disporre dell'autorizzazione WRITER con ambito a livello di bucket per scrivere oggetti nel bucket e dell'autorizzazione READER basata sugli oggetti per leggere gli oggetti dal bucket. Per istruzioni su come eseguire questa operazione, consulta Impostazione degli ACL.
Nota: il passaggio seguente non è necessario se utilizzi Google Cloud CLI.

Recupera l'indirizzo email dell'agente di servizio associato al progetto che contiene il bucket Cloud Storage. Eseguendo questo passaggio, crei automaticamente l'agente di servizio se non esiste attualmente.

Assegna una chiave Cloud KMS a un agente di servizio

Per utilizzare chiavi di crittografia gestite dal cliente, concedi all'agente di servizio Cloud Storage associato al tuo bucket l'autorizzazione a utilizzare la tua chiave Cloud KMS per la crittografia e la decrittografia:

Console

Apri il browser Cloud Key Management Service Keys (Chiave di servizio Cloud Key Management Service) nella console Google Cloud.
Apri il browser delle chiavi Cloud KMS
Fai clic sul nome del keyring che contiene la chiave che vuoi utilizzare.
Seleziona la casella di controllo relativa alla chiave desiderata.

Nel riquadro a destra della finestra diventa disponibile la scheda Autorizzazioni.
Nella finestra di dialogo Aggiungi entità, specifica l'indirizzo email dell'agente di servizio Cloud Storage a cui vuoi concedere l'accesso.
Nel menu a discesa Seleziona un ruolo, seleziona Autore crittografia/decriptazione CryptoKey Cloud KMS.
Fai clic su Aggiungi.

Per scoprire come ottenere informazioni dettagliate sugli errori relativi alle operazioni di Cloud Storage non riuscite nella console Google Cloud, consulta Risoluzione dei problemi.

Riga di comando

Utilizza il comando gcloud storage service-agent con il flag --authorize-cmek per concedere all'agente di servizio associato al tuo bucket l'autorizzazione a criptare e decriptare gli oggetti utilizzando la chiave Cloud KMS:

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

Dove:

PROJECT_STORING_OBJECTS è l'ID o il numero del progetto che contiene gli oggetti che vuoi criptare o decriptare. Ad esempio, my-pet-project.
KEY_RESOURCE è la tua risorsa chiave Cloud KMS.

Librerie client

C#

Per maggiori informazioni, consulta la documentazione di riferimento dell'API C# di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.


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

Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di Cloud Storage.

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

Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di Cloud Storage.

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

Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di Cloud Storage.

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

Per maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di Cloud Storage.

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

Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di Cloud Storage.

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

Per maggiori informazioni, consulta la documentazione di riferimento dell'API Ruby di Cloud Storage.

# 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

Assicurati che gcloud CLI sia installato e inizializzato per generare un token di accesso per l'intestazione Authorization.

In alternativa, puoi creare un token di accesso utilizzando OAuth 2.0 Playground e includerlo nell'intestazione Authorization.
Crea un file JSON contenente le seguenti informazioni:
```
{
  "policy": {
    "bindings": {
      "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
      "members": "serviceAccount:SERVICE_AGENT_EMAIL_ADDRESS"
    },
  }
}
```
Dove SERVICE_AGENT_EMAIL_ADDRESS è l'indirizzo email associato all'agente di servizio. Ad esempio, service-7550275089395@gs-project-accounts.iam.gserviceaccount.com.

Utilizza cURL per chiamare l'API Cloud KMS con una richiesta POST setIamPolicy:

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"

Dove:

JSON_FILE_NAME è il percorso del file JSON creato nel passaggio 2.
KEY_RESOURCE è la tua risorsa chiave Cloud KMS.

API XML

Non è possibile utilizzare l'API XML per assegnare Cloud KMS a un agente di servizio. Utilizza invece uno degli altri strumenti di Cloud Storage, come gcloud CLI.

Usa chiavi di crittografia predefinite

Imposta la chiave predefinita per un bucket

Per aggiungere, modificare o rimuovere la chiave Cloud KMS utilizzata per impostazione predefinita quando gli oggetti vengono scritti in un bucket:

Console

Nella console Google Cloud, vai alla pagina Bucket di Cloud Storage.

Vai a Bucket
Nell'elenco dei bucket, fai clic sul nome del bucket che ti interessa.
Nella pagina Dettagli bucket, fai clic sulla scheda Configurazione.
Fai clic sull'icona a forma di matita associata alla voce Tipo di crittografia.
Imposta o rimuovi la chiave Cloud KMS predefinita per il bucket.
1. Se il bucket non utilizza una chiave Cloud KMS, seleziona il pulsante di opzione Chiave gestita dal cliente, quindi seleziona una delle chiavi disponibili nel menu a discesa associato.
2. Se il bucket attualmente utilizza una chiave Cloud KMS, modifica la chiave Cloud KMS nel menu a discesa o rimuovi la chiave Cloud KMS selezionando il pulsante di opzione Chiave gestita da Google.
Fai clic su Salva.

Per scoprire come ottenere informazioni dettagliate sugli errori relativi alle operazioni di Cloud Storage non riuscite nella console Google Cloud, consulta Risoluzione dei problemi.

Riga di comando

Utilizza il comando gcloud storage buckets update con il flag appropriato:

gcloud storage buckets update gs://BUCKET_NAME FLAG

Dove:

BUCKET_NAME è il nome del bucket pertinente. Ad esempio, my-bucket.
FLAG è l'impostazione desiderata per la chiave predefinita nel bucket. Utilizza uno dei seguenti formati:
- --default-encryption-key= e una risorsa chiave Cloud KMS, se vuoi aggiungere o modificare una chiave predefinita.
- --clear-default-encryption-key, se vuoi rimuovere la chiave predefinita dal bucket.

In caso di esito positivo, la risposta sarà simile a:

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