Usar claves de encriptación administradas por el cliente

Descripción general

En esta página, se describe cómo usar una clave de encriptación de Cloud Key Management Service con Cloud Storage, lo que incluye la configuración de claves predeterminadas en los buckets y la adición de claves a objetos individuales. Una clave de encriptación de Cloud KMS es una clave de encriptación administrada por el cliente. Estas claves se crean y administran a través de Cloud KMS y se almacenan como claves de software, en un clúster de HSM o de forma externa.

Creación manual o automática de claves

Puedes crear CMEK de forma manual o usar la clave automática de Cloud KMS (Vista previa). Autokey simplifica la creación y administración de claves CMEK mediante la automatización del aprovisionamiento y la asignación. Con la clave automática, no necesitas aprovisionar llaveros de claves, claves y cuentas de servicio con anticipación. En cambio, se generan a pedido como parte de la creación de recursos de Cloud Storage.

El uso de claves generadas por Autokey puede ayudarte a alinearte de manera coherente con los estándares de la industria y las prácticas recomendadas para la seguridad de los datos, como el nivel de protección, la separación de obligaciones, la rotación de claves, la ubicación y el nivel de detalle de la clave. Para obtener más información, consulta Descripción general de las claves automáticas.

Antes de comenzar

Antes de usar esta función en Cloud Storage, debes realizar las siguientes acciones:

Habilita la API de Cloud KMS del proyecto que almacenará tus claves de encriptación.

Habilitar la API
Obtén los permisos suficientes en el proyecto que almacenará tus claves de encriptación:
- Si eres propietario del proyecto que almacenará tus claves, lo más probable es que tengas el permiso necesario.
- Si planeas crear claves y llaveros de claves de encriptación nuevos, debes tener los permisos cloudkms.keyRings.create y cloudkms.cryptoKeys.create.
- Ya sea que planees usar claves o llaveros de claves nuevos o existentes, debes tener el permiso cloudkms.cryptoKeys.setIamPolicy para las claves que usarás en la encriptación.
  
  Este permiso te permite otorgar a los agentes de servicio de Cloud Storage acceso a las claves de Cloud KMS.
- Los permisos anteriores se encuentran en la función de administrador de Cloud KMS.
  
  Consulta Usa IAM con Cloud KMS para más instrucciones sobre cómo obtener estas o algunas otras funciones de Cloud KMS.
Obtén un llavero de claves de Cloud KMS y al menos una clave dentro de este.

El llavero de claves debe estar en la misma ubicación que los datos que deseas encriptar, pero puede estar en un proyecto diferente. Para conocer las ubicaciones de Cloud KMS disponibles, consulta las ubicaciones de Cloud KMS.
Nota: En la mayoría de las regiones dobles, debes crear el llavero de claves en la multirregión asociada, pero para las regiones dobles predefinidas ASIA1, EUR4 y NAM4, debes crear el llavero de claves en la misma región doble predefinida.
Ten permiso suficiente para trabajar con objetos en tu bucket de Cloud Storage:
- Si eres propietario del proyecto que contiene el bucket, es probable que tengas el permiso necesario.
- Si usas IAM, deberías tener el permiso storage.objects.create para escribir objetos en el bucket y storage.objects.get a fin de leer objetos del bucket. Consulta la sección sobre cómo usar permisos de IAM si quieres ver las instrucciones para obtener una función, como Administrador de objetos de almacenamiento, que tenga estos permisos.
- Si usas LCA, deberías tener un permiso WRITER para buckets a fin de escribir objetos en el bucket y un permiso READER para objetos a fin de leer objetos del bucket. Consulta la configuración de las LCA y obtén instrucciones para realizar esto.
Nota: El siguiente paso no es necesario si usas Google Cloud CLI.

Obtén la dirección de correo electrónico del agente de servicio asociado con el proyecto que contiene tu bucket de Cloud Storage. Si realizas este paso, crearás de forma automática el agente de servicio si no existe en la actualidad.

Asigna una clave de Cloud KMS a un agente de servicio

Para usar las claves de encriptación administradas por el cliente, otorga permiso al agente de servicio de Cloud Storage asociado con tu bucket para usar tu clave de Cloud KMS para encriptar y desencriptar:

Console

