مهاجرت از SafetyNet Attestation API

اگر قبلاً با استفاده از یک سرور قابل اعتماد پاسخ‌ها را تأیید می‌کنید، انتقال از SafetyNet Attestation API به Play Integrity API ساده است. Play Integrity API همچنین می‌تواند به‌عنوان جایگزینی برای بررسی‌های مجوز برنامه که مستقیماً با برنامه Play Store از طریق AIDL انجام می‌شود، مانند مواردی که توسط Licensing Verification Library (LVL) انجام می‌شود، استفاده شود. بیشتر تغییرات مورد نیاز در سمت سرور قابل اعتماد خواهد بود، که نیاز به خواندن و تجزیه و تحلیل توکن پاسخ یکپارچگی Play دارد. توجه داشته باشید که در حین انتقال، هم برنامه و هم سرور باید از هر دو API به طور همزمان پشتیبانی کنند تا از کلاینت های قدیمی که هنوز به روز نشده اند پشتیبانی کنند.

توجه: برای SafetyNet Attestation API، امکان انجام اعتبارسنجی پاسخ به طور مستقیم در دستگاه وجود داشت، اگرچه توصیه نمی شد . برای استفاده از Play Integrity API جدید، به یک مؤلفه سرور قابل اعتماد نیاز دارید که رمزگشایی و تأیید رمز پاسخ را انجام دهد. ما قویاً از نگه داشتن کلیدهای خود مدیریت Play Integrity API در دستگاه خودداری می کنیم، زیرا این امر باعث می شود مهاجم جعل پاسخ را بی اهمیت جلوه دهد.

اگر به برنامه شما محدودیت های سهمیه افزایش یافته برای SafetyNet Attestation API داده شده است، باید سطح استفاده اختصاص داده شده برای Play Integrity API را بررسی کنید و در صورت نیاز درخواست کنید که به سطح بالاتر بروید.

تغییرات زیر برای پشتیبانی از Play Integrity API ضروری است:

کلاینت اندروید:

• اطمینان حاصل کنید که کد در حال ارسال nonce با فرمت صحیح به سازنده IntegrityTokenRequest است:
  • String (به جای آرایه بایت)
  • آدرس اینترنتی امن
  • کدگذاری شده به صورت Base64 و بدون بسته بندی
  • حداقل 16 کاراکتر
  • حداکثر 500 کاراکتر
• منطق امتحان مجدد را مرور کنید و مطمئن شوید که برنامه به درستی خطاها را مدیریت می کند.
• اطمینان حاصل کنید که داده‌های پاسخ ارسال شده به سرور مورد اعتماد امکان تمایز بین پاسخ‌های SafetyNet Attestation API و پاسخ‌های Play Integrity API را می‌دهد.

سرور قابل اعتماد:

• منطق تولید nonce را مرور کنید و مطمئن شوید که الزامات Play Integrity API را برآورده می‌کند.
• مطمئن شوید که کد سرور می‌تواند بین پاسخ‌های SafetyNet Attestation API و Play Integrity API تمایز قائل شود. مطمئن شوید که کد آن پاسخ ها را به درستی تجزیه و تایید می کند.
• منطق را برای اعتبارسنجی و تجزیه پاسخ‌های Play Integrity API اضافه کنید.
• از آنجایی که پاسخ جدید Play Integrity API جزئیات بیشتری را ارائه می‌کند، ممکن است لازم باشد منطق تصمیم‌گیری و داده‌های بازخوردی که به دستگاه‌های سرویس گیرنده ارسال می‌شوند، تقویت شود. برای اطلاعات بیشتر، بخش API Response Mapping را در این موضوع ببینید.

بدون رمزگذاری

یک nonce مرتبط با یکپارچگی باید به‌عنوان یک String کدگذاری‌شده، URL ایمن و غیر پیچیده شده با Base64 به Play Integrity API ارسال شود. این قالب با SafetyNet Attestation API که byte[] نیاز دارد، متفاوت است.

