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

控制台

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

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

   转到 IAM 页面

2. 点击添加。

3. 输入 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. 如果系统提示您向 Firestore 服务账号授予密钥权限，请点击授予。如需创建 CMEK 数据库，您必须向 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，其中包含数据库的 Firestore 位置
• DATABASE_ID（其中包含数据库的 ID）

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

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

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

REST API

HTTP 请求：

POST https://firestore.googleapis.com/v1/projects/{FIRESOTRE_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 参数，Firestore 会默认创建非 CMK 数据库。

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 替换为要用于 Firestore 数据库的项目

使用 Firebase CLI 确认您的 Firestore 数据库是否已受到保护：

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

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

• KMS 密钥名称字段提供用于加密 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 替换为要用于 Firestore 数据库的项目
• DATABASE_ID（其中包含数据库的 ID）
• FIRESTORE_DATABASE_LOCATION，其中包含数据库的 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 替换为要用于 Firestore 数据库的项目
• 将 FIRESTORE_LOCATION 替换为您的 Firestore 数据库的位置
• 将 BACKUP_ID 替换为您的备份 ID
• KMS_PROJECT 替换为包含 CMEK 密钥的项目
• KMS_LOCATION 替换为包含 CMEK 密钥和密钥环的位置
• 将 KMS_KEYRING_ID 替换为您的 CMEK 密钥环的 ID

确认恢复的 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 替换为要用于 Firestore 数据库的项目
• 将 FIRESTORE_LOCATION 替换为您的 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 替换为要用于 Firestore 数据库的项目
• 将 FIRESTORE_LOCATION 替换为您的 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"
    ]
  },
  ……
}