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

Por padrão, o Gemini Data Analytics criptografa o conteúdo do cliente em repouso. O Gemini Data Analytics executa a criptografia, e você não precisa fazer nada. Essa opção é chamada de criptografia padrão do Google.

Se você quiser controlar suas chaves de criptografia, use chaves de criptografia gerenciadas pelo cliente (CMEKs) no Cloud KMS com serviços integrados a CMEKs, incluindo o Gemini Data Analytics. Ao usar chaves do Cloud KMS, é possível controlar o nível de proteção, o local, a programação de rotação, as permissões de uso e acesso e os limites criptográficos. Com o Cloud KMS, também é possível visualizar registros de auditoria e controlar ciclos de vida de chaves. Em vez de o Google ser proprietário e gerente de chaves de criptografia de chaves (KEKs) simétricas que protegem seus dados, você controla e gerencia essas chaves no Cloud KMS.

Depois de configurar os recursos com CMEKs, a experiência de acesso aos recursos do Gemini Data Analytics é semelhante à criptografia padrão do Google. Para saber mais sobre suas opções de criptografia, consulte Chaves de criptografia gerenciadas pelo cliente (CMEK).

Nesta página, descrevemos como usar chaves de criptografia gerenciadas pelo cliente (CMEK) para proteger os dados usados pela API Conversational Analytics. A API Conversational Analytics é um produto do serviço Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK para recursos da API Conversational Analytics

Quando você configura a CMEK para um recurso da API Conversational Analytics, a chave do Cloud KMS especificada criptografa os dados sensíveis em repouso. É possível configurar a CMEK para recursos DataAgent e Conversation de maneira independente.

A CMEK para a API Conversational Analytics está disponível apenas em locais regionais e multirregionais, não no local global. Para saber os locais compatíveis com cada fonte de dados, consulte Locais de dados compatíveis.

O que é protegido com a CMEK

A CMEK para a API Conversational Analytics protege os seguintes dados em repouso:

  • Para recursos do DataAgent, todo o conteúdo principal do cliente no campo data_analytics_agent é protegido. Esse conteúdo inclui os campos staging_context, published_context e last_published_context, além dos campos system_instruction e example_queries.
  • Para recursos do Conversation, todos os dados de histórico de mensagens e estado são protegidos.

Os dados a seguir não são criptografados com a chave CMEK do cliente. Em vez disso, esses dados são protegidos pela criptografia padrão do Google:

  • Para recursos DataAgent, a criptografia padrão do Google protege campos de metadados como name, display_name, description, labels, create_time, update_time, delete_time, purge_time e kms_key.
  • Para recursos do Conversation, a criptografia padrão do Google protege campos de metadados como name, agents, labels, create_time, last_used_time e kms_key.

Limitações

A CMEK para a API Conversational Analytics tem as seguintes limitações:

  • A CMEK precisa ser configurada quando o recurso é criado. Não é possível adicionar ou alterar essa tag em um recurso atual.
  • As políticas da organização de CMEK não são compatíveis.
  • O local necessário da chave do Cloud KMS depende do tipo e do local do recurso. Em uma única região, a chave precisa estar na mesma região que o recurso. Na multirregião us ou eu, o local da chave para os recursos DataAgent e Conversation é diferente. Para mais informações, consulte Requisitos para locais da chave.
  • A região global não é compatível.
  • É possível usar apenas uma CMEK por projeto e por região para todos os recursos do Conversation nesse projeto e região.

Principais requisitos para locais

O local necessário da chave do Cloud KMS depende do tipo de recurso que você protege e do local desse recurso:

Local do recurso Local da chave para recursos do DataAgent Local da chave para recursos do Conversation
Multirregião us us us-central1
Multirregião eu europe europe-west1
Uma única região, como us-east4 A mesma região do recurso A mesma região do recurso

Os recursos do DataAgent em uma multirregião são armazenados na multirregião especificada no nome do recurso. Portanto, a chave precisa estar na multirregião correspondente do Cloud KMS. Para a multirregião us, o local do Cloud KMS também é us. Para a multirregião eu, o local do Cloud KMS é europe, porque o Cloud KMS não tem um local eu. Para mais informações, consulte Locais do Cloud KMS.

Os recursos do Conversation em uma multirregião são armazenados em uma região específica dentro dessa multirregião: us-central1 para us e europe-west1 para eu. A chave precisa estar nessa região. Por exemplo, para proteger um recurso Conversation chamado projects/PROJECT_ID/locations/us/conversations/CONVERSATION_ID, use uma chave no local us-central1.

Antes de começar

