استخدام مفاتيح التشفير المُدارة للعميل (CMEK)

وحدة التحكم

لمنح دور Cloud KMS إلى وكيل الخدمة، اتّبِع الخطوات التالية: يمكنك أيضًا منح الإذن على مستوى المفتاح أو سلسلة المفاتيح إذا أردت مستوى دقة أقل.

1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة إدارة الهوية وإمكانية الوصول.

   الانتقال إلى صفحة "إدارة الهوية وإمكانية الوصول"

2. انقر على إضافة.

3. أدخِل رقم التعريف بتنسيق البريد الإلكتروني لوكيل خدمة Cloud Firestore.

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. انقر على إنشاء قاعدة بيانات (Create Database).

3. اختَر وضع قاعدة البيانات. انقر على متابعة.

4. في صفحة ضبط قاعدة البيانات، أدخِل معرّف قاعدة البيانات.

5. حدد موقعًا.

6. انقر على عرض خيارات التشفير، ثم اختَر مفتاح Cloud KMS.

7. اختَر أو أدخِل اسم المورد لمفتاح CMEK الذي تريد استخدامه لقاعدة البيانات.

8. تقتصر قائمة المفاتيح على مشروع Google Cloud الحالي وموقع قاعدة البيانات الذي اخترته. لاستخدام مفتاح من مشروع Google Cloud مختلف، انقر على تبديل المشروع أو إدخال المفتاح يدويًا.

9. إذا طُلب منك منح إذن المفتاح لحساب خدمة Cloud Firestore، انقر على منح. لإنشاء قاعدة بيانات مفاتيح التشفير المُدارة من العميل (CMEK)، يجب منح حساب خدمة "Cloud Firestore" دور "cloudkms.cryptoKeyEncrypterDecrypter".

10. اختَر قواعد الأمان لعملاء الأجهزة الجوّالة والويب.

11. انقر على إنشاء قاعدة بيانات (Create Database).

بعد إنشاء قاعدة البيانات، يمكنك التأكّد من أنّها متوافقة مع مفتاح التشفير المُدار من العميل من خلال الاطّلاع على تفاصيل قاعدة البيانات:

• إذا كانت قاعدة بياناتك محمية باستخدام مفاتيح التشفير التي يديرها العميل (CMEK)، سيظهر حقل نوع التشفير على أنّه يديره العميل، وسيعرض حقل مفتاح التشفير خدمة Cloud KMS المقابلة وإصدار المفتاح المستخدَم لحماية قاعدة البيانات هذه.
• إذا لم تكن قاعدة بياناتك محمية بمفاتيح التشفير المُدارة من العميل، سيظهر حقل نوع التشفير على أنّه مُدار من Google.

gcloud

قبل إنشاء قاعدة بيانات تم تفعيل ميزة "مفاتيح التشفير التي يملكها العميل" (CMEK) فيها باستخدام "Google Cloud CLI"، عليك تثبيت أحدث إصدار من "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 مع معرّف لقاعدة البيانات

• 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 في الحقل cmek_config.kms_key_name.

يجب ضبطه على رقم تعريف المورد الكامل لمفتاح Cloud KMS. يُسمح فقط باستخدام مفتاح في الموقع الجغرافي نفسه لقاعدة البيانات هذه.

يجب أن تكون هذه القيمة هي رقم تعريف مورد مفتاح Cloud KMS بالتنسيق التالي: 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

لإنشاء قاعدة بيانات تم تفعيل ميزة "مفاتيح التشفير التي يملكها العميل" فيها، استخدِم حقل اسم مفتاح 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 بمعرّف قاعدة بياناتك
• LOCATION بموقع قاعدة بياناتك
• ‫KMS_PROJECT مع المشروع الذي يحتوي على مفتاح CMEK
• ‫KMS_LOCATION بالموقع الجغرافي الذي يحتوي على مفتاح CMEK وسلسلة المفاتيح
• KMS_KEYRING_ID بمعرّف سلسلة مفاتيح CMEK
• FIRESTORE_PROJECT مع المشروع لاستخدامها في قاعدة بيانات Cloud Firestore

