使用客戶自行管理的加密金鑰 (CMEK)

主控台

如要將 Cloud KMS 角色授予服務代理，請按照下列步驟操作。如要降低精細度，您也可以在金鑰或金鑰環層級授予權限。

1. 前往 Google Cloud 控制台的「IAM」頁面。

   前往「IAM」頁面

2. 按一下「新增」。

3. 輸入 Firestore 服務代理程式的電子郵件格式 ID。

4. 選取「Cloud KMS CryptoKey Encrypter/Decrypter」(Cloud KMS 加密編譯金鑰加密者/解密者) 角色。

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，並以電子郵件格式的 ID 指定要授予存取權的服務代理
• 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 控制台的「Databases」頁面。

   前往「資料庫」頁面

2. 按一下 [Create Database] (建立資料庫)。

3. 選取資料庫模式。按一下「繼續」。

4. 在「設定資料庫」頁面中，輸入資料庫 ID。

5. 選取地點。

6. 按一下「顯示加密選項」，然後選取「Cloud KMS 金鑰」。

7. 選取或輸入要用於資料庫的 CMEK 金鑰資源名稱。

8. 金鑰清單僅限於您選取的目前 Google Cloud 專案和資料庫位置。如要使用其他 Google Cloud 專案的金鑰，請按一下「切換專案」或「手動輸入金鑰」。

9. 如果系統提示您授予 Firestore 服務帳戶金鑰權限，請按一下「授予」。如要建立 CMEK 資料庫，必須授予 Firestore 服務帳戶 cloudkms.cryptoKeyEncrypterDecrypter 角色。

10. 為行動和網路用戶端選取安全性規則。

11. 按一下 [Create Database] (建立資料庫)。

建立資料庫後，您可以查看「資料庫詳細資料」，確認資料庫是否已啟用 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/{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 參數，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，並在專案中用於 Firestore 資料庫

確認 Firestore 資料庫受到 Firebase CLI 保護：

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