Abre el navegador de claves de Cloud Key Management Service en la consola de Google Cloud.
Abrir el navegador de claves de Cloud KMS
Haz clic en el nombre del llavero de claves que contiene la clave que deseas usar.
Selecciona la casilla de verificación de la clave que deseas.

La pestaña Permisos en el panel de la ventana derecha estará disponible.
En el cuadro de diálogo Agregar principales, especifica la dirección de correo electrónico del agente de servicio de Cloud Storage al que vas a otorgar acceso.
En el menú desplegable Seleccionar un rol, selecciona Encriptador/desencriptador de CryptoKey de Cloud KMS.
Haz clic en Agregar.

Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas de Cloud Storage en la consola de Google Cloud, consulta Solución de problemas.

Línea de comandos

Usa el comando gcloud storage service-agent con la marca --authorize-cmek a fin de otorgarle permiso al agente de servicio asociado con tu bucket para encriptar y desencriptar objetos con tu clave de Cloud KMS:

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

Aquí:

PROJECT_STORING_OBJECTS es el ID o el número del proyecto que contiene los objetos que deseas encriptar o desencriptar. Por ejemplo, my-pet-project.
KEY_RESOURCE es el recurso de clave de Cloud KMS.

Bibliotecas cliente

C#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage 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 de REST

API de JSON

Tener la gcloud CLI instalada e inicializada para generar un token de acceso para el encabezado Authorization.

Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado Authorization.
Crea un archivo JSON que contenga la siguiente información:
```
{
  "policy": {
    "bindings": {
      "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
      "members": "serviceAccount:SERVICE_AGENT_EMAIL_ADDRESS"
    },
  }
}
```
En el ejemplo anterior, SERVICE_AGENT_EMAIL_ADDRESS es la dirección de correo electrónico asociada a tu agente de servicio. Por ejemplo, service-7550275089395@gs-project-accounts.iam.gserviceaccount.com

Usa cURL para llamar a la API de Cloud KMS con una solicitud 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"

Aquí:

JSON_FILE_NAME es la ruta de acceso del archivo JSON que creaste en el paso 2.
KEY_RESOURCE es el recurso de clave de Cloud KMS.

API de XML

La API de XML no se puede usar para asignar Cloud KMS a un agente de servicio. En su lugar, usa una de las otras herramientas de Cloud Storage, como la gcloud CLI.

Usa las claves de encriptación predeterminadas

Establece la clave predeterminada de un bucket

Sigue los pasos que se indican a continuación para agregar, cambiar o quitar la clave de Cloud KMS que se usa de forma predeterminada cuando los objetos se escriben en un bucket:

Console

En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.
Ir a Buckets
En la lista de buckets, haz clic en el nombre del bucket deseado.
En la página de detalles del bucket haz clic en la pestaña Configuración.
Haz clic en el ícono de lápiz asociado a la entrada Tipo de encriptación.
Configura o quita la clave de Cloud KMS predeterminada para el bucket.
1. Si el bucket no usa actualmente una clave de Cloud KMS, marca el botón de selección Clave administrada por el cliente y, luego, selecciona una de las claves disponibles en el menú desplegable asociado.
2. Si actualmente el bucket usa una clave de Cloud KMS, cambia la clave de Cloud KMS en el menú desplegable o quita la clave de Cloud KMS mediante el botón de selección Clave administrada por Google.
Haz clic en Guardar.

Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas de Cloud Storage en la consola de Google Cloud, consulta Solución de problemas.

Línea de comandos

Usa el comando gcloud storage buckets update con la marca adecuada:

gcloud storage buckets update gs://BUCKET_NAME FLAG

Donde:

BUCKET_NAME es el nombre del bucket correspondiente. Por ejemplo, my-bucket.
FLAG es la configuración deseada para la clave predeterminada en el bucket. Usa uno de los siguientes formatos:
- --default-encryption-key= y un recurso de clave de Cloud KMS, si deseas agregar o cambiar una clave predeterminada.
- --clear-default-encryption-key, si deseas quitar la clave predeterminada del bucket.

Si se ejecuta de forma correcta, la respuesta se ve de la siguiente manera:

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

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

En el siguiente ejemplo, se establece una clave de encriptación predeterminada administrada por el cliente en un bucket:

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