Chaves de encriptação geridas pelo cliente (CMEK)

Por predefinição, Google Cloud encripta automaticamente os dados quando estão em repouso através de chaves de encriptação geridas pela Google.

Se tiver requisitos regulamentares ou de conformidade específicos relacionados com as chaves que protegem os seus dados, pode usar chaves de encriptação geridas pelo cliente (CMEK) para a IA Documentos. Em vez de a Google gerir as chaves de encriptação que protegem os seus dados, o processador do Document AI é protegido através de uma chave que controla e gere no Cloud Key Management Service (KMS).

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

Pré-requisito

O agente de serviço do Document AI tem de ter a função de encriptador/desencriptador de CryptoKey do Cloud KMS na chave que usa.

O exemplo seguinte concede uma função 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 conjunto de chaves onde a chave está localizada. Substitua location pela localização da IA Documentos para o porta-chaves. Substitua key_project_id pelo projeto do porta-chaves. Substitua project_number pelo número do seu projeto.

C#

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

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Document AI.

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Document AI.

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Document AI.

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Document AI.

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Document AI.

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Document AI.

Para se autenticar no Document AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 CMEK

As definições de encriptação estão disponíveis quando cria um processador. Para usar as CMEK, selecione a opção CMEK e selecione uma chave.

Nota: a localização da chave tem de corresponder à localização do processador. Por exemplo, se o seu processador estiver localizado em europe-west2, a chave CMEK correspondente também tem de estar localizada em europe-west2. No entanto, para as us e eu multirregiões, a chave tem de estar em us-central1 e europe-west4, respetivamente.

A chave CMEK é usada para todos os dados associados ao processador e aos respetivos recursos subordinados. Todos os dados relacionados com clientes que são enviados para o processador são encriptados automaticamente com a chave fornecida antes de serem escritos no disco.

Depois de criar um processador, não pode alterar as respetivas definições de encriptação. Para usar uma chave diferente, tem de criar um novo processador.

Chaves externas

Pode usar o Cloud External Key Manager (EKM) para criar e gerir chaves externas para encriptar dados no Google Cloud.

Quando usa uma chave do Cloud EKM, a Google não tem controlo sobre a disponibilidade da sua chave gerida externamente. Se pedir acesso a um recurso encriptado com uma chave gerida externamente e a chave não estiver disponível, o Document AI rejeita o pedido. Pode haver um atraso de até 10 minutos antes de poder aceder ao recurso depois de a chave ficar disponível.

Para mais considerações ao usar chaves externas, consulte as considerações do EKM.

Recursos suportados pela CMEK

Quando armazena qualquer recurso no disco, se forem armazenados dados de clientes como parte do recurso, o Document AI encripta primeiro o conteúdo através da chave CMEK.

Recurso	Material encriptado
Processor	N/A – Sem dados do utilizador. No entanto, se especificar uma chave CMEK durante a criação do processador, esta tem de ser válida.
ProcessorVersion	Tudo
Evaluation	Tudo

APIs suportadas pela CMEK

As APIs que usam a chave CMEK para encriptação incluem o seguinte:

Método	Encriptação
processDocument	N/A: não foram guardados dados no disco.
batchProcessDocuments	Os dados são armazenados temporariamente no disco e encriptados através de uma chave efémera (consulte a conformidade com a CMEK).
trainProcessorVersion	Os documentos usados para a preparação são encriptados através da chave KMS/CMEK fornecida.
evaluateProcessorVersion	As avaliações são encriptadas através da chave KMS/CMEK fornecida.

Os pedidos de API que acedem a recursos encriptados falham se a chave estiver desativada ou inacessível. Os exemplos incluem o seguinte:

Método	Desencriptação
getProcessorVersion	As versões do processador preparadas com dados de clientes são encriptadas. O acesso requer desencriptação.
processDocument	O processamento de documentos através de uma versão do processador encriptada requer a desencriptação.
Import Documents	A importação de documentos com a opção auto-labeling ativada através de uma versão do processador encriptada requer a desencriptação.

CMEK e Cloud Storage

As APIs, como a batchProcess, podem ler e escrever em contentores do Cloud Storage.

Todos os dados escritos no Cloud Storage pelo Document AI são encriptados através da chave de encriptação configurada do contentor, que pode ser diferente da chave CMEK do seu processador.

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