MASTG-KNOW-0035: Google Play Integrity API

Google has launched the Google Play Integrity API to improve the security and integrity of apps and games on Android starting with Android 4.4 (level 19). The previous official API, SafetyNet, did not cover all the security needs that Google wanted for the platform, so Play Integrity was developed with the basic functions of the previous API and integrated additional features. This change aims to protect users from dangerous and fraudulent interactions.

Google Play Integrity offers the following safeguards:

  • Verification of genuine Android device: It verifies that the application is running on a legitimate Android device.
  • User license validation: It indicates whether the application or game was installed or purchased through the Google Play Store.
  • Unmodified binary verification: It determines whether the application is interacting with the original binary recognized by Google Play.

The API provides four macro categories of information to help the security team make a decision. These categories include:

  1. Request Details: In this section, details are obtained about the app package that requested the integrity check, including its format (e.g., com.example.myapp), a base64-encoded ID provided by the developer to link the request with the integrity certificate, and the execution time of the request in milliseconds.

  2. App Integrity: This section provides information about the integrity of the app, including the result of the verification (denominated verdict), which indicates whether the app's installation source is trusted (via Play Store) or unknown/suspicious. If the installation source is considered secure, the app version will also be displayed.

  3. Account Details: This category provides information about the app licensing status. The result can be LICENSED, indicating that the user purchased or installed the app on the Google Play Store; UNLICENSED, meaning that the user does not own the app or did not acquire it through the Google Play Store; or UNEVALUATED, which means that the licensing details could not be evaluated because a necessary requirement is missing, that is, the device may not be trustworthy enough or the installed app version is not recognized by the Google Play Store.

  4. Device Integrity: This section presents information that verifies the authenticity of the Android environment in which the app is running.

  5. MEETS_DEVICE_INTEGRITY: The app is on an Android device with Google Play Services, passing system integrity checks and compatibility requirements.

  6. MEETS_BASIC_INTEGRITY: The app is on a device that may not be approved to run Google Play Services but passes basic integrity checks, possibly due to an unrecognized Android version, unlocked bootloader, or lack of manufacturer certification.
  7. MEETS_STRONG_INTEGRITY: The app is on a device with Google Play Services, ensuring robust system integrity with features like hardware-protected boot.
  8. MEETS_VIRTUAL_INTEGRITY: The app runs in an emulator with Google Play Services, passing system integrity checks and meeting Android compatibility requirements.

API Errors:

The API can return local errors such as APP_NOT_INSTALLED and APP_UID_MISMATCH, which can indicate a fraud attempt or attack. In addition, outdated Google Play Services or Play Store can also cause errors, and it is important to check these situations to ensure proper integrity verification functionality and to ensure the environment is not intentionally set up for an attack. You can find more details on the official page.

Best practices:

  1. Use Play Integrity as part of a broader security strategy. Complement it with additional security measures such as input data validation, user authentication, and anti-fraud protection.

  2. Minimize queries to the Play Protect API to reduce device resource impact. For example, employ the API only for essential device integrity verifications.

  3. Include a NONCE with integrity verification requests. This random value, generated by the app or server, helps the verification server confirm that responses match the original requests without third-party tampering.

Limitations: The default daily limit for Google Play Services Integrity Verification API requests is 10,000 requests per day. Applications needing more must contact Google to request an increased limit.

Example Request:

{
   "requestDetails": {
     "requestPackageName": "com.example.your.package",
     "timestampMillis": "1666025823025",
     "nonce": "kx7QEkGebwQfBalJ4...Xwjhak7o3uHDDQTTqI"
   },
   "appIntegrity": {
     "appRecognitionVerdict": "UNRECOGNIZED_VERSION",
     "packageName": "com.example.your.package",
     "certificateSha256Digest": [
       "vNsB0...ww1U"
     ],
     "versionCode": "1"
   },
   "deviceIntegrity": {
     "deviceRecognitionVerdict": [
       "MEETS_DEVICE_INTEGRITY"
     ]
   },
   "accountDetails": {
     "appLicensingVerdict": "UNEVALUATED"
   }
 }