Claves de encriptación administradas por el cliente (CMEK)

De forma predeterminada, Google Cloud encripta los datos cuando están en reposo automáticamente con claves de encriptación administradas por Google.

Si tienes requisitos normativos o de cumplimiento específicos relacionados con las claves que protegen los datos, puedes usar claves de encriptación administradas por el cliente (CMEK) para Document AI. En lugar de que Google administre las claves de encriptación que protegen tus datos, tu procesador de Document AI se protege con una clave que tú controlas y administras en Cloud Key Management Service (KMS).

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

Requisitos

El agente de servicio de Document AI debe tener el rol de Encriptador/Desencriptador de CryptoKey de Cloud KMS en la clave que usas.

En el siguiente ejemplo, se otorga una función 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:[e-mail] \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter

Reemplaza key por el nombre de la clave. Reemplaza key-ring por el nombre del llavero de claves en el que se encuentra la clave. Reemplaza location por la ubicación de Document AI para el llavero de claves. Reemplaza key_project_id por el proyecto del llavero de claves. Reemplaza 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 de Document AI C#.

Para autenticarte en Document AI, 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:[e-mail]")
    {
        // 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.IAMPolicyClientte-xref-link" href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html" track-type="exampleCode" track-name="xrefLink" track-metadata-lang="DOT"NET" track-metadata-modifier="Google.Cloud".Iam.V1" track-metadata-href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html">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.IAMPolicyClientte-xref-link" href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html" track-type="exampleCode" track-name="xrefLink" track-metadata-lang="DOTNET" track-metadata-modifier="Google.Cloud.Iam.V1" track-metadata-href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html">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 de Document AI Go.

Para autenticarte en Document AI, 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.

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:[e-mail]"

	// 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 de Document AI Java.

Para autenticarte en Document AI, 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.

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:[e-mail]";
    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 de Document AI Node.js.

Para autenticarte en Document AI, 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.

//
// 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:[e-mail]';

// 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 de Document AI PHP.

Para autenticarte en Document AI, 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.

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:[e-mail]'
) {
    // 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 de Document AI Python.

Para autenticarte en Document AI, 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.

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:[e-mail]')

    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 de Document AI Ruby.

Para autenticarte en Document AI, 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.

# 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:[e-mail]"

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

Usa CMEK

La configuración de encriptación está disponible cuando creas un procesador. Para usar CMEK, selecciona la opción CMEK y elige una clave.

Nota: La ubicación de la clave debe coincidir con la ubicación del procesador. Por ejemplo, si tu procesador se encuentra en europe-west2, la clave de CMEK correspondiente también debe estar en europe-west2. Sin embargo, para las multirregiones us y eu, la clave debe estar en us-central1 y europe-west4, respectivamente.

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

Una vez que se crea un procesador, no puedes cambiar su configuración de encriptación. Para usar una clave diferente, debes crear un procesador nuevo.

Claves externas

Puedes usar Cloud External Key Manager (EKM) para crear y administrar claves externas que encripten datos en Google Cloud.

Cuando usas una clave de Cloud EKM, Google no tiene control sobre la disponibilidad de tu clave administrada de forma externa. Si solicitas acceso a un recurso encriptado con una clave administrada de forma externa 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 una vez que la clave esté disponible.

Para obtener más consideraciones sobre el uso de claves externas, consulta Consideraciones de EKM.

Recursos compatibles con CMEK

Cuando se almacena cualquier recurso en el disco, si se almacenan datos del cliente como parte del recurso, Document AI primero encripta el contenido con la clave de CMEK.

Recurso	Material encriptado
Processor	N/A: No hay datos del usuario. Sin embargo, si especificas una clave de CMEK durante la creación del procesador, esta debe ser válida.
ProcessorVersion	Todos
Evaluation	Todos

APIs compatibles con CMEK

Entre las APIs que usan la clave CMEK para la encriptación, se incluyen las siguientes:

Método	Encriptación
processDocument	N/A: No hay datos guardados en el disco.
batchProcessDocuments	Los datos se almacenan temporalmente en el disco y se encriptan con una clave efímera (consulta Cumplimiento de CMEK).
trainProcessorVersion	Los documentos que se usan para el entrenamiento se encriptan con la clave de KMS o CMEK proporcionada.
evaluateProcessorVersion	Las evaluaciones se encriptan con la clave de KMS o CMEK proporcionada.

Las solicitudes a la API que acceden a recursos encriptados fallan si la clave está inhabilitada o no se puede acceder a ella. Algunos ejemplos son los siguientes:

Método	Desencriptación
getProcessorVersion	Las versiones del procesador entrenadas con datos del cliente están encriptadas. El acceso requiere desencriptación.
processDocument	El procesamiento de documentos con una versión del procesador encriptada requiere desencriptación.
Import Documents	La importación de documentos con auto-labeling habilitado con una versión de procesador encriptada requiere desencriptación.

CMEK y Cloud Storage

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

Document AI encripta los datos que escribe en Cloud Storage con la clave de encriptación configurada del bucket, 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.