Usar claves de encriptación administradas por el cliente (CMEK)

Usar claves de encriptación administradas por el cliente (CMEK)

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para obtener información sobre el acceso a esta versión, consulta la página de solicitud de acceso.

En esta página, se describe cómo realizar tareas relacionadas con las claves de encriptación administradas por el cliente (CMEK) para Firestore. Para obtener más información sobre las CMEK en general, incluso cuándo y por qué habilitarlas, consulta la documentación de Cloud KMS.

Prepara tus claves CMEK

Antes de crear una base de datos de Firestore protegida con CMEK, debes completar los siguientes pasos:

1. Crear (o recuperar) un agente de servicio de Firestore.
2. Crea una clave CMEK.
3. Establece la configuración de IAM para esa clave.

Completa estos pasos para cada proyecto que contenga bases de datos de Firestore protegidas por CMEK. Si más adelante creas una CMEK nueva, deberás configurarla por ti.

Nota: Los comandos gcloud de esta página muestran marcadores de posición para dos proyectos de Google Cloud: el proyecto que contiene las bases de datos de Firestore, FIRESTORE_PROJECT, y el que contiene las claves CMEK, KMS_PROJECT. Sin embargo, puedes usar el mismo proyecto para tus bases de datos de Firestore y claves CMEK.

Crea un agente de servicio de Firestore

Antes de crear una clave CMEK, debes tener un agente de servicio de Firestore, que es un tipo de cuenta de servicio administrada por Google que Firestore usa para acceder a la clave.

Ejecuta el comando services Identity create para crear el agente de servicio que Firestore usa con el objetivo de acceder a la clave CMEK en tu nombre. Este comando crea la cuenta de servicio si aún no existe y, luego, la muestra.

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

Reemplaza FIRESTORE_PROJECT por el proyecto que planeas usar para las bases de datos de Firestore.

El comando muestra el ID del agente de servicio, que tiene el formato de una dirección de correo electrónico. Registra la string de correo electrónico de salida, ya que la usarás en un paso posterior.

Service identity created:
[e-mail]

Crear una clave

Puedes usar una clave creada directamente en Cloud KMS o una clave administrada de forma externa que pongas a disposición con Cloud External Key Manager.

La ubicación de la clave de Cloud KMS debe ser la misma que la ubicación de la base de datos de Firestore con la que se usará.

• En el caso de las ubicaciones de bases de datos regionales, usa el mismo nombre de ubicación para el llavero de claves, la clave y la base de datos porque los nombres de ubicación tienen una asignación uno a uno.

  Por ejemplo, si deseas crear una base de datos protegida con CMEK en us-west1, crea un llavero de claves y una clave en us-west1.

• Para las ubicaciones de bases de datos multirregionales, usa el nombre de la ubicación multirregional de KMS:

  • Usa la ubicación multirregional us de Cloud KMS para la ubicación multirregional nam5 de Firestore.
  • Usa la ubicación multirregional europe de Cloud KMS para la ubicación multirregional eur3 de Firestore.

En el proyecto de Google Cloud en el que deseas administrar tus claves, completa lo siguiente:

1. Habilita la API de Cloud KMS.

2. Crea un llavero de claves y una clave mediante una de las siguientes opciones:

   • Crea el llavero de claves y la clave directamente en Cloud KMS.
   • Usa una clave administrada de forma externa. Crea la clave externa y, luego, crea una clave de Cloud EKM para que la clave esté disponible a través de Cloud KMS.

Establece la configuración de IAM para la clave

Console

Para otorgar una función de Cloud KMS a tu agente de servicio, haz lo siguiente. También puedes otorgar permiso a nivel de la clave o del llavero de claves si deseas reducir el nivel de detalle.

1. En la consola de Google Cloud, ve a la página IAM.

   Ir a la página IAM

2. Haz clic en Agregar.

3. Ingresa el ID con formato de correo electrónico para tu agente de servicio de Firestore.

4. Selecciona la función Encriptador/Desencriptador de CryptoKey de Cloud KMS.

5. Haz clic en Guardar.

gcloud