• "URL-safe" به معنای استفاده از نوع "URL and filename-safe" در Base64 است (به بخش 5 RFC 4648 مراجعه کنید)، که در آن "-" و "_" به جای "+" و "/" استفاده می‌شوند. برای اطلاعات بیشتر در مورد رمزگذاری Base64، RFC 4648 را ببینید.
• "no-wrap" به معنای حذف تمام پایان دهنده های خط است. این بدان معنی است که خروجی یک خط طولانی است.

.setNonce(Base64.encodeToString(NONCE_BYTES,
        Base64.URL_SAFE | Base64.NO_WRAP))

علاوه بر این، مطمئن شوید که نسل nonce با دستورالعمل‌های Play Integrity API همسو باشد.

نقشه برداری پاسخ API

جدول زیر فیلدهای SafetyNet Attestation API را با معادل‌های Play Integrity API آنها ترسیم می‌کند.

SafetyNet Attestation API		Play Integrity API	یادداشت ها
timestampMs		requestDetails.timestampMillis
nonce		requestDetails.nonce
apkPackageName		appIntegrity.packageName
apkCertificateDigestSha256		appIntegrity.certificateSha256Digest	مطمئن شوید که appRecognitionVerdict روی PLAY_RECOGNIZED تنظیم شده است
ctsProfileMatch		در deviceIntegrity.deviceRecognitionVerdict ترکیب شده است
basicIntegrity		در deviceIntegrity.deviceRecognitionVerdict ترکیب شده است
evaluationType		در deviceIntegrity.deviceRecognitionVerdict ترکیب شده است
advice		Not available
error		Not available	لیست برچسب های یکپارچگی دستگاه خالی خواهد بود.

نگاشت حکم یکپارچگی دستگاه

SafetyNet Attestation API			Play Integrity API
ctsProfileMatch	basicIntegrity	evaluationType	deviceRecognitionVerdict
FALSE	FALSE		بدون برچسب
FALSE	TRUE		MEETS_BASIC_INTEGRITY
TRUE	FALSE		بدون برچسب
TRUE	TRUE	BASIC	MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY
TRUE	TRUE	HARDWARE_BACKED	MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY

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

بازی Integrity API Retry Logic

در صورت وجود کدهای خطا، برنامه باید دوباره تماس‌های API را امتحان کند. مطمئن شوید که همه کدهای خطا را بازبینی کرده‌اید و مطمئن شوید که برنامه در صورت لزوم با عقب‌نشینی نمایی دوباره امتحان می‌کند. لطفاً مطمئن شوید که حداقل تأخیر حداقل 5 ثانیه است که به صورت تصاعدی افزایش می یابد (5 ثانیه، 10 ثانیه، 20 ثانیه، 40 ثانیه و غیره)، تا زمان کافی برای ارزیابی دستگاه و یکپارچگی برنامه در اختیار API قرار گیرد.

جایگزینی اختیاری API مجوز برنامه

اگر از App Licensing API استفاده می‌کنید، می‌توانید به‌صورت اختیاری برای استفاده از Play Integrity API مهاجرت کنید، زیرا یک نشانه Play Integrity API شامل اطلاعات مجوز برنامه است. همانند انتقال API SafetyNet Attestation، باید انتظار داشته باشید که تعدادی از دستگاه ها نسخه قدیمی برنامه را حفظ کنند. سرور مورد اعتماد شما باید بتواند هر دو پاسخ API مجوز برنامه و Play Integrity API را پردازش کند.

پاسخ‌ها را تا پایان کامل دریافت کنید

اگر هنوز به Play Integrity API مهاجرت نکرده‌اید یا تأییدیه SafetyNet را تا مهلت انتقال (31 ژانویه 2024) حذف نکرده‌اید، می‌توانید این فرم را برای درخواست تمدید تکمیل کنید. اگر برای تمدید تأیید شود، برنامه شما تا پایان مهلت نهایی (31 ژانویه 2025) از SafetyNet Attestation به دریافت پاسخ‌ها ادامه خواهد داد.