شفافية الرمز لحِزم التطبيقات

"شفافية الرمز" هي آلية اختيارية لتوقيع الرموز والتحقق منها في التطبيقات المنشورة باستخدام "مجموعة حزمات تطبيق Android". يستخدم مفتاح توقيع شفافية التعليمة البرمجية، الذي يحتفظ به مطور التطبيق فقط.

إنّ شفافية الرمز البرمجي مستقلة عن مخطط التوقيع المستخدَم لحِزم التطبيقات وAPK. يكون مفتاح شفافية الرمز منفصلاً ويختلف عن مفتاح توقيع التطبيق الذي يتم تخزينه على البنية الأساسية الآمنة من Google عند استخدام ميزة توقيع التطبيق من Play.

آلية عمل شفافية الرموز

تتم هذه العملية من خلال تضمين ملف شفافية الرمز البرمجي في الحِزمة بعد إنشائه، ولكن قبل تحميله إلى Play Console للتوزيع.

ملف شفافية الرمز هو رمز JSON المميّز للويب (JWT) يحتوي على قائمة بملفات DEX والمكتبات الأصلية المضمّنة في الحِزمة، وتجزئاتها. ثم يتم توقيعه باستخدام مفتاح شفافية التعليمة البرمجية الذي يحتفظ به المطور فقط.

يتم نشر ملف شفافية الرمز هذا في حزمة APK الأساسية التي تم إنشاؤها من حزمة التطبيقات (خاصةً في القسم الرئيسي للوحدة الأساسية). يمكن بعد ذلك التحقق مما يلي:

• تشتمل جميع ملفات DEX وملفات الرموز الأصلية المتوفرة في حِزم APK على تجزئات مطابقة في ملف شفافية الرمز.
• يتطابق مكوّن المفتاح العام لمفتاح توقيع شفافية الرمز في التطبيق مع المفتاح العام للمطوّر (الذي يجب أن يوفّره مطوّر البرامج عبر قناة منفصلة وآمنة).

وتثبت هذه المعلومات مجتمعة أنّ الرمز البرمجي الوارد في حِزم APK مطابق لما أراده المطوّر، وأنّه لم يتم تعديله.

لا يتحقق ملف شفافية الرمز من الموارد أو مواد العرض أو ملف بيان Android أو أي ملفات أخرى ليست ملفات DEX أو مكتبات أصلية يحتوي عليها مجلد lib/.

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

القيود المعروفة

هناك مواقف معينة لا يمكن فيها استخدام شفافية الرموز:

• التطبيقات التي تحدّد السمة sharedUserId في ملف البيان. قد تشارك مثل هذه التطبيقات عمليتها مع تطبيقات أخرى، ما يصعِّب ضمانات بخصوص الرمز الذي يتم تنفيذه.
• ستؤدي التطبيقات التي تستخدم الحماية من التلاعب أو أي خدمة أخرى تُجري تغييرات في الرموز بعد إنشاء ملف شفافية الرموز إلى تعذُّر عملية التحقق من شفافية الرموز.
• التطبيقات التي تستخدم ميزة Multidex القديمة على مستويات واجهة برمجة التطبيقات الأقدم من 21 (Android 5.0) وتستخدم وحدات الميزات. سيستمر عمل شفافية الرمز عندما يتم تثبيت التطبيق من خلال Google Play على أجهزة Android 5.0 والإصدارات الأحدث. سيتم إيقاف شفافية الرمز على الإصدارات الأقدم من نظام التشغيل.

كيفية إضافة شفافية الرمز

لكي تتمكّن من إضافة شفافية الرموز إلى تطبيقك، احرص على توفير مفتاحَي تشفير خاص وعام يمكنك استخدامهما لتوقيع رمز الشفافية. ويجب أن يكون هذا المفتاح فريدًا يختلف عن مفتاح توقيع التطبيق الذي تستخدمه لميزة "توقيع التطبيق" من Play، ويجب أن يتم الاحتفاظ به بشكل آمن وعدم مشاركته خارج مؤسستك مطلقًا.

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

