Usar chaves de criptografia gerenciadas pelo cliente (CMEK)

Nesta página, descrevemos como executar tarefas relacionadas às chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) para o Firestore. Para obter mais informações sobre CMEK, em geral, como quando e por que ativar, consulte a documentação do Cloud KMS.

Preparar suas chaves CMEK

Antes de criar um banco de dados do Firestore protegido por CMEKs, você precisa concluir as seguintes etapas:

  1. Crie ou recupere um agente de serviço do Firestore.
  2. Crie uma chave CMEK.
  3. Defina as configurações do IAM para essa chave.

Conclua estas etapas para cada projeto que conterá bancos de dados do Firestore protegidos pela CMEK. Se posteriormente você criar uma nova chave CMEK, será necessário definir as configurações de IAM para essa chave.

Criar um agente de serviço do Firestore

Antes de criar uma chave CMEK, você precisa ter um agente de serviço do Firestore, que é um tipo de conta de serviço gerenciado pelo Google que o Firestore usa para acessar a chave.

Execute o comando services Identity create para criar o agente de serviço que o Firestore usa para acessar a chave CMEK em seu nome. Esse comando cria a conta de serviço, se ela ainda não existir, e depois a exibe.

gcloud beta services identity create \
    --service=firestore.googleapis.com \
    --project FIRESTORE_PROJECT

Substitua FIRESTORE_PROJECT pelo projeto que você planeja usar para os bancos de dados do Firestore.

O comando exibe o código do agente de serviço, que está formatado como um endereço de e-mail. Registre a string de e-mail de saída, porque você a usará em uma etapa posterior.

Service identity created:
service-xxx@gcp-sa-firestore.iam.gserviceaccount.com

Crie uma chave

É possível usar uma chave criada diretamente no Cloud KMS ou uma chave gerenciada externamente que você disponibiliza com o Cloud External Key Manager.

O local da chave do Cloud KMS precisa ser o mesmo local do banco de dados do Firestore com que ela será usada.

  • Para locais de banco de dados regionais, use o mesmo nome de local para keyring, chave e banco de dados, porque os nomes dos locais têm um mapeamento de um para um.

    Por exemplo, se você quiser criar um banco de dados protegido por CMEK em us-west1, crie um keyring e uma chave em us-west1.

  • Para locais de bancos de dados multirregionais, use o nome do local multirregional do KMS:

    • Use o local multirregional us do Cloud KMS para o local multirregional nam5 do Firestore.
    • Use o local multirregional europe do Cloud KMS para o local multirregional eur3 do Firestore.

No projeto do Google Cloud em que você quer gerenciar suas chaves, faça o seguinte:

  1. Ative a API Cloud KMS.

  2. Crie um keyring e uma chave usando uma das seguintes opções:

Como definir as configurações do IAM da chave

Console

Para conceder um papel do Cloud KMS ao seu agente de serviço, faça o seguinte. Também é possível conceder permissão no nível da chave ou do keyring para a granularidade mais baixa.

  1. No console do Google Cloud, abra a página IAM.

    Acessar a página IAM

  2. Clique em Adicionar.

  3. Insira o ID formatado por e-mail do seu agente de serviço do Firestore.

  4. Selecione o papel Criptografador/Descriptografador de CryptoKey do Cloud KMS.

  5. Clique em Salvar.

gcloud

  1. Conceda o papel cloudkms.cryptoKeyEncrypterDecrypter ao seu agente de serviço:

    gcloud kms keys add-iam-policy-binding KMS_KEY \
    --keyring KMS_KEYRING\
    --location KMS_LOCATION \
    --member serviceAccount:SERVICE_AGENT_EMAIL \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
    --project KMS_PROJECT

    Preencha o seguinte:

    • KMS_KEY: nome atribuído à chave;
    • KMS_KEYRING: keyring do KMS que contém a chave;
    • KMS_LOCATION : região que contém o keyring;
    • SERVICE_AGENT_EMAIL: identificador formatado pelo e-mail do agente de serviço a que você está concedendo acesso;
    • KMS_PROJECT: projeto que contém a chave.

    O terminal mostrará uma resposta semelhante a esta:

    Updated IAM policy for key KMS_KEY.
bindings:
- members:
  - serviceAccount:
    service-{project-number}@gcp-sa-firestore.iam.gserviceaccount.com