1. Otorga la función cloudkms.cryptoKeyEncrypterDecrypter al agente de servicio:

   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
   

   Proporcione lo siguiente:

   • KMS_KEY: es el nombre que le asignaste a la clave
   • KMS_KEYRING: es el llavero de claves de KMS que contiene la clave
   • KMS_LOCATION: la región que contiene el llavero de claves
   • SERVICE_AGENT_EMAIL: es el identificador con formato de correo electrónico para el agente de servicio al que le otorgas acceso
   • KMS_PROJECT: el proyecto que contiene la clave

   La terminal debería mostrar una respuesta similar a la siguiente:

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

Crea una base de datos habilitada con CMEK

Después de crear y configurar tus claves CMEK, puedes crear una base de datos protegida con CMEK. La base de datos existente de Firestore que está protegida por la encriptación predeterminada de Google no se puede convertir para usar CMEK. Solo puedes elegir un tipo y una clave de encriptación en el momento de la creación.

gcloud

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

Proporcione lo siguiente:

• FIRESTORE_DATABASE_LOCATION: Es la ubicación de Firestore para la base de datos.
• DATABASE_ID: Un ID para la base de datos

• KMS_KEY_NAME: Es el nombre que le asignaste a la clave. Usa el nombre completo del recurso para la clave en el siguiente formato:

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

• FIRESTORE_PROJECT: Es el proyecto que se usará para la base de datos de Firestore.

API de REST

Solicitud HTTP:

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

En el cuerpo de la solicitud, configura CMEK en el campo cmek_config.kms_key_name.

Establece el ID de recurso completo de una clave de Cloud KMS. Solo se permite una clave en la misma ubicación que esta base de datos.

Este valor debe ser el ID de recurso de la clave de Cloud KMS en el formato projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}.

Para obtener más detalles sobre otros campos, consulta la página de database create.

Solicitud de ejemplo:

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 crear una base de datos habilitada para CMEK, usa el recurso google_firestore_database. Para obtener más información y ejemplos, consulta 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"
  }

}

Proporcione lo siguiente:

• FIRESTORE_PROJECT: Es el proyecto que se usará para la base de datos de Firestore.
• DATABASE_ID: Un ID para la base de datos
• FIRESTORE_DATABASE_LOCATION: Es la ubicación de Firestore para la base de datos.
• DATABASE_TYPE: Es FIRESTORE_NATIVE para el modo nativo o DATASTORE_MODE para el modo Datastore.

• KMS_KEY_NAME: Es el nombre que le asignaste a la clave. Usa el nombre completo del recurso para la clave en el siguiente formato:

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

Accede a una base de datos protegida con CMEK

Todas las operaciones de lectura, escritura y consulta que se envían a una base de datos protegida con CMEK deben funcionar de la misma manera que con una base de datos encriptada predeterminada de Google. Por ejemplo, no necesitas proporcionar una clave para cada solicitud.

Visualiza la clave en uso

gcloud

Puedes usar el comando databases describe de gcloud CLI para confirmar la configuración de CMEK de la base de datos:

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

Deberías ver información de CMEK en el campo cmekConfig en la respuesta similar a la siguiente:

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

La respuesta incluye la siguiente información:

• kmsKeyName: Es el nombre completo del recurso de la clave que se usa para encriptar la base de datos protegida con CMEK.
• activeKeyVersion: Es una lista de todas las versiones de claves que usa la base de datos protegida con CMEK en la actualidad. Durante la rotación de claves, puede haber varias versiones de claves activas.

API de REST

Solicitud HTTP:

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

En el cuerpo de la solicitud, configura CMEK en el campo cmek_config.kms_key_name. Establece el ID de recurso completo de una clave de Cloud KMS. Solo se permite una clave en la misma ubicación que esta base de datos.

Este valor debe ser el ID de recurso de la clave de Cloud KMS en el formato projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}.

Para obtener más detalles sobre otros campos, consulta la página de database create.

Ejemplo de solicitud y respuesta:

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"
    ]
  },
  ……
}

Inhabilita una clave

Para inhabilitar una clave asociada con una base de datos, completa lo siguiente:

1. Consulta las versiones de claves que se usan en una base de datos
2. Inhabilita esas versiones de claves
3. Espera a que el cambio surta efecto y verifica si ya no se puede acceder a los datos. Los cambios suelen aplicarse en minutos, pero pueden tardar hasta 3 horas.

Cuando se inhabilita una clave que usa una base de datos, debes esperar recibir una excepción FAILED_PRECONDITION con detalles adicionales en el mensaje de error, por ejemplo:

{
  "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)"
      }
    ]
  }
}

Habilita una clave