استخدام المكوّن الإضافي لنظام Gradle المتوافق مع Android

تتطلّب ميزة "شفافية الرمز" توفّر الإصدار 7.1.0-alpha03 من المكوّن الإضافي Android Gradle أو إصدارًا أحدث. لضبط المفتاح المستخدَم لتوقيع رمز الشفافية، يمكنك إضافة ما يلي في مجموعة bundle.

// In your app module's build.gradle file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

// In your app module's build.gradle.kts file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

يجب أن يكون المفتاح المستخدَم هو المفتاح الذي ستستخدمه فقط لشفافية الرموز، وليس مفتاح توقيع التطبيق الذي تستخدمه ميزة "توقيع التطبيق" من Play.

استخدام bundletool في سطر الأوامر

تتطلّب ميزة توفير شفافية الرموز الإصدار 1.7.0 أو إصدارًا أحدث من bundletool ويمكنك تنزيله من GitHub.

يمكنك تنفيذ الأمر التالي لإضافة شفافية الرمز إلى "مجموعة حزمات تطبيق Android". يجب أن يكون المفتاح المستخدَم هو المفتاح الذي ستستخدمه فقط لشفافية الرموز، وليس مفتاح توقيع التطبيق الذي تستخدمه ميزة "توقيع التطبيق" من Play.

bundletool add-transparency \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --ks=/MyApp/keystore.jks \
  --ks-pass=file:/MyApp/keystore.pwd \
  --ks-key-alias=MyKeyAlias \
  --key-pass=file:/MyApp/key.pwd

بدلاً من ذلك، إذا كنت تريد استخدام أدوات التوقيع الخاصة بك، يمكنك استخدام bundletool لإنشاء ملف شفافية الرمز غير الموقَّع، وتوقيعه في بيئة منفصلة وإدخال التوقيع في الحزمة:

# Generate code transparency file
bundletool add-transparency \
  --mode=generate_code_transparency_file \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/code_transparency_file.jwt \
  --transparency-key-certificate=/MyApp/transparency.cert

# Add code transparency signature to the bundle
bundletool add-transparency \
  --mode=inject_signature \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert \
  --transparency-signature=/MyApp/signature

التحقّق من شفافية رمز أحد التطبيقات

هناك طرق مختلفة للتحقق من الرمز في ما يتعلق بملف شفافية الرمز، وذلك بناءً على ما إذا كان لديك حِزم APK مثبَّتة على جهاز Android أو تم تنزيلها محليًا على جهاز الكمبيوتر.

استخدام Bundletool للتحقق من حِزمة تطبيق أو مجموعة ملفات APK

يمكنك استخدام bundletool للتحقق من شفافية الرمز في حِزمة تطبيق أو مجموعة APK. يمكنك استخدام الأمر check-transparency لطباعة الملف المرجعي للشهادة العلنية:

# For checking a bundle:
bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab

No APK present. APK signature was not checked.
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.


# For checking a ZIP containing app's APK splits:
bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

يمكنك اختياريًا تحديد الشهادة العلنية التي تريد التحقّق من توافقها مع الحزمة أو حزمة APK، حتى لا تضطر إلى مقارنة قيم التجزئات يدويًا:

bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert

No APK present. APK signature was not checked.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.


bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.

استخدام Bundletool للتحقق من تثبيت تطبيق على الجهاز

للتحقّق من تطبيق تم تثبيته على جهاز Android، تأكَّد من أنّ الجهاز متصل بالكمبيوتر عبر ADB وأصدر الأمر التالي:

bundletool check-transparency \
  --mode=connected_device \
  --package-name="com.my.app"

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

يمكن أيضًا لميزة "التحقق من شفافية الأجهزة المتصلة" تأكيد التوقيع مقابل مفتاح عام تحدِّده اختياريًا:

bundletool check-transparency \
  --mode=connected-device \
  --package-name="com.my.app" \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.