使用客户管理的加密密钥 (CMEK)

控制台

如需向您的服务代理授予 Cloud KMS 角色，请执行以下操作。如果需要更低的粒度级别，您也可以在密钥级层或密钥环级层授予权限。

1. 在 Google Cloud 控制台中，前往 IAM 页面。

   转到 IAM 页面

2. 点击添加。

3. 输入 Cloud Firestore 服务代理的邮件格式 ID。

4. 选择 Cloud KMS CryptoKey Encrypter/Decrypter 角色。

5. 点击保存。

gcloud

向您的服务账号授予 cloudkms.cryptoKeyEncrypterDecrypter 角色：

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

替换以下内容：

• 将 KMS_KEY 替换为您为密钥分配的名称
• 将 KMS_KEYRING 替换为包含密钥的 KMS 密钥环
• 将 KMS_LOCATION 替换为包含密钥环的区域
• 将 SERVICE_AGENT_EMAIL 替换为您要向其授予访问权限的服务代理的邮件格式标识符
• 将 KMS_PROJECT 替换为包含密钥的项目

终端应显示类似以下内容的响应：

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

控制台

1. 在 Google Cloud 控制台中，转到数据库页面。

   前往“数据库”页面

2. 点击创建数据库。

3. 选择数据库模式。点击继续。

4. 在配置数据库页面上，输入数据库 ID。

5. 选择地理位置。

6. 点击显示加密选项，然后选择 Cloud KMS 密钥。

7. 选择或输入要用于数据库的 CMEK 密钥的资源名称。

8. 密钥列表仅显示当前 Google Cloud 项目和您选择的数据库位置下的密钥。如需使用来自其他 Google Cloud 项目的密钥，请点击切换项目或手动输入密钥。

9. 如果系统提示您向 Cloud Firestore 服务账号授予密钥权限，请点击授予。如需创建 CMEK 数据库，您的 Cloud Firestore 服务账号必须获得 cloudkms.cryptoKeyEncrypterDecrypter 角色。

10. 为移动客户端和 Web 客户端选择安全规则。

11. 点击创建数据库。

创建数据库后，您可以通过查看数据库详细信息来验证该数据库是否为启用了 CMEK 的数据库。

• 如果您的数据库受 CMEK 保护，加密类型字段会显示为客户管理，加密密钥字段会列出相应的 Cloud KMS 以及用于保护此数据库的密钥版本。
• 如果您的数据库未受 CMEK 保护，加密类型字段会显示为由 Google 管理。

gcloud

在使用 Google Cloud CLI 创建启用了 CMEK 的数据库之前，请安装最新版本工具并授权 gcloud CLI。如需了解详情，请参阅安装 gcloud CLI。

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

替换以下内容：

• 将 FIRESTORE_DATABASE_LOCATION 替换为数据库的 Cloud Firestore 位置
• 将 DATABASE_ID 替换为数据库的 ID

• 将 KMS_KEY_NAME 替换为您为密钥分配的名称。使用密钥的完整资源名称，格式如下：

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

• 将 FIRESTORE_PROJECT 替换为要用于 Cloud Firestore 数据库的项目

REST API

HTTP 请求：

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

在请求正文的 cmek_config.kms_key_name 字段中配置 CMEK 密钥。

设置为 Cloud KMS 密钥的完整资源 ID。仅允许与此数据库位于同一位置的密钥。

此值应为 Cloud KMS 密钥资源 ID，格式为 projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}

如需详细了解其他字段，请参阅 database create 页面。

示例请求：

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"
  }
}'

Firebase CLI

如需创建启用了 CMEK 的数据库，请使用 KMS 密钥名称字段。如果您未指定 --kms-key-name 参数，Cloud Firestore 将默认创建未启用 CMEK 的数据库。

firebase firestore:databases:create DATABASE_ID
--___location LOCATION
--kms-key-name projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID
--project FIRESTORE_PROJECT

替换以下内容：

• 将 DATABASE_ID 替换为您的数据库的 ID
• 将 LOCATION 替换为您的数据库的位置
• 将 KMS_PROJECT 替换为包含 CMEK 密钥的项目
• 将 KMS_LOCATION 替换为包含 CMEK 密钥和密钥环的位置
• 将 KMS_KEYRING_ID 替换为您的 CMEK 密钥环的 ID
• 将 FIRESTORE_PROJECT 替换为要用于 Cloud Firestore 数据库的项目

使用 Firebase CLI 确认您的 Cloud Firestore 数据库是否启用了保护：

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

响应消息中会显示以下 CMEK 信息：

• KMS 密钥名称字段提供用于加密 Cloud Firestore CMEK 数据库的完整密钥资源名称。
• 有效密钥版本字段列出了此 CMEK 数据库当前使用的所有密钥版本。在密钥轮替期间，您可以有多个有效的密钥版本。

Terraform

如需创建启用了 CMEK 的数据库，请使用 google_firestore_database 资源。如需更多信息和示例，请参阅 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"
  }

}

替换以下内容：

• 将 FIRESTORE_PROJECT 替换为要用于 Cloud Firestore 数据库的项目
• 将 DATABASE_ID 替换为数据库的 ID
• 将 FIRESTORE_DATABASE_LOCATION 替换为数据库的 Cloud Firestore 位置
• 将 DATABASE_TYPE 替换为 FIRESTORE_NATIVE（针对原生模式）或 DATASTORE_MODE（针对 Datastore 模式）。

