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 processa a criptografia para você sem nenhuma ação adicional da sua parte. 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 seus 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 dados usados pela API Análises de conversação com fontes de dados do Looker. A API Análises de conversação é um produto do serviço Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK para recursos da API Análises de conversação

Ao configurar a CMEK para um recurso da API Análises de conversação, a chave especificada do Cloud KMS criptografa os dados sensíveis em repouso. É possível configurar a CMEK para recursos DataAgent e Conversation de forma independente.

Só é possível configurar a CMEK no momento da criação do recurso. Para usar a CMEK, especifique o campo kms_key ao criar um recurso DataAgent ou Conversation. Não é possível adicionar ou alterar uma chave do Cloud KMS em um recurso atual.

O que é protegido com a CMEK

A CMEK para a API Análises de conversação protege os seguintes dados em repouso:

DataAgent recursos: todo o conteúdo principal do cliente nos campos staging_context, published_context e last_published_context do data_analytics_agent. Isso inclui campos como system_instruction e example_queries.
Recursos Conversation: todas as mensagens e o histórico de estados.

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:

Recursos DataAgent: campos de metadados, incluindo name, display_name, description, labels, create_time, update_time, delete_time, purge_time e kms_key
Recursos Conversation: campos de metadados, incluindo name, agents, labels, create_time, last_used_time e kms_key

Limitações

A CMEK para a API Análises de conversação tem as seguintes limitações:

A CMEK precisa ser configurada quando o recurso é criado. Não é possível adicioná-la ou alterá-la em um recurso atual.
A chave do Cloud KMS e o recurso da API Análises de conversação precisam estar no mesmo local. A região global está indisponível.
Para recursos da API Análises de conversação, a CMEK é compatível com a região us-east4.
Para recursos da API Análises de conversação, a CMEK só é compatível com fontes de dados do Looker.
Só é possível usar uma CMEK por projeto por região para todos os recursos Conversation nesse projeto e região.

Antes de começar

Antes de usar a CMEK com a API Análises de conversação, siga estas etapas:

Ative as APIs necessárias no Google Cloud console ou na Google Cloud CLI.
Console
Ative as seguintes APIs no Google Cloud console do seu Google Cloud project.

Ativar a API Gemini Data Analytics

Ativar o Gemini for Google Cloud API

Ativar a API Cloud Key Management Service

Dica:ao ativar uma API, pode ser necessário atualizar apágina do console para confirmar que ela está ativada.
Google Cloud
gcloud
Com a Google Cloud CLI, execute os seguintes comandos gcloud services enable para ativar a API Gemini Data Analytics, o Gemini for Google Cloud API 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 da CLI gcloud de exemplo anteriores, substitua project_id pelo ID do seu Google Cloud projeto.
Adicione seu projeto à lista de permissões.

Seu Google Cloud projeto precisa ser adicionado a uma lista de permissões para usar a CMEK com o Gemini Data Analytics. Para solicitar que seu projeto seja adicionado à lista de permissões, envie o ID do projeto pelo formulário de lista de permissões da CMEK do GDA. A adição do projeto à lista de permissões leva aproximadamente um a dois dias úteis para ser concluída.
Crie um keyring e uma chave do Cloud KMS no mesmo local dos recursos da API Análises de conversação. Para mais informações, consulte Criar uma chave.
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 Análises de conversação com a 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 seu Google Cloud projeto.
Conceda o papel Criptografador/Descriptografador do Cloud KMS CryptoKey (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 Gemini Data Analytics use sua chave do Cloud KMS para criptografar e descriptografar os dados da API Análises de conversação.

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.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
Conceda a permissão ao agente de serviço do Gemini for Google Cloud API:
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
Nos exemplos de código anteriores, substitua os valores de exemplo da seguinte maneira:
- 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 seu Google Cloud projeto 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 a CMEK

Esta seção mostra como proteger um novo recurso DataAgent ou Conversation com a 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.

Uma chave CMEK precisa estar na mesma região do recurso que ela protege. Saiba mais em Limitações.

Proteger um recurso `DataAgent` com a CMEK

Para proteger um novo recurso DataAgent com a 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 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" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_data_agent = f"projects/{key_project}/locations/{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 maneira:

BILLING_PROJECT_ID: o ID do seu 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: a região do keyring.

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 um exemplo de uma solicitação create completa, consulte Criar um agente de dados usando HTTP e Python.

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/{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 maneira:

KMS_PROJECT_ID: o ID do projeto em que a chave foi criada.
LOCATION: a região do keyring.
KEY_RING_NAME: o nome do keyring do Cloud KMS.
KEY_NAME: o nome da chave do Cloud KMS.

Proteger um recurso `Conversation` com a CMEK

Para proteger um novo recurso Conversation com a 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 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" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_conversation = f"projects/{key_project}/locations/{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 maneira:

BILLING_PROJECT_ID: o ID do seu 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: a região do keyring.

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 um exemplo de uma solicitação create completa, consulte Criar um agente de dados usando HTTP e Python.

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/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"
}

No exemplo anterior, substitua os valores da seguinte maneira:

KMS_PROJECT_ID: o ID do projeto em que a chave foi criada.
LOCATION: a região do keyring.
KEY_RING_NAME: o nome do keyring do Cloud KMS.
KEY_NAME: o nome da chave do Cloud KMS.

Solução de problemas

Esta seção aborda problemas comuns e considerações importantes ao usar a CMEK com a API Análises de conversação.

Mudanças de estado da chave

Se uma versão de chave do Cloud KMS que protege um recurso da API Análises de conversação ficar indisponível, você perderá o acesso aos dados criptografados por essa chave. Se você tentar acessar dados protegidos enquanto a chave estiver indisponível, como ler o contexto de um recurso DataAgent ou acessar o histórico de Conversation, a solicitação vai falhar. O erro retornado depende do motivo pelo qual a chave está indisponível:

Se a versão da chave estiver desativada ou destruída, a operação normalmente 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 normalmente falhará com um erro PERMISSION_DENIED ou NOT_FOUND.

Mesmo quando a chave está indisponí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 Análises de conversação

Quando você usa a CMEK na API Análises de conversação, seus projetos podem consumir cotas de solicitações criptográficas do Cloud KMS. Por exemplo, a leitura de um recurso DataAgent ou o acesso ao histórico de Conversation protegido pela CMEK exige que o Cloud KMS descriptografe 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 de hardware, às vezes chamadas de chaves do Cloud HSM, as operações de criptografia e descriptografia são descontadas das cotas do Cloud HSM no projeto que contém a chave.
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

Saiba como ativar a API Análises de conversação.
Saiba como autenticar e se conectar a uma fonte de dados com a API Análises de conversação.
Saiba como criar um agente de dados usando o SDK do Python.
Saiba como criar um agente de dados usando HTTP e Python.
Saiba mais sobre o Cloud KMS.
Saiba mais sobre as políticas da organização de CMEK.

Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

CMEK para recursos da API Análises de conversação

O que é protegido com a CMEK

Limitações

Antes de começar

Console

gcloud

Proteger recursos com a CMEK

Proteger um recurso DataAgent com a CMEK

SDK do Python

HTTP

Proteger um recurso Conversation com a CMEK

SDK do Python

HTTP

Solução de problemas

Mudanças de estado da chave

Cotas do Cloud KMS e a API Análises de conversação

A seguir

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

Proteger um recurso `DataAgent` com a CMEK

Proteger um recurso `Conversation` com a CMEK