Esta página se ha traducido con Cloud Translation API.

Claves de encriptado gestionadas por el cliente (CMEK)

De forma predeterminada, Google Cloud cifra automáticamente los datos en reposo con claves de cifrado gestionadas por Google.

Si tienes requisitos de cumplimiento o normativas específicos relacionados con las claves que protegen tus datos, puedes usar claves de cifrado gestionadas por el cliente (CMEK) en Document AI. En lugar de que Google gestione las claves de cifrado que protegen tus datos, tu procesador de Document AI se protege con una clave que controlas y gestionas en Cloud Key Management Service (KMS).

En esta guía se describe la CMEK para Document AI. Para obtener más información sobre la CMEK en general, incluido cuándo y por qué habilitarla, consulta la documentación de Cloud Key Management Service.

Requisitos previos

El agente de servicio de Document AI debe tener el rol Encargado del encriptado y desencriptado de la clave criptográfica Cloud KMS en la clave que uses.

En el siguiente ejemplo se concede un rol que proporciona acceso a una clave de Cloud KMS:

gcloud

gcloud kms keys add-iam-policy-binding key \
    --keyring key-ring \
    --location location \
    --project key_project_id \
    --member serviceAccount:service-project_number@gcp-sa-prod-dai-core.iam.gserviceaccount.com \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter

Sustituye key por el nombre de la clave. Sustituye key-ring por el nombre del conjunto de claves en el que se encuentra la clave. Sustituye location por la ubicación de Document AI del conjunto de claves. Sustituye key_project_id por el proyecto del llavero de claves. Sustituye project_number por el número de tu proyecto.

C#

Para obtener más información, consulta la documentación de referencia de la API C# de Document AI.

Para autenticarte en Document AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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

Para obtener más información, consulta la documentación de referencia de la API Go de Document AI.

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

Para obtener más información, consulta la documentación de referencia de la API Java de Document AI.

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

Para obtener más información, consulta la documentación de referencia de la API Node.js de Document AI.

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

Para obtener más información, consulta la documentación de referencia de la API PHP de Document AI.

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

Para obtener más información, consulta la documentación de referencia de la API Python de Document AI.

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

Para obtener más información, consulta la documentación de referencia de la API Ruby de Document AI.

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

Usar CMEK

Los ajustes de cifrado están disponibles cuando crea un procesador. Para usar CMEK, selecciona la opción CMEK y elige una clave.

security-3

La clave de CMEK se usa para todos los datos asociados al procesador y a sus recursos secundarios. Todos los datos relacionados con los clientes que se envían al encargado del tratamiento se cifran automáticamente con la clave proporcionada antes de escribirse en el disco.

Una vez que se ha creado un procesador, no se pueden cambiar sus ajustes de cifrado. Para usar otra clave, debes crear un nuevo procesador.

Claves externas

Puedes usar Cloud External Key Manager (EKM) para crear y gestionar claves externas con las que cifrar datos en Google Cloud.

Cuando usas una clave de Cloud EKM, Google no tiene control sobre la disponibilidad de tu clave gestionada de forma externa. Si solicitas acceso a un recurso cifrado con una clave gestionada externamente y la clave no está disponible, Document AI rechazará la solicitud. Puede haber un retraso de hasta 10 minutos antes de que puedas acceder al recurso después de que la clave esté disponible.

Para obtener más información sobre las consideraciones al usar claves externas, consulta las consideraciones de EKM.

Recursos compatibles con CMEK

Cuando se almacena un recurso en el disco, si se almacena algún dato de cliente como parte del recurso, Document AI cifra primero el contenido con la clave CMEK.

Recurso	Material cifrado
`Processor`	N/A: no hay datos de usuario. Sin embargo, si especifica una clave CMEK durante la creación del procesador, esta debe ser válida.
`ProcessorVersion`	Todo
`Evaluation`	Todo

APIs compatibles con CMEK

Las APIs que usan la clave CMEK para el cifrado son las siguientes:

Método	Cifrado
`processDocument`	N/A: no se guardan datos en el disco.
`batchProcessDocuments`	Los datos se almacenan temporalmente en el disco y se cifran con una clave efímera (consulta la sección sobre el cumplimiento de CMEK).
`trainProcessorVersion`	Los documentos utilizados para el entrenamiento se cifran con la clave KMS o CMEK proporcionada.
`evaluateProcessorVersion`	Las evaluaciones se encriptan con la clave de KMS o CMEK proporcionada.

Las solicitudes de API que acceden a recursos cifrados fallan si la clave está inhabilitada o no se puede acceder a ella. Estos son algunos ejemplos:

Método	Desencriptado
`getProcessorVersion`	Las versiones del procesador entrenadas con datos de clientes están cifradas. Para acceder, es necesario descifrar.
`processDocument`	Para procesar documentos con una versión cifrada del procesador, es necesario descifrarlos.
`Import Documents`	Para importar documentos con la opción `auto-labeling` habilitada mediante una versión de procesador cifrada, es necesario descifrarlos.

CMEK y Cloud Storage

Las APIs, como batchProcess, pueden leer y escribir en segmentos de Cloud Storage.

Los datos que Document AI escribe en Cloud Storage se cifran con la clave de cifrado configurada del contenedor, que puede ser diferente de la clave CMEK de tu procesador.

Para obtener más información, consulta la documentación de CMEK para Cloud Storage.

Seguridad y cumplimiento

Añadir registro de auditoría