إدارة الملفات المشفَّرة من جهة العميل باستخدام Drive API

يضمن التشفير من جهة العميل (CSE) تشفير بياناتك قبل وصولها إلى خوادم Drive، ما يمنحك التحكّم في بياناتك. يرشدك هذا الدليل إلى عملية تشفير ملفات التشفير من جهة العميل وتحميلها آليًا، بالإضافة إلى تنزيلها وفك تشفيرها باستخدام Drive API. ويشمل أيضًا الأساليب المقترَحة لاختبار عملية التنفيذ والتحقّق من صحتها.

قبل البدء

قبل إدارة الملفات المشفرة، عليك إعداد نطاق Google Workspace باستخدام قائمة التحقّق التالية:

• ضبط التشفير من جهة العميل (CSE) لنطاقك

• إعداد موفِّر الهوية (IdP)

• تأكَّد من أنّ خدمة قائمة التحكّم بالوصول إلى مفاتيح التشفير (KACLS) تتوافق مع نقاط النهاية /wrap و/unwrap و/privilegedwrap و/privilegedunwrap و/digest.

• أنشئ مشروعًا في وحدة تحكّم Google Cloud وفعِّل Drive API.

المصادقة والتفويض

للتفاعل مع Drive API وKACLS، عليك اختيار طريقة مصادقة. يؤثّر هذا الاختيار في كيفية تفاعلك مع كلتا الخدمتين:

• فرد: للمصادقة بصفتك فردًا، استخدِم خطوات OAuth للتصرّف نيابةً عن هذا المستخدم. استخدِم نقطتَي النهاية العاديتَين /wrap و /unwrap، وقدِّم رمز تفويض Google الخاص بهذا المستخدم.
• المشرف: لانتحال هوية مستخدمين آخرين في النطاق، استخدِم حساب خدمة مع التفويض على مستوى النطاق. استخدِم نقطتَي النهاية /privilegedwrap و/privilegedunwrap بدون رمز مميّز للمصادقة من Google.

تنبيه: في حال استخدام حساب خدمة بدون تفويض على مستوى النطاق، تتم إضافة الملفات التي تم إنشاؤها إلى مساحة تخزين حساب الخدمة وليس إلى مساحة تخزين مستخدم معيّن، ما يجعل الملفات غير متاحة للمستخدمين.

للحصول على تفاصيل إضافية حول إنشاء بيانات الاعتماد، يُرجى الاطّلاع على دليل إنشاء بيانات اعتماد الوصول.

مصادقة موفّر هوية النطاق

لإجراء المصادقة باستخدام موفّر الهوية، يجب ضبط معرّف عميل OAuth وتنزيل ملف سر العميل. يجب أن يحصل تطبيقك على رمز مميّز للمصادقة من موفِّر الهوية (IdP) للمصادقة على الطلبات التي يتم إرسالها إلى خدمة KACLS. هذه الرمز المميز مطلوب للسماح لتطبيقك بالوصول إلى مفتاح تشفير البيانات.

التعامل مع بيانات الاعتماد بأمان

يتعامل تطبيقك مع بيانات الاعتماد الحسّاسة للمصادقة على Drive API وموفّر الهوية. ومن بينها:

• معلومات سرية من موفّر الهوية، مثل ملف سر العميل
• مادة سرية من Google، مثل ملف مفتاح خاص لحساب الخدمة
• المواد السرية التي يخزّنها التطبيق، مثل بيانات الاعتماد المحفوظة

يجب التأكّد من تخزين جميع بيانات الاعتماد هذه بأمان.

الحدود والحصص

تخضع الملفات المشفَّرة من جهة العميل لحدود وحصص Drive العادية. يُرجى العلم بحدود مساحة التخزين السحابي المشتركة وحدود الملفات والمجلدات العامة وكيفية إدارة حصتك. بالإضافة إلى ذلك، يجب أن تتعامل أداة الاستيراد مع حدود المعدّل من خدمة قائمة التحكّم بالوصول إلى مفاتيح التشفير (KACLS) وموفِّر الهوية (IdP).

بنية الملف المشفّر

يتوقّع Drive أن يكون تنسيق الملفات المشفَّرة من جهة العميل على النحو التالي عند تحميلها وتنزيلها.

+-------------------+
| Magic header      |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ...               |
+-------------------+
| Encrypted Chunk N |
+-------------------+

العنوان السحري

الرأس السحري (المعروف أيضًا باسم توقيع الملف أو الرقم السحري) هو تسلسل ثابت من البايتات يتم وضعه في بداية الملف للتعرّف على تنسيقه بشكل فريد. يجب أن يبدأ الملف بالبايتات 0x99 0x5E 0xCC 0x5E.

القطع المشفّرة

