Chiavi di crittografia gestite dal cliente (CMEK)

Per impostazione predefinita, Google Cloud automaticamente cripta i dati at-restutilizzando 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 di Google, il processore Document AI è protetto utilizzando una chiave che puoi controllare e gestire in Cloud Key Management Service (KMS).

Questa guida descrive le chiavi CMEK per Document AI. Per ulteriori informazioni sulle chiavi CMEK in generale, inclusi quando e perché abilitarle, consulta la documentazione di Cloud Key Management Service.

Prerequisito

L'agente di servizio Document AI Service Agent deve disporre del ruolo Cloud KMS CryptoKey Encrypter/Decrypter role per la chiave che utilizzi.

L'esempio seguente concede un ruolo che fornisce l'accesso a una chiave 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

Sostituisci key con il nome della chiave. Sostituisci key-ring con il nome del keyring in cui si trova la chiave. Sostituisci location con la località Document AI per il keyring. Sostituisci key_project_id con il progetto per il keyring. Sostituisci project_number con il numero del tuo progetto.

C#

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

Per eseguire l'autenticazione in Document AI, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura 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:[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

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

Per eseguire l'autenticazione in Document AI, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura 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:[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

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

Per eseguire l'autenticazione in Document AI, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura 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:[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

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

Per eseguire l'autenticazione in Document AI, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura 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:[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

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

Per eseguire l'autenticazione in Document AI, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura 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:[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

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

Per eseguire l'autenticazione in Document AI, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura 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:[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

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

Per eseguire l'autenticazione in Document AI, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura 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:[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}"

Utilizzo delle chiavi CMEK

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

Nota: la località della chiave deve corrispondere a quella del processore. Ad esempio, se il processore si trova in europe-west2, anche la chiave CMEK corrispondente deve trovarsi in europe-west2. Tuttavia, per le us e eu multiregioni, la chiave deve trovarsi rispettivamente in us-central1 e europe-west4.

La chiave CMEK viene utilizzata per tutti i dati associati al processore e alle relative risorse secondarie. Tutti i dati relativi ai clienti inviati al processore vengono criptati automaticamente con la chiave fornita prima di essere scritti su disco.

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

Chiavi esterne

Puoi utilizzare Cloud External Key Manager (EKM) per creare e gestire chiavi esterne per criptare i dati all'interno di Google Cloud.

Quando utilizzi una chiave Cloud EKM, Google non ha alcun controllo sulla disponibilità della chiave gestita esternamente. 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 su EKM.

Risorse supportate da CMEK

Quando archivia una risorsa su disco, se i dati dei clienti vengono archiviati come parte 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 le seguenti:

Metodo	Crittografia
processDocument	N/A: nessun dato salvato su disco.
batchProcessDocuments	I dati vengono archiviati temporaneamente su disco e criptati utilizzando una chiave effimera (vedi Conformità 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	Decrittografia
getProcessorVersion	Le versioni del processore addestrate utilizzando i dati dei clienti vengono criptate. L'accesso richiede 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 processore.

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