Chaves de criptografia gerenciadas pelo cliente

Por padrão, a Pesquisa do agente criptografa o conteúdo do cliente em repouso. A Pesquisa do agente 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 a Pesquisa do agente. 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. Ao usar o Cloud KMS, é possível também monitorar o uso de chaves, ver registros de auditoria e controlar ciclos de vida de chaves. Em vez de o Google ser proprietário e responsável pelo gerenciamento das 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 da Pesquisa do agente é semelhante à criptografia padrão do Google. Para saber mais sobre suas opções de criptografia, consulte Chaves de criptografia gerenciadas pelo cliente (CMEK).

Quando uma chave CMEK é registrada, a Pesquisa do agente chama o Cloud KMS periodicamente para manter uma instância logicamente isolada dos seus dados. Isso acontece mesmo que a configuração da CMEK não seja definida como padrão e não haja apps ou conectores de dados usando ela. O uso vem da configuração e execução da instância, não do volume de dados ou do número de usuários que acessam ela. Consulte os preços do Cloud Key Management Service.

Limitações do Cloud KMS na Pesquisa do agente

As seguintes limitações se aplicam às chaves CMEK (Cloud KMS) na Pesquisa do agente:

  • As chaves já aplicadas a um app ou conector de dados não podem ser alteradas, mas as versões delas podem ser alternadas.
  • É preciso usar apps e repositórios de dados multirregionais dos EUA ou da UE (não globais). Para mais informações sobre multirregiões e residência de dados, incluindo limites associados ao uso de locais não globais, consulte locais.

  • Se você precisar registrar mais de uma chave para um projeto, entre em contato com a equipe da sua conta do Google para solicitar um aumento de cota para configurações de CMEK, justificando por que você precisa de mais de uma chave.

    As seguintes limitações se aplicam ao EKM ou HSM com CMEK:

    • Sua cota de EKM e HSM para chamadas de criptografia e descriptografia precisa ter pelo menos 1.000 QPM de headroom. Para saber como verificar suas cotas, consulte Verificar suas cotas do Cloud KMS.

    • Se você estiver usando o EKM, a chave precisa estar acessível por mais de 90% de qualquer período de mais de 30 segundos. Se a chave não estiver acessível por esse período, isso poderá afetar negativamente a indexação e a atualização da pesquisa.

    • Se houver problemas de faturamento, problemas persistentes de falta de cota ou problemas persistentes de inacessibilidade por mais de 12 horas, o serviço vai desativar automaticamente o CmekConfig associado à chave do EKM ou HSM.

  • Os apps ou conectores de dados criados antes do registro de uma chave no projeto não podem ser protegidos por ela.
  • Para apps com vários conectores de dados, se um deles usar uma configuração de CMEK, todos os outros também precisarão usar a mesma configuração.

Sobre chaves de região única para conectores de terceiros

Se você usa conectores de terceiros e quer usar suas próprias chaves para proteger os dados conectados, crie três chaves complementares de região única além da chave multirregional. Os comandos para criar chaves são fornecidos no procedimento a seguir, Registrar sua chave do Cloud KMS.

As chaves únicas precisam ser criadas para as seguintes regiões:

Multirregional Regiões únicas
eu europe-west1 europe-west4 europe-north1
us us-east1 us-central1 us-west1

Antes de começar

Verifique se você atende aos seguintes pré-requisitos:

  • Crie uma chave simétrica multirregional do Cloud KMS. Consulte Criar um keyring e Criar uma chave na documentação do Cloud KMS.

    • Defina o período de rotação como Nunca (rotação manual).

    • Em Local, selecione Multirregional e escolha europe ou us no menu suspenso.

  • O papel do IAM de criptografia/descriptografia de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave foi concedido ao agente de serviço do Discovery Engine. A conta do agente de serviço tem um endereço de e-mail com o seguinte formato: service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com. Para instruções gerais sobre como adicionar um papel a um agente de serviço, consulte Conceder ou revogar um único papel.

  • O papel do IAM de criptografador/descriptografador de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave foi concedido ao agente de serviço do Cloud Storage. Se essa função não for concedida, a importação de dados para apps e conectores de dados protegidos por CMEK vai falhar porque o Discovery Engine não consegue criar o bucket e o diretório temporários protegidos por CMEK necessários para a importação.

  • Não crie apps nem conectores de dados que você quer gerenciar com sua chave até concluir as instruções de registro de chave nesta página.

