استخدام مفاتيح التشفير المُدارة للعميل (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 من خلال الاطّلاع على تفاصيل قاعدة البيانات:

• إذا كانت قاعدة بياناتك محمية باستخدام مفاتيح التشفير التي يديرها العميل (CMEK)، سيظهر حقل نوع التشفير على أنّه مُدار من قِبل العميل، وسيعرض حقل مفتاح التشفير خدمة Cloud KMS المقابلة وإصدار المفتاح المستخدَم لحماية قاعدة البيانات هذه.
• إذا لم تكن قاعدة بياناتك محمية باستخدام مفتاح CMEK، سيظهر حقل نوع التشفير على أنّه مُدار من 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

لإنشاء قاعدة بيانات تم تفعيل ميزة 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 بمعرّف قاعدة بياناتك
• ‫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 التلقائي (غير المستند إلى مفتاح CMEK)، اضبط العلامة 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

لاستعادة تشفير 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 التلقائي (غير المستند إلى مفتاح 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 بمعرّف قاعدة بياناتك
• 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"
    ]
  },
  ……
}