Para volver a habilitar una clave asociada con una base de datos, completa los siguientes pasos:

1. Consulta las versiones de claves que se usan en una base de datos
2. Habilita esas versiones de claves
3. Espera a que el cambio surta efecto y verifica si ya no se puede acceder a los datos. Los cambios suelen aplicarse en minutos, pero pueden tardar hasta 3 horas.

Visualiza los registros de auditoría de una clave de Cloud KMS

Antes de habilitar los registros de auditoría de acceso a los datos de Cloud KMS, debes estar familiarizado con los registros de auditoría de Cloud.

Los registros de auditoría de acceso a los datos de Cloud KMS muestran cuándo Firestore o cualquier otro producto configurado para usar tu clave CMEK realiza llamadas de encriptación o desencriptación a Cloud KMS. Firestore no emite una llamada de encriptación/desencriptación en cada solicitud de datos, sino que mantiene una aplicación de sondeo que verifica la clave de forma periódica. Los resultados del sondeo aparecen en los registros de auditoría.

Puedes configurar los registros de auditoría y también interactuar con ellos en la consola de Google Cloud:

1. Asegúrate de que el registro esté habilitado para la API de Cloud KMS en tu proyecto.

2. Ve a Cloud Logging en la consola de Google Cloud.

   Ir a Cloud Logging

3. Agrega las siguientes líneas al compilador de consultas para limitar las entradas de registro a tu clave de Cloud KMS:

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

   Proporcione lo siguiente:

   • KMS_KEY: es el nombre de la clave CMEK
   • KMS_KEYRING: es el llavero de claves de KMS que contiene la clave
   • KMS_LOCATION: Es la ubicación de la clave y el llavero de claves.

   El registro muestra un par de entradas de registro cada cinco minutos por base de datos. Las entradas de registro son similares a estos ejemplos:

   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 [e-mail]
   audit_log, method: "Decrypt", principal_email: "[e-mail]"
   
   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 [e-mail]
   audit_log, method: "Encrypt", principal_email: "[e-mail]"
   

Consulta Comprende los registros de auditoría para obtener detalles acerca de cómo interpretar los registros de auditoría.

Configura una política de la organización de CMEK

Si quieres especificar los requisitos de cumplimiento de encriptación para las bases de datos de Firestore en tu organización, usa una restricción de la política de la organización de CMEK.

Exigir protección con CMEK

Configura constraints/gcp.restrictNonCmekServices de modo que requiera CMEK para la creación de la base de datos en Firestore. Establece la restricción en deny y agrega firestore.googleapis.com a la lista de denegación, por ejemplo:

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

Reemplaza FIRESTORE_PROJECT por el proyecto que deseas restringir.

Para obtener más información sobre cómo configurar las políticas de la organización, consulta Crea y edita políticas.

Después de que la política entre en vigencia, recibirás un mensaje de error y una excepción FAILED_PRECONDITION si intentas crear una base de datos que no sea de CMEK en el proyecto afectado. Por ejemplo, esta es una excepción:

{
  "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."
          }
        ]

Limita el uso de claves para CMEK

Si deseas limitar las claves de Cloud KMS que se usan para la protección con CMEK, configura la restricción constraints/gcp.restrictCmekCryptoKeyProjects.

Como restricción de lista, los valores aceptados son indicadores de jerarquía de recursos (por ejemplo, projects/PROJECT_ID, under:folders/FOLDER_ID y under:organizations/ORGANIZATION_ID). Usa esta restricción configurando una lista de indicadores de jerarquía de recursos y estableciendo la restricción en Permitir. Esta configuración restringe los servicios compatibles para que las claves CMEK solo se puedan elegir entre los proyectos, las carpetas y las organizaciones que se enumeran. Las solicitudes para crear recursos protegidos por CMEK en los servicios configurados no se realizan de forma correcta sin una clave de Firestore de uno de los recursos permitidos.

En el siguiente ejemplo, solo se permiten claves de ALLOWED_KEY_PROJECT_ID para las bases de datos protegidas por CMEK en el proyecto especificado:

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

Después de que la política entre en vigencia, recibirás una excepción FAILED_PRECONDITION y un mensaje de error si infringes la restricción. Una excepción se ve de la siguiente manera:

{
  "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."
          }
        ]
      }
    ]
  }
}

¿Qué sigue?

• Lee la descripción general de Firestore y CMEK