role: roles/cloudkms.cryptoKeyEncrypterDecrypter

Criar um banco de dados ativado para CMEK

Depois que as chaves CMEK forem criadas e configuradas, será possível criar um banco de dados protegido pela CMEK. O banco de dados do Firestore protegido pela criptografia padrão do Google não pode ser convertido para usar CMEK. Só é possível escolher um tipo de criptografia e uma chave no momento da criação.

gcloud 

gcloud alpha firestore databases create --location=FIRESTORE_DATABASE_LOCATION \
      --database=DATABASE_ID \
      --kms-key-name=KMS_KEY_NAME \
      --project=FIRESTORE_PROJECT

Preencha o seguinte:

  • FIRESTORE_DATABASE_LOCATION: o local do Firestore para o banco de dados
  • DATABASE_ID: um ID para o banco de dados.

  • KMS_KEY_NAME: o nome que você atribuiu à chave. Use o nome completo do recurso para a chave no formato:

    projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID

  • FIRESTORE_PROJECT: o projeto a ser usado no banco de dados do Firestore

API REST

Solicitação HTTP:

POST https://firestore.googleapis.com/v1/projects/{FIRESOTRE_PROJECT}/databases

No corpo da solicitação, configure a CMEK no campo cmek_config.kms_key_name.

Defina como o ID completo do recurso de uma chave do Cloud KMS. É permitida apenas uma chave no mesmo local desse banco de dados.

Esse valor precisa ser o ID de recurso da chave do Cloud KMS no formato projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}.

Veja mais detalhes sobre outros campos na página database create.

Exemplo de solicitação:

curl -X POST 'https://firestore.googleapis.com/v1/projects/FIRESTORE_PROJECT/databases?databaseId={DATABASE_ID}' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-d '{
  "type":"FIRESTORE_NATIVE",
  "locationId":"{FIRESTORE_DATABASE_LOCATION}",
  "cmekConfig": {
    "kmsKeyName":"projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID"
  }
}'

Terraform

Para criar um banco de dados ativado para CMEK, use o recurso google_firestore_database. Para mais informações e exemplos, consulte google_firestore_database.

resource "google_firestore_database" "database" {
  project     = "FIRESTORE_PROJECT"
  name        = "DATABASE_ID"
  location_id = "FIRESTORE_DATABASE_LOCATION"
  type        = "DATABASE_TYPE"

  cmek_config {
    kms_key_name = "KMS_KEY_NAME"
  }

}

Preencha o seguinte:

  • FIRESTORE_PROJECT: o projeto a ser usado no banco de dados do Firestore
  • DATABASE_ID: um ID para o banco de dados.
  • FIRESTORE_DATABASE_LOCATION: o local do Firestore para o banco de dados
  • DATABASE_TYPE: FIRESTORE_NATIVE para o modo nativo ou DATASTORE_MODE para o modo Datastore.

  • KMS_KEY_NAME: o nome que você atribuiu à chave. Use o nome completo do recurso para a chave no formato:

    projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID

Acessar um banco de dados protegido por CMEKs

Todas as operações de leitura, gravação e consulta enviadas para um banco de dados protegido por CMEKs precisam funcionar da mesma maneira que um banco de dados criptografado padrão do Google. Por exemplo, não é preciso fornecer uma chave para cada solicitação.

Ver a chave em uso

gcloud

É possível usar o comando databases describe da CLI gcloud para confirmar a configuração da CMEK do banco de dados:

gcloud firestore databases describe --database=DATABASE_ID --project=FIRESTORE_PROJECT

Você verá informações da CMEK no campo cmekConfig na resposta semelhante a esta:

cmekConfig:
    activeKeyVersion:
    - projects/PROJECT_ID/locations/us/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME/cryptoKeyVersions/1
    kmsKeyName: projects/PROJECT_ID/locations/us/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME
  locationId: nam5
  name: projects/PROJECT_ID/databases/DATABASE_ID

A resposta inclui as seguintes informações:

  • kmsKeyName: o nome completo do recurso da chave usada para criptografar o banco de dados protegido pela CMEK.
  • activeKeyVersion: uma lista de todas as versões de chave atualmente em uso pelo banco de dados protegido pela CMEK. Durante a rotação de chaves, pode haver várias versões de chave ativas.

API REST

Solicitação HTTP:

GET https://firestore.googleapis.com/v1/{name=projects/FIRESTORE_PROJECT/databases/DATABASE_ID}

No corpo da solicitação, configure a CMEK no campo cmek_config.kms_key_name. Defina como o ID completo do recurso de uma chave do Cloud KMS. É permitida apenas uma chave no mesmo local desse banco de dados.

Esse valor precisa ser o ID de recurso da chave do Cloud KMS no formato projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}.

Veja mais detalhes sobre outros campos na página database create.

Exemplo de solicitação e resposta:

curl 'https://firestore.googleapis.com/v1/projects/FIRESTORE_PROJECT/databases/{DATABASE_ID}' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json"

—----------------------------------------- Response —--------------------------------------------
{
  "name": "projects/FIRESTORE_PROJECT/databases/{DATABASE_ID}",
  "locationId": "{FIRESTORE_DATABASE_LOCATION}",
  "type": "FIRESTORE_NATIVE",
  "cmekConfig": {
    "kmsKeyName": "projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}",
    "activeKeyVersion": [
      "projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}/cryptoKeyVersions/1"
    ]
  },
  ……
}

Desativar uma chave

Para desativar uma chave associada a um banco de dados, siga estas etapas:

  1. Veja as versões de chave em uso para um banco de dados
  2. Desativar essas versões de chave
  3. Aguarde a alteração entrar em vigor e verifique se os dados não estão mais acessíveis. Normalmente, as alterações entram em vigor em alguns minutos, mas podem levar até três horas.

Quando uma chave usada por um banco de dados é desativada, você recebe uma exceção FAILED_PRECONDITION com mais detalhes na mensagem de erro. Por exemplo:

{
  "error": {
    "code": 400,
    "message": "The customer-managed encryption key required by the requested resource is not accessible. Error reason:  generic::permission_denied: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource 'projects/FIRESTORE_PROJECT/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}' (or it may not exist).",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "The customer-managed encryption key required by the requested resource is not accessible. Error reason:  generic::permission_denied: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource 'projects/FIRESTORE_PROJECT/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}' (or it may not exist)"
      }
    ]
  }
}

Ativar uma chave

Para reativar uma chave associada a um banco de dados, siga estas etapas:

  1. Veja as versões de chave em uso para um banco de dados
  2. Ativar essas versões de chave
  3. Aguarde a alteração entrar em vigor e verifique se os dados não estão mais acessíveis. Normalmente, as alterações entram em vigor em alguns minutos, mas podem levar até três horas.

Visualizar registros de auditoria para chave do Cloud KMS

Antes de ativar os registros de auditoria de acesso a dados do Cloud KMS, familiarize-se com os registros de auditoria do Cloud.

Os registros de auditoria de acesso a dados do Cloud KMS mostram quando o Firestore ou qualquer outro produto configurado para usar sua chave CMEK faz chamadas de criptografia/descriptografia para o Cloud KMS. O Firestore não emite uma chamada de criptografia/descriptografia em todas as solicitações de dados, mas mantém um aplicativo de pesquisa que verifica a chave periodicamente. Os resultados da pesquisa aparecem nos registros de auditoria.

É possível configurar e interagir com os registros de auditoria no Console do Google Cloud:

  1. Verifique se a geração de registros está ativada para a API Cloud KMS no seu projeto.

  2. Acesse o Cloud Logging no Console do Google Cloud.

    Acessar o Cloud Logging

  3. Limite as entradas de registro na chave do Cloud KMS adicionando as seguintes linhas ao criador de consultas:

    resource.type="cloudkms_cryptokey"
resource.labels.key_ring_id = KMS_KEYRING
resource.labels.crypto_key_id = KMS_KEY
resource.labels.location=KMS_LOCATION

    Preencha o seguinte:

    • KMS_KEY: nome da chave CMEK;
    • KMS_KEYRING: keyring do KMS que contém a chave;
    • KMS_LOCATION: a localização da chave e do keyring.

    O registro mostra algumas entradas a cada cinco minutos por banco de dados. As entradas de registro serão semelhantes a estes exemplos:

    Info 2021-03-20 08:02:24.869 EDT Cloudkms.googleapis.com Decrypt projects/cloud-kms-project/locations/us-central1/keyRings/firestore-keys/cryptoKeys/my-cmek-key service-123456789123@gcp-sa-firestore.iam.gserviceaccount.com