• 将 KMS_KEY_NAME 替换为您为密钥分配的名称。使用密钥的完整资源名称，格式如下：

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

gcloud

将受 CMEK 保护的数据库恢复为使用 CMEK 加密

如需恢复到 CMEK 加密，请运行 gcloud firestore databases restore 命令，并使用可选的 encryption-type 和 kms-key-name 标志为恢复的数据库配置加密类型。如果您未指定加密类型，则恢复的数据库将使用与备份相同的加密配置。

  gcloud firestore databases restore
  --encryption-type=customer-managed-encryption
  --kms-key-name=KMS_KEY_NAME

将 KMS_KEY_NAME 替换为您为密钥分配的名称。使用密钥的完整资源名称，格式如下：

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

将受 CMEK 保护的数据库恢复为使用默认加密

如需恢复到 Google 默认加密（未启用 CMEK），请按以下方式设置 encryption-type 标志：

  gcloud firestore databases restore
  --encryption-type=google-default-encryption

将受 CMEK 保护的数据库恢复为与备份相同的加密类型

如需恢复为与备份相同的加密类型，请按以下方式设置 encryption-type 标志：

  gcloud firestore databases restore --encryption-type=use-source-encryption

Firebase CLI

将受 CMEK 保护的数据库恢复为使用 CMEK 加密

如需恢复到 CMEK 加密，请使用可选的 encryption-type 和 kms-key-name 标志。如果您未指定加密类型，则恢复的数据库将使用与备份相同的加密配置。

firebase firestore:databases:restore \
--database DATABASE_ID \
--backup 'projects/FIRESTORE_PROJECT/locations/FIRESTORE_LOCATION/backups/BACKUP_ID' \
--encryption-type CUSTOMER_MANAGED_ENCRYPTION \
--kms-key-name projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID \
--project FIRESTORE_PROJECT

替换以下内容：

• 将 DATABASE_ID 替换为您的数据库的 ID
• 将 FIRESTORE_PROJECT 替换为要用于 Cloud Firestore 数据库的项目
• 将 FIRESTORE_LOCATION 替换为 Cloud Firestore 数据库的位置
• 将 BACKUP_ID 替换为您的备份 ID
• 将 KMS_PROJECT 替换为包含 CMEK 密钥的项目
• 将 KMS_LOCATION 替换为包含 CMEK 密钥和密钥环的位置
• 将 KMS_KEYRING_ID 替换为您的 CMEK 密钥环的 ID

确认您恢复的 Cloud Firestore 数据库已启用 CMEK 加密：

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

将受 CMEK 保护的数据库恢复为使用默认加密

如需恢复到 Google 默认加密（未启用 CMEK），请按以下方式设置 encryption-type 标志：

firebase firestore:databases:restore \
--database DATABASE_ID \
--backup 'projects/FIRESTORE_PROJECT/locations/FIRESTORE_LOCATION/backups/BACKUP_ID' \
--encryption-type GOOGLE_DEFAULT_ENCRYPTION \
--project FIRESTORE_PROJECT

替换以下内容：

• 将 DATABASE_ID 替换为您的数据库的 ID
• 将 FIRESTORE_PROJECT 替换为要用于 Cloud Firestore 数据库的项目
• 将 FIRESTORE_LOCATION 替换为 Cloud Firestore 数据库的位置
• 将 BACKUP_ID 替换为您的备份 ID

将受 CMEK 保护的数据库恢复为与备份相同的加密类型

如需恢复为与备份相同的加密类型，请按以下方式设置 encryption-type 标志：

firebase firestore:databases:restore \
--database DATABASE_IDD \
--backup 'projects/FIRESTORE_PROJECT/locations/FIRESTORE_LOCATION/backups/BACKUP_ID' \
--encryption-type USE_SOURCE_ENCRYPTION

替换以下内容：

• 将 DATABASE_ID 替换为您的数据库的 ID
• 将 FIRESTORE_PROJECT 替换为要用于 Cloud Firestore 数据库的项目
• 将 FIRESTORE_LOCATION 替换为 Cloud Firestore 数据库的位置
• 将 BACKUP_ID 替换为您的备份 ID

gcloud

您可以使用 databases describe gcloud CLI 命令来确认数据库 CMEK 配置：

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

您应该会在响应的 cmekConfig 字段中看到 CMEK 信息，如下所示：

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

响应包含以下信息：

• kmsKeyName：用于加密受 CMEK 保护的数据库的密钥的完整密钥资源名称。
• activeKeyVersion：列出目前由受 CMEK 保护的数据库使用的所有密钥版本。在密钥轮替期间，您可以有多个有效的密钥版本。在密钥轮替期间，旧版和新版密钥都必须保持可用状态。请勿在旧版密钥仍显示在 activeKeyVersion 字段中时将其停用。

REST API

HTTP 请求：

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

在请求正文的 cmek_config.kms_key_name 字段中配置 CMEK 密钥。设置为 Cloud KMS 密钥的完整资源 ID。仅允许与此数据库位于同一位置的密钥。

此值应为 Cloud KMS 密钥资源 ID，格式为 projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}

如需详细了解其他字段，请参阅 database create 页面。

请求和响应示例：

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