تأكَّد من أنّ قاعدة بيانات Cloud Firestore محمية باستخدام Firebase CLI:

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

تظهر معلومات مفتاح CMEK التالية في رسالة الردّ:

• يوفّر حقل اسم مفتاح KMS الاسم الكامل لمورد المفتاح المستخدَم لتشفير قاعدة بيانات "مفاتيح التشفير التي يديرها العميل" في Cloud Firestore.
• يوفّر حقل إصدارات المفاتيح النشطة قائمة بجميع إصدارات المفاتيح المستخدَمة حاليًا في قاعدة بيانات "مفاتيح التشفير التي يديرها العميل" هذه. أثناء تدوير المفاتيح، يمكن أن يكون لديك نُسخ مفاتيح نشطة متعدّدة.

Terraform

لإنشاء قاعدة بيانات تم تفعيل ميزة "مفاتيح التشفير المُدارة من العميل" فيها، استخدِم المورد 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 مع معرّف لقاعدة البيانات
• ‫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 التلقائي (غير المستند إلى مفتاح إدارة العميل)، اضبط العلامة encryption-type على النحو التالي:

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

استعادة قاعدة بيانات محمية بمفاتيح تشفير يديرها العميل إلى نوع التشفير نفسه المستخدَم في النسخة الاحتياطية

للاستعادة إلى نوع التشفير نفسه المستخدَم في النسخة الاحتياطية، اضبط العلامة encryption-type على النحو التالي:

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

Firebase CLI