Registrar sua chave do Cloud KMS

Para criptografar dados usando a CMEK, registre sua chave multirregional. Opcional: se os dados precisarem de chaves de região única, por exemplo, ao usar conectores de terceiros, também será necessário registrar as chaves de região única.

Antes de começar

Certifique-se disto:

  • A região ainda não está protegida por uma chave. O procedimento abaixo falha se uma chave já estiver registrada para a região usando o comando REST. Para determinar se há uma chave ativa na Pesquisa do agente para um local, consulte Ver chaves do Cloud KMS.

Procedimento

REST

Para registrar sua própria chave para a Pesquisa do agente, siga estas etapas:

  1. Chame o método UpdateCmekConfig com a chave que você quer registrar.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"kmsKey":"projects/KMS_PROJECT_ID/locations/KMS_LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"}' \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"

    Substitua:

    • KMS_PROJECT_ID: o ID do projeto que contém a chave. O número do projeto não vai funcionar.
    • KMS_LOCATION: a multirregião da sua chave: us ou europe.
    • KEY_RING: o nome do keyring que contém a chave.
    • KEY_NAME: o nome da chave;
    • PROJECT_ID: o ID do projeto que contém o conector de app ou de dados.
    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • CMEK_CONFIG_ID: defina um ID exclusivo para o recurso CmekConfig, por exemplo, default_cmek_config.

    • SET_DEFAULT: defina como true para usar a chave como padrão para apps e conectores de dados subsequentes criados na multirregião.

  2. Opcional: registre o valor name retornado pelo método e siga as instruções em Receber detalhes sobre uma operação de longa duração para saber quando a operação será concluída.

    Normalmente, leva alguns minutos para registrar uma chave.

    Depois que a operação for concluída, os novos apps e conectores de dados nessa multirregião serão protegidos pela chave. Para informações gerais sobre a criação de apps, consulte Sobre apps e repositórios de dados.

  3. Crie o app. Para instruções, consulte Criar um app e Sobre apps e repositórios de dados.

Console

Procedimento

Para registrar sua própria chave para a Pesquisa por agente, siga estas etapas:

  1. No console Google Cloud , acesse a página Aplicativos de IA.

    Aplicativos de IA

  2. Clique em Configurações e selecione a guia CMEK.

  3. Clique em Adicionar chave para o local us ou eu.

    Clique em "Adicionar chave" para um local.
    Clique em "Adicionar chave".

    1. Clique no menu suspenso Selecionar uma chave do Cloud KMS e escolha a chave.

      • Se a chave estiver em outro projeto, clique em Alternar projeto, clique no nome do projeto, digite o nome da chave que você criou e selecione a chave.

      • Se você souber o nome de recurso da chave, clique em Inserir manualmente, cole o nome de recurso da chave e clique em Salvar.

    2. Clique em OK > Salvar.

  4. Crie o app. Para instruções, consulte Sobre apps e repositórios de dados.

Isso registra sua chave, criando um CmekResource chamado default_cmek_config.

Pode levar várias horas para que os dados ingeridos apareçam nos resultados da pesquisa.

Ver chaves do Cloud KMS

