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, como 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 com fontes de dados do Looker. 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 especificada do Cloud KMS criptografa os dados sensíveis em repouso. É possível configurar a CMEK para recursos DataAgent e Conversation de forma independente.

A CMEK só pode ser configurada 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 mudar uma chave do Cloud KMS em um recurso atual.

O que é protegido com a CMEK

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

  • Recursos do DataAgent: 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 estado.

Os seguintes dados 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 Conversational Analytics tem as seguintes limitações:

  • A CMEK precisa ser configurada quando o recurso é criado. Não é possível adicionar ou mudar um recurso existente.
  • A chave do Cloud KMS e o recurso da API Conversational Analytics precisam estar no mesmo local. A região global está indisponível.
  • Para recursos da API Conversational Analytics, a CMEK é compatível na região us-east4.
  • Para recursos da API Conversational Analytics, a CMEK é compatível apenas com fontes de dados do Looker.
  • Só é possível usar uma CMEK por projeto e região para todos os recursos do Conversation nesse projeto e região.

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 Google Cloud ou na Google Cloud CLI.

    Console

    Ative as seguintes APIs no console do Google Cloud para seu 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 anteriores, substitua project_id pelo ID do projeto Google Cloud .

  2. Adicione seu projeto à lista de permissões.

    Seu projeto Google Cloud precisa ser adicionado a uma lista de permissão para usar a CMEK com a Análise de dados do Gemini. Para pedir que seu projeto seja adicionado à lista de permissões, envie o ID do projeto usando o 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.

  3. Crie um keyring e uma chave do Cloud KMS no mesmo local dos recursos da API Conversational Analytics. Para mais informações, consulte Criar uma chave.

  4. Crie os agentes de serviço gerenciados pelo Google, também conhecidos como contas de serviço por produto por projeto (P4SAs), 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 comandos gcloud a seguir 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 Google Cloud .

  5. 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 Gemini Data Analytics use sua chave do Cloud KMS para criptografar e descriptografar os dados da API Conversational Analytics.

    Conceda 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 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.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

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

    • KEY_NAME: o nome da sua 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 projeto 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 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 de 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 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 ver 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 forma:

  • BILLING_PROJECT_ID: o ID do seu projeto.
  • KEY_RING_NAME: o nome do keyring do Cloud KMS.
  • KEY_NAME: o nome da sua chave do Cloud KMS.
  • KMS_PROJECT_ID: o ID do projeto em que a chave foi criada. Se estiver vazio, 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 forma:

  • 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 sua 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 ver 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 forma:

  • BILLING_PROJECT_ID: o ID do seu projeto.
  • KEY_RING_NAME: o nome do keyring do Cloud KMS.
  • KEY_NAME: o nome da sua chave do Cloud KMS.
  • KMS_PROJECT_ID: o ID do projeto em que a chave foi criada. Se estiver vazio, 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 forma:

  • 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 sua 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 Conversational Analytics.

Principais mudanças de estado

Se uma versão de chave do Cloud KMS que protege um recurso da API Conversational Analytics 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, por exemplo, lendo o contexto de um recurso DataAgent ou acessando o histórico do Conversation, a solicitação vai falhar. O erro retornado depende do motivo pelo qual a chave não está disponível:

  • Se a versão da chave estiver desativada ou destruída, a operação geralmente falha 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 vai 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 necessárias do IAM, conforme descrito em Antes de começar.

Cotas do Cloud KMS e da API Conversational Analytics

Ao usar a CMEK na API Conversational Analytics, 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 do Conversation protegido por 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