Antes de usar a CMEK com a API Conversational Analytics, siga estas etapas:

  1. Ative as APIs necessárias no console do Google Cloud ou na Google Cloud CLI.

    Console

    Ative as seguintes APIs no console do Google Cloud para o projeto do Google Cloud .

    Ativar a API Gemini Data Analytics

    Ativar a API Gemini para Google Cloud

    Ativar a API Cloud Key Management Service

    gcloud

    Com a Google Cloud CLI, execute os seguintes comandos gcloud services enable para ativar a API Gemini Data Analytics, a API Gemini para Google Cloud e a API Cloud Key Management Service, respectivamente:

    gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable cloudkms.googleapis.com --project=project_id

    Nos comandos de exemplo da CLI gcloud, substitua project_id pelo ID do projeto do Google Cloud .

  2. Crie um keyring e uma chave do Cloud KMS no local necessário para os recursos da API Conversational Analytics, conforme descrito em Requisitos de local da chave. Para mais informações, consulte Criar uma chave.

  3. Crie os agentes de serviço gerenciados pelo Google, também conhecidos como contas de serviço por produto por projeto (P4SAs, na sigla em inglês), se eles ainda não existirem. Esses agentes de serviço são necessários para permitir que os serviços envolvidos na proteção dos recursos da API Conversational Analytics com CMEK acessem sua chave do Cloud KMS.

    Execute os seguintes comandos gcloud para criar os agentes de serviço: 

    gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
    Substitua PROJECT_ID pelo ID do projeto do Google Cloud .

  4. Conceda o papel Criptografador/descriptografador de CryptoKey do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) no Identity and Access Management (IAM) aos dois agentes de serviço criados na etapa anterior para permitir que o serviço de análise de dados do Gemini use sua chave do Cloud KMS para criptografar e descriptografar os dados da API Conversational Analytics. Se você usar mais de uma chave, por exemplo, chaves separadas para recursos DataAgent e Conversation na multirregião us ou eu, conceda o papel em cada chave.

    Conceda a permissão ao agente de serviço do Gemini Data Analytics:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    Conceda a permissão ao agente de serviço da API Gemini para Google Cloud :

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    Nos exemplos de código anteriores, substitua os valores de amostra da seguinte forma:

    • KEY_NAME: o nome da chave do Cloud KMS.
    • KEY_LOCATION: a região do keyring (por exemplo, us-east4).
    • KEY_RING_NAME: o nome do keyring
    • PROJECT_NUMBER: o número do projeto do Google Cloud em que você está criando recursos de API.
    • KMS_PROJECT_ID: o ID do projeto em que a chave foi criada. Pode ser o mesmo projeto em que você está criando recursos de API.

Proteger recursos com CMEK

Nesta seção, mostramos como proteger um novo recurso DataAgent ou Conversation com CMEK usando a API REST para especificar uma chave do Cloud KMS no campo kms_key durante a criação do recurso.

Só é possível ativar a CMEK ao criar um recurso DataAgent ou Conversation.

O local necessário de uma chave do Cloud KMS depende do tipo e do local do recurso que ela protege. Para mais informações, consulte Requisitos para locais da chave.

Proteger um recurso do DataAgent com CMEK

Para proteger um novo recurso DataAgent com CMEK, especifique uma chave do Cloud KMS no campo kms_key ao criar o agente de dados.

SDK do Python

O exemplo a seguir mostra como especificar uma chave do Cloud KMS ao criar um recurso DataAgent com o SDK do Python. Para conferir um exemplo de uma solicitação create completa, consulte Criar um agente de dados usando o SDK do Python.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_data_agent = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

No exemplo anterior, substitua os valores da seguinte forma:

  • BILLING_PROJECT_ID: o ID do projeto de faturamento.
  • KEY_RING_NAME: o nome do keyring do Cloud KMS.
  • KEY_NAME: o nome da chave do Cloud KMS.
  • KMS_PROJECT_ID: o ID do projeto em que a chave foi criada. Se deixado em branco, billing_project será usado.
  • LOCATION: o local do agente de dados, por exemplo, us, eu ou us-east4.
  • KEY_LOCATION: o local do keyring. Para a multirregião eu, use europe. Para todos os outros locais, use o mesmo local de LOCATION. Se deixado em branco, o padrão será o local do agente de dados, que funciona para todos os locais, exceto a multirregião eu.

HTTP

O exemplo a seguir mostra como especificar uma chave do Cloud KMS no corpo da solicitação ao criar um recurso DataAgent com HTTP e Python. Para ver um exemplo de uma solicitação create completa, consulte Criar um agente de dados usando HTTP e Python.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

