Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês)

Por padrão,o Google Cloud automaticamente criptografa os dados quando em repouso usando chaves de criptografia gerenciadas pelo Google.

Caso você precise atender a requisitos específicos de compliance e conformidade relacionados às chaves que protegem seus dados, use as chaves de criptografia gerenciadas pelo cliente (CMEKs) para a Document AI. Em vez de o Google gerenciar as chaves de criptografia que protegem seus dados, seu processador da Document AI é protegido usando uma chave que você controla e gerencia no Cloud Key Management Service (KMS).

Este guia descreve a CMEK para a Document AI. Para mais informações sobre CMEK em geral, como quando e por que ativar, consulte a documentação do Cloud Key Management Service.

Pré-requisito

O agente de serviço da Document AI precisa ter a função de criptografador/descriptografador de CryptoKey do Cloud KMS na chave que você usa.

O exemplo a seguir concede um papel que fornece acesso a uma chave do 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

Substitua key pelo nome da chave. Substitua key-ring pelo nome do keyring em que a chave está localizada. Substitua location pelo local da Document AI para o keyring. Substitua key_project_id pelo projeto do keyring. Substitua project_number pelo número do projeto.

C#

Para mais informações, consulte a documentação de referência da API C# da Document AI.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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.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 mais informações, consulte a documentação de referência da API Go da Document AI.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API Java da Document AI.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API Node.js da Document AI.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API PHP da Document AI.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API Python da Document AI.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API Ruby da Document AI.

Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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}"

Usar a CMEK

As configurações de criptografia estão disponíveis quando você cria um processador. Para usar a CMEK, selecione a opção CMEK e escolha uma chave.

Observação: o local da chave precisa corresponder ao local do processador. Por exemplo, se o processador estiver localizado em europe-west2, a chave CMEK correspondente também precisará estar em europe-west2. No entanto, para as multirregiões us e eu, a chave precisa estar em us-central1 e europe-west4, respectivamente.

A chave CMEK é usada para todos os dados associados ao processador e aos recursos filhos dele. Todos os dados relacionados ao cliente enviados ao processador são criptografados automaticamente com a chave fornecida antes de serem gravados em disco.

Depois que um processador é criado, não é possível mudar as configurações de criptografia dele. Para usar uma chave diferente, crie um novo processador.

Chaves externas

Use o Cloud External Key Manager (EKM) para criar e gerenciar chaves externas para criptografar dados no Google Cloud.

Quando você usa uma chave do Cloud EKM, o Google não tem controle sobre a disponibilidade da sua chave gerenciada externamente. Se você solicitar acesso a um recurso criptografado com uma chave gerenciada externamente e a chave não estiver disponível, a Document AI vai rejeitar a solicitação. Pode haver um atraso de até 10 minutos antes de você conseguir acessar o recurso quando a chave estiver disponível.

Para mais considerações ao usar chaves externas, consulte Considerações sobre o EKM.

Recursos compatíveis com a CMEK

Ao armazenar qualquer recurso em disco, se dados do cliente forem armazenados como parte do recurso, a Document AI primeiro criptografa o conteúdo usando a chave de CMEK.

Recurso	Material criptografado
Processor	N/A: sem dados do usuário. No entanto, se você especificar uma chave CMEK durante a criação do processador, ela precisará ser válida.
ProcessorVersion	Todos
Evaluation	Todos

APIs compatíveis com CMEK

As APIs que usam a chave CMEK para criptografia incluem:

Método	Criptografia
processDocument	Não aplicável: nenhum dado salvo no disco.
batchProcessDocuments	Os dados são armazenados temporariamente no disco e criptografados usando uma chave temporária (consulte Conformidade com a CMEK).
trainProcessorVersion	Os documentos usados para treinamento são criptografados com a chave do KMS/CMEK fornecida.
evaluateProcessorVersion	As avaliações são criptografadas usando a chave KMS/CMEK fornecida.

As solicitações de API que acessam recursos criptografados falham se a chave estiver desativada ou inacessível. Os exemplos incluem:

Método	Descriptografia
getProcessorVersion	As versões do processador treinadas com dados do cliente são criptografadas. O acesso exige descriptografia.
processDocument	O processamento de documentos usando uma versão criptografada do processador exige descriptografia.
Import Documents	A importação de documentos com o auto-labeling ativado usando uma versão criptografada do processador exige descriptografia.

CMEK e Cloud Storage

APIs, como batchProcess, podem ler e gravar em buckets do Cloud Storage.

Todos os dados gravados no Cloud Storage pela Document AI são criptografados usando a chave de criptografia configurada do bucket, que pode ser diferente da chave CMEK do seu processador.

Para mais informações, consulte a documentação da CMEK para o Cloud Storage.