Chiavi di crittografia gestite dal cliente (CMEK)

Per impostazione predefinita, Google Cloud cripta automaticamente i dati quando sono in stato at-rest utilizzando chiavi di crittografia gestite da Google.

Se hai requisiti di conformità o normativi specifici relativi alle chiavi che proteggono i tuoi dati, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per Document AI. Invece che da Google, le chiavi di crittografia che proteggono i tuoi dati vengono gestite dal tuo elaboratore Document AI utilizzando una chiave che controlli e gestisci in Cloud Key Management Service (KMS).

Questa guida descrive CMEK per Document AI. Per ulteriori informazioni su CMEK in generale, incluso quando e perché attivarlo, consulta la documentazione di Cloud Key Management Service.

Prerequisito

L'agente di servizio Document AI deve disporre del ruolo Autore crittografia/decrittografia CryptoKey Cloud KMS per la chiave che utilizzi.

L'esempio seguente concede un ruolo che fornisce l'accesso a una chiave Cloud KMS:

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

Sostituisci key con il nome della chiave. Sostituisci key-ring con il nome del mazzo di chiavi in cui si trova la chiave. Sostituisci location con la posizione di Document AI per il portachiavi. Sostituisci key_project_id con il progetto per la chiave automatizzata. Sostituisci project_number con il numero del tuo progetto.

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI C#.

Per autenticarti a Document AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.


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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Go.

Per autenticarti a Document AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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
}

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Java.

Per autenticarti a Document AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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());
    }
  }
}

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Node.js.

Per autenticarti a Document AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

//
// 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();

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI PHP.

Per autenticarti a Document AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.

Per autenticarti a Document AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Ruby.

Per autenticarti a Document AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Utilizzo di CMEK

Le impostazioni di crittografia sono disponibili quando crei un elaboratore. Per utilizzare CMEK, seleziona l'opzione CMEK e una chiave.

security-3

La chiave CMEK viene utilizzata per tutti i dati associati al processore e alle sue risorse secondarie. Tutti i dati relativi ai clienti inviati al responsabile del trattamento vengono criptati automaticamente con la chiave fornita prima della scrittura su disco.

Una volta creato un elaboratore, non puoi modificare le relative impostazioni di crittografia. Per utilizzare una chiave diversa, devi creare un nuovo elaboratore.

Chiavi esterne

Puoi utilizzare Cloud External Key Manager (EKM) per creare e gestire le chiavi esterne per criptare i dati in Google Cloud.

Quando utilizzi una chiave Cloud EKM, Google non ha alcun controllo sulla disponibilità della chiave con gestione esterna. Se richiedi l'accesso a una risorsa criptata con una chiave gestita esternamente e la chiave non è disponibile, Document AI rifiuterà la richiesta. Potrebbe essere necessario attendere fino a 10 minuti prima di poter accedere alla risorsa dopo che la chiave è diventata disponibile.

Per ulteriori considerazioni sull'utilizzo delle chiavi esterne, consulta Considerazioni sulle chiavi EKM.

Risorse supportate da CMEK

Quando archivi una risorsa su disco, se i dati dei clienti sono archiviati all'interno della risorsa, Document AI cripta prima i contenuti utilizzando la chiave CMEK.

Risorsa Materiale criptato
Processor N/A - nessun dato utente. Tuttavia, se specifichi una chiave CMEK durante la creazione del processore, questa deve essere valida.
ProcessorVersion Tutti
Evaluation Tutti

API supportate da CMEK

Le API che utilizzano la chiave CMEK per la crittografia includono:

Metodo Crittografia
processDocument N/A: nessun dato salvato sul disco.
batchProcessDocuments I dati vengono archiviati temporaneamente su disco e criptati utilizzando una chiave effimera (vedi Conformità a CMEK).
trainProcessorVersion I documenti utilizzati per l'addestramento vengono criptati utilizzando la chiave KMS/CMEK fornita.
evaluateProcessorVersion Le valutazioni vengono criptate utilizzando la chiave KMS/CMEK fornita.

Le richieste API che accedono alle risorse criptate non vanno a buon fine se la chiave è disabilitata o non è raggiungibile. Ecco alcuni esempi:

Metodo Decriptazione
getProcessorVersion Le versioni del processore addestrate utilizzando i dati dei clienti sono criptate. Per l'accesso è necessaria la decrittografia.
processDocument L'elaborazione dei documenti utilizzando una versione del processore criptata richiede la decrittografia.
Import Documents L'importazione di documenti con auto-labeling abilitato utilizzando una versione del processore criptata richiede la decrittografia.

CMEK e Cloud Storage

Le API, come batchProcess, possono leggere e scrivere nei bucket Cloud Storage.

Tutti i dati scritti in Cloud Storage da Document AI vengono criptati utilizzando la chiave di crittografia configurata del bucket, che può essere diversa dalla chiave CMEK del tuo elaboratore.

Per ulteriori informazioni, consulta la documentazione di CMEK per Cloud Storage.