إدارة الملفات المشفَّرة من جهة العميل باستخدام 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 الخاص بهذا المستخدم.
• المشرف: لانتحال هوية مستخدمين آخرين في النطاق، استخدِم حساب خدمة مع التفويض على مستوى النطاق (DWD). استخدِم نقطتَي النهاية /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 من فك تشفير الملفات من جهة العميل إذا كانت منظَّمة بشكل غير صحيح. اطّلِع على أساليب التحقّق لمعرفة طرق الاختبار المقترَحة.

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

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

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

اطلب رمزًا مميزًا لـ "بحث مبرمَج" من Google Drive من خلال استدعاء طريقة Files:generateCseToken في Drive API. تأكَّد من عدم تضمين مَعلمة طلب البحث 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: مفتاح تشفير البيانات (DEK) المغلف (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. تلقّي مفتاح تشفير البيانات (DEK) بنص عادي من خدمة KACLS

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

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

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

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

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

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

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

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

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

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

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

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

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

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