يجب تقسيم الملف إلى أجزاء بحجم 2 ميغابايت. يتم تشفير كل جزء باستخدام أداة التشفير الأساسية AEAD (التشفير المصادق عليه مع البيانات المرتبطة) من مكتبة Google Tink مع نوع مفتاح AES-GCM، وذلك باستخدام فهرس الجزء وعلامة الجزء النهائي كبيانات مرتبطة. للحصول على مثال على رمز برمجي يستخدم Drive API ويتوافق مع هذه المواصفات، راجِع العرض التوضيحي المفتوح المصدر.

تحذير: لن يتمكّن Drive من فك تشفير الملفات من جهة العميل إذا كانت منظَّمة بشكل غير صحيح. اطّلِع على أساليب التحقّق لمعرفة طرق الاختبار المقترَحة.

تشفير ملف وتحميله

لتحميل ملف مشفّر من جهة العميل، يجب أن يصادق تطبيقك على نفسه، ويطلب رمزًا مميزًا للتشفير من جهة العميل، ويشفّر محتوى الملف محليًا، ويغلّف مفتاح التشفير، ثم يحمّل المحتوى المشفّر والبيانات الوصفية إلى Google Drive.

الحصول على رمز مميّز لميزة "التشفير من جهة العميل"

اطلب رمزًا مميزًا من "بحث Google المخصّص" من Google Drive من خلال استدعاء طريقة Drive API Files:generateCseToken. تأكَّد من عدم تضمين مَعلمة طلب البحث fileId في الطلب. لإنشاء الملف في مجلد معيّن، أدرِج المَعلمة parent في طلب البحث مع رقم تعريف المجلد. في حال حذف parent، يتم إنشاء الملف في مجلد الجذر "ملفاتي" الخاص بالمستخدم. تتضمّن الاستجابة رقم تعريف ملف فريدًا لعملية التحميل ورمزًا مميّزًا للتفويض بتنسيق JWT، وهو مطلوب في خطوة تغليف المفتاح.

تشفير البيانات محليًا

1. استخدِم Google Tink لإنشاء مفتاح تشفير بيانات (DEK) فريد للملف.
2. يجب تشفير محتوى الملف وفقًا لبنية الملف المشفّر.

احتساب تجزئة مفتاح مورد الحوسبة

لحساب تجزئة مفتاح المورد، اتّبِع الخطوات التالية:

1. استخرِج resource_name وperimeter_id من رمز التفويض jwt الذي تم تلقّيه من generateCseToken. في حال عدم توفّر perimeter_id، استخدِم سلسلة فارغة.
2. احسب HMAC-SHA256 باستخدام مفتاح تشفير البيانات (DEK) كنص عادي كمفتاح والسلسلة ResourceKeyDigest:my_resource_name:my_perimeter_id كبيانات للتوقيع.
3. رمِّز قيمة التجزئة الناتجة باستخدام Base64.

لمزيد من التفاصيل، يُرجى الاطّلاع على تجزئة مفتاح المورد.

تشفير مفتاح التشفير

لحماية مفتاح تشفير البيانات (DEK)، يجب تشفيره (تغليفه) باستخدام خدمة إدارة مفاتيح التشفير الخارجية.

1. اتّصِل بنقطة النهاية المناسبة:
   • فردي: /wrap
   • المشرف: /privilegedwrap
2. مرِّر مفتاح تشفير البيانات العادي ورمز مصادقة موفِّر الهوية ورمز تفويض Google (إذا كان مطلوبًا) وresource_name من رمز JWT وreason.
3. استلِم مفتاح تشفير البيانات (DEK) المغلف (WDEK) من خدمة KACLS.

تحميل على Drive

استخدِم نقطة نهاية Drive API files.create لإجراء عملية تحميل ملف عادية لبيانات الملف المشفّر. اضبط الحقول التالية في البيانات الوصفية للملف:

• id: هو المعرّف الفريد للملف الذي تم استلامه من ردّ generateCseToken.
• mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
  • يمكن ضبط المَعلمة content على نوع MIME للملف الأصلي.
• clientEncryptionDetails:
  • encryptionState: "encrypted".
  • decryptionMetadata:
    • ‫wrappedKey: مفتاح فك تشفير المحتوى (WDEK) الذي تم استلامه من KACLS
    • ‫kaclsId: هو رقم تعريف KACLS الذي تم تلقّيه من الردّ generateCseToken.
    • keyFormat: "tinkAesGcmKey".
    • aes256GcmChunkSize: "default".
    • ‫encryptionResourceKeyHash: التجزئة التي تم احتسابها في احتساب تجزئة مفتاح المورد

ملاحظة: تتطلّب بعض الحقول ترميز base64. يمكنك الاطّلاع على مستندات Drive API للحصول على التفاصيل

مثال على المصادر المفتوحة

للحصول على عرض توضيحي عملي لعملية التشفير والتحميل، يُرجى الرجوع إلى العرض التوضيحي المفتوح المصدر. يوفّر ذلك حلاً عمليًا ويمكن أن يكون مرجعًا مفيدًا.

تنزيل ملف وفك تشفيره

