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

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

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

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

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

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

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

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

وتتأكد هذه المعلومات معًا من أن الرمز الذي تم تضمينه في حزم APK تتطابق مع ما قصده مطوّر البرامج، وأنه لم يتم تعديله.

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

ملاحظة مهمة: لا يتحقّق نظام التشغيل Android من ملفات شفافية الرموز عند التثبيت. والاعتماد على مخططات توقيع حِزم APK للتحقق من أي حِزم APK مثبَّتة.

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

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

هناك حالات معيّنة يتعذّر فيها استخدام شفافية الرمز:

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

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

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

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

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

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

Groovy

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

Kotlin

// 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 أو الإصدارات الأحدث من أداة packagetool، والذي يجب تنزيلها من 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

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

# 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

ملاحظة: تؤدي إضافة ملف شفافية الترميز إلى الحزمة إلى إلغاء صلاحية أي بيانات حالية. التوقيعات. الحِزمة الناتجة (my_app_with_transparency.aab في الفترة السابقة مثال) باستخدام مفتاح التحميل (على سبيل المثال، استخدام jarsigner) قبل تحميله على Play Console لتوزيعه

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

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

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

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

يمكنك استخدام أداة packagetool للتحقّق من شفافية الرموز في حِزمة تطبيق أو حِزمة 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.