Para conferir uma chave registrada para a Pesquisa do agente, faça o seguinte:

  • Se você tiver o nome do recurso CmekConfig, chame o método GetCmekConfig:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

    Substitua:

    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém os dados.
    • CMEK_CONFIG_ID: o ID do recurso CmekConfig. Se você registrou a chave usando o console, o ID é default_cmek_config.

    Exemplo de chamada e resposta do curl: 

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"

    
{
  "name":
  "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
  "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
  "state": "ACTIVE"
  "isDefault": true
}

  • Se você não tiver o nome do recurso CmekConfig, chame o método ListCmekConfigs:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"

    Substitua:

    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém os dados.

    Exemplo de chamada e resposta do curl: 

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs"

    
{
  "cmek_configs": [
    {
      "name":
      "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
      "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
      "state": "ACTIVE"
      "isDefault": true
    }
  ]
}

Cancelar o registro da chave do Cloud KMS

Para cancelar o registro da sua chave na Pesquisa no agente, siga estas etapas:

  1. Chame o método DeleteCmekConfig com o nome do recurso CmekConfig que você quer cancelar o registro.

    curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

    Substitua:

    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém o app ou conector de dados.
    • CMEK_CONFIG_ID: o ID do recurso CmekConfig. Se você registrou a chave usando o console, o ID é default_cmek_config.

    Exemplo de chamada e resposta do curl: 

    $ curl -X DELETE
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"
 
{
 "name": "projects/my-ai-app-project-123/locations/us/operations/delete-cmek-config-56789",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.DeleteCmekConfigMetadata"
 }
}

  2. Opcional: registre o valor name retornado pelo método e siga as instruções em Receber detalhes sobre uma operação de longa duração para ver quando a operação será concluída.

    A exclusão de um CmekConfig é uma operação de longa duração que pode levar até alguns dias para ser concluída. Isso acontece porque os recursos criptografados subjacentes são totalmente desprovisionados antes da remoção do CmekConfig.

Verificar se um app ou conector de dados está protegido por uma chave

Os apps e conectores de dados criados depois que a chave é registrada são protegidos por ela. Se você quiser confirmar se um app ou conector de dados específico está protegido pela sua chave, siga estas etapas:

Verificar usando o console Google Cloud

Use o console Google Cloud para verificar se uma configuração padrão de CMEK está definida.

  1. No console Google Cloud , acesse a página Aplicativos de IA.
  2. Clique em Configurações e selecione a guia CMEK.
  3. Verifique se o status da configuração do local aparece como Ativo e mostra sua chave registrada.