يتطلّب تنزيل ملف CSE استرداد المحتوى المشفّر والبيانات الوصفية من Google Drive، وطلب مفتاح فك التشفير النصي العادي من خدمة إدارة مفاتيح التشفير (KACLS)، ثم فك تشفير الملف محليًا.

استرداد البيانات الوصفية للملف والمحتوى المشفّر

استدعِ طريقة Files:get في Drive API لاسترداد البيانات الوصفية ومحتوى الملف. يحتوي clientEncryptionDetails على DecryptionMetadata الذي يتضمّن مفتاح تشفير البيانات (DEK) المغلف (WDEK) ورمز JWT الذي يتضمّن معلومات KACLS.

فك تشفير مفتاح التشفير

1. اتّصِل بنقطة النهاية المناسبة:
   • فردي: /unwrap
   • المشرف: /privilegedunwrap
2. مرِّر مفتاح WDEK ورمز مصادقة موفِّر الهوية ورمز تفويض Google (إذا كان ذلك مطلوبًا) وresource_name وreason.
3. تلقّي مفتاح فك التشفير بنص عادي من خدمة KACLS

فك تشفير البيانات محليًا

1. إعداد الرمز باستخدام مفتاح تشفير البيانات (DEK) للنص العادي الذي تم استلامه من خدمة KACLS.
2. تخطَّ وحدات البايت السحرية الأولية وفك تشفير المحتوى المتبقي وفقًا لبنية الملف المشفّر.

مثال على المصادر المفتوحة

للحصول على عرض توضيحي عملي لعملية التنزيل وفك التشفير، يُرجى الرجوع إلى العرض التوضيحي المفتوح المصدر. يوفّر ذلك حلاً عمليًا ويمكن أن يكون مرجعًا مفيدًا.

التحقّق من صحة الملفات المستورَدة

بما أنّ Google لا يمكنها الوصول إلى مفاتيح التشفير، لا يمكنها فك تشفير ملفاتك والتحقّق من صحتها من جهة الخادم. سيؤدي حدوث أخطاء في التنفيذ أثناء مراحل التشفير المحلي أو تغليف المفاتيح إلى حدوث أخطاء عند فك تشفير الملفات من جهة العميل. من الضروري إجراء عملية تحقّق شاملة قبل استخدام عملية التنفيذ الخاصة بك.

لكي يعمل محتوى "بحث مخصص من Google" الذي تم تحميله من Google Drive بشكلٍ صحيح، يجب أن يكون مشفّرًا بشكلٍ سليم وأن يحتوي على البيانات الوصفية الصحيحة. وتقع عليك مسؤولية التأكّد من أنّ المحتوى صالح ويمكن فك تشفيره.

إجراء اختبارات التشفير وفك التشفير ذهابًا وإيابًا

للتأكّد من صحة عملية التنفيذ، من الضروري اختبار مسار العملية بالكامل. يتضمّن ذلك أخذ مجموعة من الملفات التجريبية وتشفيرها باستخدام المنطق المحلي، ثم تحميلها إلى Drive باستخدام واجهة برمجة التطبيقات، وبعد ذلك تنزيلها وفك تشفيرها. بعد فك التشفير، قارِن المحتوى الناتج بالملفات الأصلية للتأكّد من تطابقهما. تساعد هذه العملية في رصد أي مشاكل في التشفير أو تغليف المفاتيح أو معالجة البيانات الوصفية. يوضّح العرض التوضيحي المفتوح المصدر كيف يمكنك تنفيذ عملية التحقّق هذه داخل تطبيقك.

التحقّق من صحة المعلومات باستخدام Google Drive

تأكَّد من أنّ الملفات التي تم تحميلها تتضمّن رمز قفل في تطبيق Drive على الويب. نزِّل يدويًا عددًا قليلاً من الملفات التي تم تحميلها للتأكّد من أنّها تعمل على النحو المتوقّع. يستخدم هذا التحقّق عملية تنفيذ ميزة "التشفير من جهة العميل" من Google لمحاولة فك التشفير، ما يساعد في تحديد المشاكل في التشفير أو منطق تغليف المفاتيح. تضمين الملفات من كلّ من ملفاتي ومساحات التخزين السحابي المشتركة

تحذير: لا تحذف ملفات المصدر الأصلية إلى أن تتأكّد تمامًا من إمكانية فك تشفير إصدارات CSE التي تم استيرادها.

فتح العرض التوضيحي للرمز المصدري

توفر حزمة تحميل "التشفير من جهة العميل" في Drive مفتوحة المصدر مكتبة Python كاملة وعاملة ومثالاً على سطر الأوامر ينفّذ عمليات التحميل والتنزيل باستخدام ميزة "التشفير من جهة العميل" الموضّحة في هذا الدليل. ننصحك بشدة بمراجعة الرمز التجريبي قبل إنشاء عملية دمج خاصة بك لمحرك البحث المخصّص.