audit_log, method: "Decrypt", principal_email: "service-1234567891011@gcp-sa-firestore.iam.gserviceaccount.com"

Info 2021-03-20 08:02:24.913 EDT Cloudkms.googleapis.com Encrypt projects/cloud-kms-project/locations/us-central1/keyRings/firestore-keys/cryptoKeys/my-cmek-key service-123456789123@gcp-sa-firestore.iam.gserviceaccount.com
audit_log, method: "Encrypt", principal_email: "service-123456789123@gcp-sa-firestore.iam.gserviceaccount.com"

Consulte Noções básicas sobre registros de auditoria para detalhes sobre como interpretar registros de auditoria.

Configurar uma política da organização de CMEK

Para especificar requisitos de conformidade com criptografia para bancos de dados do Firestore na organização, use uma restrição de política da organização de CMEK.

Exigir proteção de CMEK

Configure constraints/gcp.restrictNonCmekServices para exigir CMEK para a criação do banco de dados do Firestore. Defina a restrição como deny e adicione firestore.googleapis.com à lista de bloqueio, por exemplo:

 gcloud resource-manager org-policies deny gcp.restrictNonCmekServices  is:firestore.googleapis.com --project=FIRESTORE_PROJECT

Substitua FIRESTORE_PROJECT pelo projeto a ser restrito.

Para saber mais sobre a configuração de políticas da organização, consulte Como criar e editar políticas.

Depois que a política entrar em vigor, você receberá uma exceção FAILED_PRECONDITION e uma mensagem de erro se tentar criar um banco de dados que não seja CMEK no projeto afetado. Por exemplo, uma exceção é semelhante a esta:

{
  "error": {
    "code": 400,
    "message": "Constraint 'constraints/gcp.restrictNonCmekServices' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'firestore.googleapis.com'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.PreconditionFailure",
        "violations": [
          {
            "type": "constraints/gcp.restrictNonCmekServices",
            "subject": "orgpolicy:projects/FIRESTORE_PROJECT",
            "description": "Constraint 'constraints/gcp.restrictNonCmekServices' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'firestore.googleapis.com'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information."
          }
        ]

Limitar o uso de chaves para a CMEK

Para limitar quais chaves do Cloud KMS são usadas para proteção de CMEK, configure a restrição constraints/gcp.restrictCmekCryptoKeyProjects.

Como uma restrição de lista, os valores aceitos são indicadores de hierarquia de recursos (por exemplo, projects/PROJECT_ID, under:folders/FOLDER_ID e under:organizations/ORGANIZATION_ID). Use essa restrição configurando uma lista de indicadores de hierarquia de recursos e definindo a restrição como Permitir. Essa configuração restringe os serviços com suporte para que as chaves CMEK possam ser escolhidas apenas nos projetos, pastas e organizações listados. As solicitações para criar recursos protegidos por CMEK em serviços configurados não são bem-sucedidas sem uma chave do Firestore de um dos recursos permitidos.

O exemplo a seguir permite apenas chaves do ALLOWED_KEY_PROJECT_ID para bancos de dados protegidos pela CMEK no projeto especificado:

gcloud resource-manager org-policies allow gcp.restrictCmekCryptoKeyProjects \
under:projects/ALLOWED_KEY_PROJECT_ID \
--project=FIRESTORE_PROJECT

Depois que a política entrar em vigor, se você violar a restrição, receberá uma exceção FAILED_PRECONDITION e uma mensagem de erro. Uma exceção é semelhante a esta:

{
  "error": {
    "code": 400,
    "message": "Constraint 'constraints/gcp.restrictCmekCryptoKeyProjects' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'projects/{NOT_ALLOWED_KEY_PROJECT}'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.PreconditionFailure",
        "violations": [
          {
            "type": "constraints/gcp.restrictCmekCryptoKeyProjects",
            "subject": "orgpolicy:projects/FIRESTORE_PROJECT",
            "description": "Constraint 'constraints/gcp.restrictCmekCryptoKeyProjects' violated for 'projects/FIRESTORE_PROJECT' attempting to perform the operation 'google.firestore.admin.v1.FirestoreAdmin.CreateDatabase' with violated value 'projects/{NOT_ALLOWED_KEY_PROJECT}'. See https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints for more information."
          }
        ]
      }
    ]
  }
}

A seguir