使用客戶自行管理的加密金鑰 (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，其中包含您要授予存取權的服務代理的電子郵件格式 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 控制台的「資料庫」頁面。

   前往「資料庫」頁面

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

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

4. 在「Configure your database」(設定資料庫) 頁面中，輸入資料庫 ID。

5. 選取位置。

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

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

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

9. 如果系統提示您將金鑰權限授予 Cloud Firestore 服務帳戶，請按一下「授予」。如要建立 CMEK 資料庫，您的 Cloud 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，另有 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 Key Name 欄位。如果未指定 --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 資料庫的專案

確認 Cloud Firestore 資料庫已透過 Firebase CLI 受到保護：

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

回應訊息中會顯示下列 CMEK 資訊：

• 「KMS Key Name」欄位會提供用於加密 Cloud Firestore CMEK 資料庫的完整金鑰資源名稱。
• 「Active Key Versions」欄位會列出目前由此 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 加密，請搭配選用的 encryption-type 和 kms-key-name 標記執行 gcloud firestore databases restore 指令，為還原的資料庫設定加密類型。如果您未指定加密類型，還原的資料庫會使用與備份相同的加密設定。

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