شفافیت کد برای بسته‌های برنامه

شفافیت کد یک مکانیزم امضا و تأیید کد اختیاری برای برنامه‌هایی است که با Android App Bundle منتشر می‌شوند. از یک کلید امضای شفافیت کد استفاده می کند که تنها توسط توسعه دهنده برنامه نگهداری می شود.

شفافیت کد مستقل از طرح امضای مورد استفاده برای بسته‌های برنامه و فایل‌های APK است. کلید شفافیت کد جدا و متفاوت از کلید امضای برنامه است که در زیرساخت امن Google هنگام استفاده از Play App Signing ذخیره می شود.

شفافیت کد چگونه کار می کند

این فرآیند با گنجاندن یک فایل شفاف کد در بسته پس از ساخته شدن، اما قبل از آپلود آن در Play Console برای توزیع کار می کند.

فایل شفافیت کد یک رمز وب JSON (JWT) است که حاوی لیستی از فایل‌های DEX و کتابخانه‌های بومی موجود در بسته و هش‌های آن‌ها است. سپس با استفاده از کلید شفافیت کد که فقط در اختیار توسعه دهنده است امضا می شود.

Code transparency diagram

این فایل شفاف کد به APK پایه ساخته شده از بسته برنامه (به ویژه در تقسیم اصلی ماژول پایه) منتشر می شود. سپس می توان تأیید کرد که:

  • همه فایل‌های DEX و کد بومی موجود در فایل‌های APK دارای هش‌های منطبق در فایل شفاف‌سازی کد هستند.
  • جزء کلید عمومی کلید امضای شفافیت کد در برنامه با کلید عمومی برنامه‌نویس مطابقت دارد (که باید توسط برنامه‌نویس از طریق یک کانال جداگانه و ایمن ارائه شود).

با هم، این اطلاعات تأیید می‌کند که کد موجود در فایل‌های APK با آنچه توسعه‌دهنده قصد داشته مطابقت دارد و اینکه تغییری در آن صورت نگرفته است.

فایل شفافیت کد منابع، دارایی‌ها، مانیفست Android یا هر فایل دیگری را که فایل‌های DEX یا کتابخانه‌های بومی موجود در پوشه lib/ نیستند، تأیید نمی‌کند.

راستی‌آزمایی شفافیت کد صرفاً برای بازرسی توسط توسعه‌دهندگان و کاربران نهایی استفاده می‌شود که می‌خواهند مطمئن شوند کدی که اجرا می‌کنند با کدی که در ابتدا توسط توسعه‌دهنده برنامه ساخته و امضا شده است مطابقت دارد.

محدودیت های شناخته شده

شرایط خاصی وجود دارد که نمی توان از شفافیت کد استفاده کرد:

  • برنامه هایی که ویژگی sharedUserId را در مانیفست مشخص می کنند. چنین برنامه‌هایی ممکن است فرآیند خود را با سایر برنامه‌ها به اشتراک بگذارند، که تضمین‌کردن درباره کدی را که اجرا می‌کنند دشوار می‌کند.
  • برنامه‌هایی که از محافظت در برابر دستکاری یا هر سرویس دیگری استفاده می‌کنند که پس از ایجاد فایل شفافیت کد، کد را تغییر می‌دهد، باعث می‌شود تأیید شفافیت کد با شکست مواجه شود.
  • برنامه‌هایی که از Multidex قدیمی در سطوح API زیر 21 (اندروید 5.0) استفاده می‌کنند و از ماژول‌های ویژگی استفاده می‌کنند. وقتی برنامه توسط Google Play روی دستگاه‌های Android نسخه ۵٫۰ و بالاتر نصب شود، شفافیت کد به کار خود ادامه می‌دهد. شفافیت کد در نسخه‌های قدیمی‌تر سیستم عامل غیرفعال می‌شود.

نحوه اضافه کردن شفافیت کد

قبل از اینکه بتوانید شفافیت کد را به برنامه خود اضافه کنید، مطمئن شوید که یک جفت کلید خصوصی و عمومی دارید که می توانید برای امضای شفافیت کد استفاده کنید. این باید یک کلید منحصربه‌فرد باشد که با کلید امضای برنامه که برای Play App Signing استفاده می‌کنید متفاوت باشد، و باید به‌طور ایمن نگهداری شود و هرگز خارج از سازمانتان به اشتراک گذاشته نشود.

اگر کلید ندارید، می‌توانید دستورالعمل‌های موجود در راهنمای برنامه خود را امضا کنید تا کلیدی را در دستگاه خود ایجاد کنید. شفافیت کد از یک فایل ذخیره کلید استاندارد استفاده می کند، بنابراین اگرچه راهنما برای امضای برنامه است، فرآیند تولید کلید یکسان است.

با استفاده از پلاگین اندروید Gradle

پشتیبانی از شفافیت کد به پلاگین Android Gradle نسخه 7.1.0-alpha03 یا جدیدتر نیاز دارد. برای پیکربندی کلید مورد استفاده برای امضای شفافیت کد، موارد زیر را در بلوک 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 App Signing استفاده می‌شود.

استفاده از bundletool در خط فرمان

پشتیبانی از شفافیت کد به bundletool نسخه 1.7.0 یا جدیدتر نیاز دارد که می توانید آن را از GitHub دانلود کنید .

دستور زیر را اجرا کنید تا شفافیت کد را به یک بسته نرم افزاری Android اضافه کنید. کلید مورد استفاده باید کلیدی باشد که فقط برای شفافیت کد از آن استفاده کنید، نه کلید امضای برنامه که توسط Play App Signing استفاده می‌شود.

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 برای بررسی برنامه نصب شده روی دستگاه

برای بررسی برنامه ای که روی دستگاه اندرویدی نصب شده است، مطمئن شوید که دستگاه از طریق 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.