Verificar usando a CLI / API

  1. Para verificar um repositório de dados:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID"

    Substitua:

    • LOCATION: a multirregião do seu projeto: us ou eu.
    • PROJECT_ID: o ID do projeto que contém o app ou conector de dados.
    • DATA_STORE_ID: o ID do repositório de dados associado ao seu app ou conector de dados.

    Exemplo de chamada curl: 

    curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"

  2. Para verificar um app:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/ENGINE_ID"

    Substitua:

    • LOCATION: a multirregião do seu projeto: us ou eu.
    • PROJECT_ID: o ID do projeto que contém o app.
    • ENGINE_ID: o ID do app.

    Exemplo de chamada curl: 

    curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/engines/my-app"

  3. Analise a saída do comando: se o campo cmekConfig estiver na saída e o campo kmsKey mostrar a chave registrada, o app ou conector de dados estará protegido por ela.

    Exemplo de resposta para um repositório de dados:

    {
 "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1",
 "displayName": "my-data-store-1",
 "industryVertical": "GENERIC",
 "createTime": "2023-09-05T21:20:21.520552Z",
 "solutionTypes": [
   "SOLUTION_TYPE_SEARCH"
 ],
 "defaultSchemaId": "default_schema",
 "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

    Exemplo de resposta para um app:

    {
  "name": "projects/969795412903/locations/us/collections/default_collection/engines/my-app",
  "displayName": "my-app",
  "dataStoreIds": [
    "my-data-store-1"
  ],
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "searchEngineConfig": {
    "searchTier": "SEARCH_TIER_STANDARD"
  },
  "industryVertical": "GENERIC",
  "appType": "APP_TYPE_INTRANET",
  "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

Outros dados protegidos pela chave do Cloud KMS

Além dos dados nos apps e conectores de dados, suas chaves podem proteger outros tipos de informações principais pertencentes ao app mantidas pela Pesquisa de agentes, como os dados de sessão gerados durante a pesquisa com acompanhamentos. Esse tipo de informação principal é protegido por CMEK se os apps e conectores de dados também forem.

Embora não seja possível executar um comando específico para verificar se as sessões estão protegidas, é possível verificar se o app está protegido. Execute o comando Verificar se um app ou conector de dados está protegido por uma chave para que o app veja a chave no recurso cmekConfig. Assim, você vai saber que os dados da sessão estão protegidos.

Fazer rotação de chaves do Cloud KMS

Ao fazer a rotação de chaves, você cria uma nova versão e a define como a principal. Deixe a versão original da chave ativada por um tempo antes de desativá-la. Isso dá tempo para que todas as operações de longa duração que possam estar usando a chave mais antiga sejam concluídas.

O procedimento a seguir descreve as etapas para alternar chaves de um app de pesquisa do agente ou conector de dados. Para informações gerais sobre rotação de chaves, consulte Rotação de chaves no guia do Cloud KMS.

Importante:não gire as chaves em apps ou conectores de dados associados a recomendações ou a apps que precisam de análises. Além disso, não gire as chaves de região única usadas para conectores de terceiros. Consulte Limitações do Cloud KMS na Pesquisa do agente.

  1. Registre a chave novamente. Para isso, repita a etapa 1 de Registrar sua chave do Cloud KMS.

  2. Consulte as instruções na seção Gerenciar chaves do guia do Cloud KMS para fazer o seguinte:

    1. Crie uma versão de chave, ative e defina como principal.

      Depois que a nova chave é definida como primária, os documentos no app ou conector de dados são recriptografados com a nova chave, e todos os documentos subsequentes adicionados ao app ou conector de dados são criptografados com a nova chave.

    2. Deixe a versão de chave mais antiga ativada.

    3. Depois de uma semana, desative a versão de chave mais antiga e verifique se tudo está funcionando como antes.

    4. Em uma data posterior, quando tiver certeza de que não houve problemas causados pela desativação da versão de chave mais antiga, você poderá destruí-la.

Se uma chave do Cloud KMS for desativada ou revogada

Se uma chave for desativada ou as permissões dela forem revogadas, o app ou conector de dados vai parar de ingerir e disponibilizar dados em até 15 minutos. Você pode reativar a chave em até 30 dias para retomar as operações antes que a configuração da CMEK expire e os dados associados sejam excluídos permanentemente. No entanto, reativar uma chave ou restaurar permissões leva muito tempo. Pode levar até 24 horas para que o app ou conector de dados retome a veiculação de dados.

Portanto, não desative uma chave a menos que seja necessário. Desativar e ativar uma chave em um app ou conector de dados é uma operação demorada. Por exemplo, alternar repetidamente uma chave entre desativada e ativada significa que o app ou conector de dados vai demorar muito para atingir um estado protegido. Desativar e reativar uma chave imediatamente depois pode resultar em dias de inatividade, porque a chave é primeiro desativada do app ou conector de dados e depois reativada.

Solução de problemas: erro "Projetos de chave do KMS não encontrados"

Sintoma:ao tentar criar um app ou conector de dados usando uma chave do KMS, você recebe um erro semelhante a este:

KMS key projects/[...] not found for location: [...] and project number: [...]

Problema:essa mensagem de erro pode ser enganosa. Isso não significa necessariamente que a chave não existe. Em vez disso, pode indicar que a chave do KMS não foi registrada para uso com a Pesquisa do agente no local especificado.

Solução:para resolver esse problema, registre sua chave seguindo as etapas em Registrar sua chave do Cloud KMS. Depois que o registro for concluído, você poderá criar apps ou conectores de dados protegidos por essa chave.