No exemplo anterior, substitua os valores da seguinte forma:

  • KEY_RING_NAME: o nome do keyring do Cloud KMS.
  • KEY_NAME: o nome da chave do Cloud KMS.
  • KMS_PROJECT_ID: o ID do projeto em que a chave foi criada.
  • LOCATION: o local do agente de dados, por exemplo, us, eu ou us-east4.
  • KEY_LOCATION: o local do keyring. Para a multirregião eu, use europe. Para todos os outros locais, use o mesmo local do agente de dados.

Proteger um recurso do Conversation com CMEK

Para proteger um novo recurso do Conversation com CMEK, especifique uma chave do Cloud KMS no campo kms_key ao criar a conversa.

SDK do Python

O exemplo a seguir mostra como especificar uma chave do Cloud KMS ao criar um recurso Conversation com o SDK do Python. Para conferir um exemplo de uma solicitação create completa, consulte Criar um agente de dados usando o SDK do Python.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_conversation = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

No exemplo anterior, substitua os valores da seguinte forma:

  • BILLING_PROJECT_ID: o ID do projeto de faturamento.
  • KEY_RING_NAME: o nome do keyring do Cloud KMS.
  • KEY_NAME: o nome da chave do Cloud KMS.
  • KMS_PROJECT_ID: o ID do projeto em que a chave foi criada. Se deixado em branco, billing_project será usado.
  • LOCATION: o local da conversa e do agente de dados, por exemplo, us, eu ou us-east4.
  • KEY_LOCATION: o local do keyring. Para a multirregião us, use us-central1. Para a multirregião eu, use europe-west1. Para uma única região, use a mesma região de LOCATION. Se deixado em branco, o padrão será o local da conversa, que funciona apenas para regiões únicas.

HTTP

O exemplo a seguir mostra como especificar uma chave do Cloud KMS no corpo da solicitação ao criar um recurso Conversation com HTTP e Python. Para ver um exemplo de uma solicitação create completa, consulte Criar um agente de dados usando HTTP e Python.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
}

No exemplo anterior, substitua os valores da seguinte forma:

  • KEY_RING_NAME: o nome do keyring do Cloud KMS.
  • KEY_NAME: o nome da chave do Cloud KMS.
  • KMS_PROJECT_ID: o ID do projeto em que a chave foi criada.
  • LOCATION: o local da conversa e do agente de dados, por exemplo, us, eu ou us-east4.
  • KEY_LOCATION: o local do keyring. Para a multirregião us, use us-central1. Para a multirregião eu, use europe-west1. Para uma única região, use a mesma região da conversa.

Solução de problemas

Nesta seção, abordamos problemas comuns e considerações importantes ao usar CMEKs com a API Conversational Analytics.

Mudanças de estado importantes

Se uma versão de chave do Cloud KMS que protege um recurso da API Conversational Analytics ficar indisponível, você vai perder o acesso aos dados criptografados por essa chave. Se você tentar acessar dados protegidos enquanto a chave estiver indisponível, por exemplo, lendo o contexto de um recurso do DataAgent ou acessando o histórico do Conversation, a solicitação vai falhar. O erro retornado depende do motivo da indisponibilidade da chave:

  • Se a versão da chave estiver desativada ou destruída, a operação geralmente vai falhar com um erro FAILED_PRECONDITION.
  • Se o papel do IAM cloudkms.cryptoKeyEncrypterDecrypter for revogado do agente de serviço gcp-sa-geminidataanalytics ou gcp-sa-cloudaicompanion, a operação geralmente falhará com um erro PERMISSION_DENIED ou NOT_FOUND.

Mesmo quando a chave não está disponível, ainda é possível realizar operações que não exigem a descriptografia do conteúdo, como excluir o recurso DataAgent ou Conversation.

Para restaurar o acesso aos dados criptografados, reative a chave e verifique se os agentes de serviço têm as permissões do IAM necessárias, conforme descrito em Antes de começar.

Cotas do Cloud KMS e a API Conversational Analytics

Quando você usa CMEK na API Conversational Analytics, seus projetos podem consumir cotas de solicitações criptográficas do Cloud KMS. Por exemplo, para ler um recurso DataAgent ou acessar o histórico de Conversation protegido por CMEK, o Cloud KMS precisa descriptografar os dados.

As operações de criptografia e descriptografia com chaves CMEK afetam as cotas do Cloud KMS destas maneiras:

  • Para chaves CMEK de software geradas no Cloud KMS, nenhuma cota do Cloud KMS é consumida.
  • Para chaves CMEK externas, às vezes chamadas de chaves do Cloud EKM, as operações de criptografia e descriptografia são descontadas das cotas do Cloud EKM no projeto que contém a chave.

Para mais informações, consulte Cotas do Cloud KMS.

A seguir