استعادة قاعدة بيانات محمية بمفاتيح التشفير التي يديرها العميل (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 بمعرّف قاعدة بياناتك
• FIRESTORE_PROJECT مع المشروع لاستخدامها في قاعدة بيانات Cloud Firestore
• FIRESTORE_LOCATION بموقع قاعدة بيانات Cloud Firestore
• ‫BACKUP_ID مع رقم تعريف النسخة الاحتياطية
• ‫KMS_PROJECT مع المشروع الذي يحتوي على مفتاح CMEK
• ‫KMS_LOCATION بالموقع الجغرافي الذي يحتوي على مفتاح CMEK وسلسلة المفاتيح
• KMS_KEYRING_ID بمعرّف سلسلة مفاتيح CMEK

تأكَّد من أنّ قاعدة بيانات Cloud Firestore التي تمت استعادتها مشفَّرة باستخدام مفتاح CMEK:

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

استعادة قاعدة بيانات محمية بمفتاح CMEK إلى التشفير التلقائي

لاستعادة تشفير Google التلقائي (غير المستند إلى مفتاح إدارة العميل)، اضبط العلامة 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 بمعرّف قاعدة بياناتك
• FIRESTORE_PROJECT مع المشروع لاستخدامها في قاعدة بيانات Cloud Firestore
• FIRESTORE_LOCATION بموقع قاعدة بيانات Cloud Firestore
• ‫BACKUP_ID مع رقم تعريف النسخة الاحتياطية

استعادة قاعدة بيانات محمية بمفاتيح تشفير يديرها العميل إلى نوع التشفير نفسه المستخدَم في النسخة الاحتياطية

للاستعادة إلى نوع التشفير نفسه المستخدَم في النسخة الاحتياطية، اضبط العلامة 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 بمعرّف قاعدة بياناتك
• FIRESTORE_PROJECT مع المشروع لاستخدامها في قاعدة بيانات Cloud Firestore
• FIRESTORE_LOCATION بموقع قاعدة بيانات Cloud Firestore
• ‫BACKUP_ID مع رقم تعريف النسخة الاحتياطية

gcloud

استنساخ قاعدة بيانات محمية بمفاتيح تشفير يديرها العميل (CMEK) إلى تشفير CMEK

للاستنساخ إلى تشفير CMEK، نفِّذ الأمر gcloud firestore databases clone باستخدام العلامتَين الاختياريتَين encryption-type وkms-key-name لضبط نوع التشفير لقاعدة البيانات المستنسَخة. إذا لم تحدّد نوع التشفير، ستستخدم قاعدة البيانات المستنسَخة إعدادات التشفير نفسها المستخدَمة في قاعدة البيانات المصدر.

gcloud firestore databases clone \
--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

استنسِخ قاعدة بيانات محمية بمفتاح تشفير مُدار من العميل إلى التشفير التلقائي

لاستنساخ الملفات باستخدام تشفير Google التلقائي (غير المستند إلى مفاتيح تشفير تديرها المؤسسة)، اضبط علامة encryption-type على النحو التالي:

gcloud firestore databases clone \
--encryption-type=google-default-encryption

استنسِخ قاعدة بيانات محمية بمفاتيح تشفير يديرها العميل (CMEK) إلى نوع التشفير نفسه المستخدَم في قاعدة البيانات المصدر

للاستنساخ إلى نوع التشفير نفسه المستخدَم في قاعدة البيانات المصدر، اضبط العلامة encryption-type على النحو التالي:

gcloud firestore databases clone \
--encryption-type=use-source-encryption

وهذا هو أيضًا الإعداد التلقائي في حال عدم تحديد --encryption-type.

Firebase CLI

استنساخ قاعدة بيانات محمية بمفاتيح تشفير يديرها العميل (CMEK) إلى تشفير CMEK

لاستنساخ تشفير CMEK، شغِّل الأمر firebase firestore:databases:clone باستخدام علامتَي encryption-type وkms-key-name الاختياريتَين لضبط نوع التشفير لقاعدة البيانات المستنسَخة. إذا لم تحدّد نوع التشفير، ستستخدم قاعدة البيانات المستنسَخة إعدادات التشفير نفسها المستخدَمة في قاعدة البيانات المصدر.

firebase firestore:databases:clone \
SOURCE_DATABASE \
DESTINATION_DATABASE \
--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

استنسِخ قاعدة بيانات محمية بمفتاح تشفير مُدار من العميل إلى التشفير التلقائي

لاستنساخ الملفات باستخدام تشفير Google التلقائي (غير المستند إلى مفاتيح تشفير تديرها المؤسسة)، اضبط علامة encryption-type على النحو التالي:

firebase firestore:databases:clone \
SOURCE_DATABASE \
DESTINATION_DATABASE \
--encryption-type=GOOGLE_DEFAULT_ENCRYPTION

استنسِخ قاعدة بيانات محمية بمفاتيح تشفير يديرها العميل (CMEK) إلى نوع التشفير نفسه المستخدَم في قاعدة البيانات المصدر

للاستنساخ إلى نوع التشفير نفسه المستخدَم في قاعدة البيانات المصدر، اضبط العلامة encryption-type على النحو التالي:

firebase firestore:databases:clone \
SOURCE_DATABASE \
DESTINATION_DATABASE \
--encryption-type=USE_SOURCE_ENCRYPTION

وهذا هو أيضًا الإعداد التلقائي في حال عدم تحديد --encryption-type.

gcloud

يمكنك استخدام الأمر databases describe gcloud CLI لتأكيد ضبط مفتاح CMEK لقاعدة البيانات:

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

من المفترض أن تظهر معلومات CMEK في الحقل cmekConfig في الردّ على النحو التالي:

      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 في الحقل cmek_config.kms_key_name. يجب ضبطه على رقم تعريف المورد الكامل لمفتاح Cloud KMS. يُسمح فقط باستخدام مفتاح في الموقع الجغرافي نفسه لقاعدة البيانات هذه.

يجب أن تكون هذه القيمة هي رقم تعريف مورد مفتاح Cloud KMS بالتنسيق التالي: 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"
    ]
  },
  ……
}