Oceny integralności

Na tej stronie opisujemy, jak interpretować zwrócone wyniki integralności i jak pracować z nimi. Niezależnie od tego, czy wykonujesz standardowe, czy klasyczne żądanie do interfejsu API, ocena integralności jest zwracana w tym samym formacie z podobną treścią. Ocena integralności przekazuje informacje o prawidłowości urządzeń, aplikacji i kont. Serwer aplikacji może użyć otrzymanego ładunku w odszyfrowanej, zweryfikowanej ocenie, aby określić, jak najlepiej wykonać określone działanie lub żądanie w aplikacji.

Format zwróconej oceny integralności

Ładunek ma postać zwykłego tekstu JSON i zawiera sygnały integralności oraz informacje podane przez dewelopera.

Ogólna struktura ładunku wygląda tak:

{
  requestDetails: { ... }
  appIntegrity: { ... }
  deviceIntegrity: { ... }
  accountDetails: { ... }
  environmentDetails: { ... }
}

Przed sprawdzeniem każdej oceny integralności musisz najpierw sprawdzić, czy wartości w polu requestDetails są zgodne z wartościami w pierwotnym żądaniu. W sekcjach poniżej znajdziesz bardziej szczegółowe informacje o każdym polu.

Pole szczegółów żądania

Pole requestDetails zawiera informacje o żądaniu, w tym dane podane przez dewelopera w polu requestHash w przypadku żądań standardowych i nonce w przypadku żądań klasycznych.

W przypadku standardowych żądań do interfejsu API:

requestDetails: {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  requestPackageName: "com.package.name"
  // Request hash provided by the developer.
  requestHash: "aGVsbG8gd29scmQgdGhlcmU"
  // The timestamp in milliseconds when the integrity token
  // was prepared (computed on the server).
  timestampMillis: "1675655009345"
}

Wartości te powinny być zgodne z wartościami z pierwotnego żądania. Dlatego sprawdź część ładunku JSON requestDetails, upewniając się, że requestPackageName i requestHash są zgodne z tym, co wysłano w pierwotnym żądaniu, jak pokazano w tym fragmencie kodu:

val requestDetails = JSONObject(payload).getJSONObject("requestDetails")
val requestPackageName = requestDetails.getString("requestPackageName")
val requestHash = requestDetails.getString("requestHash")
val timestampMillis = requestDetails.getLong("timestampMillis")
val currentTimestampMillis = ...

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request
    || !requestHash.equals(expectedRequestHash)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

RequestDetails requestDetails =
    decodeIntegrityTokenResponse
    .getTokenPayloadExternal()
    .getRequestDetails();
String requestPackageName = requestDetails.getRequestPackageName();
String requestHash = requestDetails.getRequestHash();
long timestampMillis = requestDetails.getTimestampMillis();
long currentTimestampMillis = ...;

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request.
    || !requestHash.equals(expectedRequestHash)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

W przypadku klasycznych żądań do interfejsu API:

requestDetails: {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the
  // request.
  requestPackageName: "com.package.name"
  // base64-encoded URL-safe no-wrap nonce provided by the developer.
  nonce: "aGVsbG8gd29scmQgdGhlcmU"
  // The timestamp in milliseconds when the request was made
  // (computed on the server).
  timestampMillis: "1617893780"
}

Wartości te powinny być zgodne z wartościami z pierwotnego żądania. Dlatego sprawdź część ładunku JSON requestDetails, upewniając się, że requestPackageName i nonce są zgodne z treściami wysłanymi w pierwotnym żądaniu, jak pokazano w tym fragmencie kodu:

val requestDetails = JSONObject(payload).getJSONObject("requestDetails")
val requestPackageName = requestDetails.getString("requestPackageName")
val nonce = requestDetails.getString("nonce")
val timestampMillis = requestDetails.getLong("timestampMillis")
val currentTimestampMillis = ...

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request. See 'Generate a nonce'
        // section of the doc on how to store/compute the expected nonce.
    || !nonce.equals(expectedNonce)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

JSONObject requestDetails =
    new JSONObject(payload).getJSONObject("requestDetails");
String requestPackageName = requestDetails.getString("requestPackageName");
String nonce = requestDetails.getString("nonce");
long timestampMillis = requestDetails.getLong("timestampMillis");
long currentTimestampMillis = ...;

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request. See 'Generate a nonce'
        // section of the doc on how to store/compute the expected nonce.
    || !nonce.equals(expectedNonce)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

Pole integralności aplikacji

Pole appIntegrity zawiera informacje dotyczące pakietu.

appIntegrity: {
  // PLAY_RECOGNIZED, UNRECOGNIZED_VERSION, or UNEVALUATED.
  appRecognitionVerdict: "PLAY_RECOGNIZED"
  // The package name of the app.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  packageName: "com.package.name"
  // The sha256 digest of app certificates (base64-encoded URL-safe).
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  certificateSha256Digest: ["6a6a1474b5cbbb2b1aa57e0bc3"]
  // The version of the app.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  versionCode: "42"
}

appRecognitionVerdict może mieć te wartości:

PLAY_RECOGNIZED

Aplikacja i certyfikat odpowiadają wersjom rozpowszechnianym w Google Play.

UNRECOGNIZED_VERSION

Nazwa certyfikatu lub pakietu nie zgadza się z rekordami Google Play.

UNEVALUATED

Integralność aplikacji nie została oceniona. Pominięto niezbędny wymóg, np. urządzenie nie było wystarczająco godne zaufania.

Aby upewnić się, że token został wygenerowany przez utworzoną przez Ciebie aplikację, sprawdź, czy integralność aplikacji jest zgodna z oczekiwaniami, tak jak w tym fragmencie kodu:

val appIntegrity = JSONObject(payload).getJSONObject("appIntegrity")
val appRecognitionVerdict = appIntegrity.getString("appRecognitionVerdict")

if (appRecognitionVerdict == "PLAY_RECOGNIZED") {
    // Looks good!
}

JSONObject appIntegrity =
    new JSONObject(payload).getJSONObject("appIntegrity");
String appRecognitionVerdict =
    appIntegrity.getString("appRecognitionVerdict");

if (appRecognitionVerdict.equals("PLAY_RECOGNIZED")) {
    // Looks good!
}

Możesz też ręcznie sprawdzić nazwę pakietu i wersję aplikacji oraz certyfikaty aplikacji.

pole integralności urządzenia

Pole deviceIntegrity może zawierać 1 wartość deviceRecognitionVerdict, która może zawierać co najmniej 1 etykietę wskazującą, jak urządzenie może egzekwować integralność aplikacji. Jeśli urządzenie nie spełnia kryteriów żadnej etykiety, pole deviceIntegrity jest puste.

deviceIntegrity: {
  // "MEETS_DEVICE_INTEGRITY" is one of several possible values.
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
}

Domyślnie deviceRecognitionVerdict może zawierać:

MEETS_DEVICE_INTEGRITY

Aplikacja działa na urządzeniu z Androidem i Usługami Google Play. Urządzenie przeszło testy integralności systemu i jest zgodne z Androidem.

Pusta (pusta wartość)

Aplikacja działa na urządzeniu, które wykazuje oznaki ataku (np. zaatakowania interfejsu API) lub naruszenia systemu (np. ma dostęp do roota) albo nie działa na urządzeniu fizycznym (np. emulator, który nie przechodzi testów integralności w Google Play).

Aby upewnić się, że token pochodzi z zaufanego urządzenia, sprawdź, czy deviceRecognitionVerdict działa zgodnie z oczekiwaniami, co pokazuje ten fragment kodu:

val deviceIntegrity =
    JSONObject(payload).getJSONObject("deviceIntegrity")
val deviceRecognitionVerdict =
    if (deviceIntegrity.has("deviceRecognitionVerdict")) {
        deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString()
    } else {
        ""
    }

if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) {
    // Looks good!
}

JSONObject deviceIntegrity =
    new JSONObject(payload).getJSONObject("deviceIntegrity");
String deviceRecognitionVerdict =
    deviceIntegrity.has("deviceRecognitionVerdict")
    ? deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString()
    : "";

if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) {
    // Looks good!
}

Jeśli masz problemy z integracją integralności urządzenia testowego na urządzeniu testowym, upewnij się, że jest zainstalowany fabryczny ROM (np. przez zresetowanie urządzenia) oraz że program rozruchowy jest zablokowany. Możesz też tworzyć testy interfejsu Play Integrity API w Konsoli Play.

Etykiety urządzeń warunkowych

Jeśli Twoja aplikacja jest publikowana w Grach Google Play na PC, deviceRecognitionVerdict może też zawierać tę etykietę:

MEETS_VIRTUAL_INTEGRITY

Aplikacja działa w obsługiwanym przez Androida emulatorze z Usługami Google Play. Emulator przechodzi testy integralności systemu i spełnia podstawowe wymagania dotyczące zgodności z Androidem.

Opcjonalne informacje o urządzeniu

Jeśli w ramach oceny integralności zgodzisz się na otrzymywanie dodatkowych etykiet, panel deviceRecognitionVerdict może zawierać te dodatkowe etykiety:

MEETS_BASIC_INTEGRITY

Aplikacja działa na urządzeniu, które przechodzi podstawowe testy integralności systemu. Urządzenie może być niezgodne z Androidem i może nie zostać zatwierdzone do uruchamiania Usług Google Play. Na przykład może korzystać z nierozpoznanej wersji Androida, mieć odblokowany program rozruchowy lub nie mieć certyfikatu producenta.

MEETS_STRONG_INTEGRITY

Aplikacja działa na urządzeniu z Androidem i Usługami Google Play. Gwarancja integralności systemu jest wysoka – np. w formie sprzętowego potwierdzenia integralności podczas uruchamiania. Urządzenie przeszło testy integralności systemu i jest zgodne z Androidem.

1 urządzenie zwróci wiele etykiet urządzenia w ramach oceny integralności, jeśli wszystkie kryteria etykiety zostaną spełnione.

Ostatnia aktywność na urządzeniach (beta)

Możesz też wyrazić zgodę na ostatnią aktywność na urządzeniu, która informuje, ile razy w ciągu ostatniej godziny aplikacja zażądała tokena integralności na konkretnym urządzeniu. Korzystając z ostatniej aktywności na urządzeniu, możesz chronić swoją aplikację przed nieoczekiwanymi, hiperaktywnymi urządzeniami, które mogą wskazywać na aktywny atak. Możesz określić poziom zaufania dla każdego poziomu ostatniej aktywności na urządzeniu na podstawie tego, ile razy Twoja aplikacja zainstalowana na typowych urządzeniach będzie prosić o token integralności w każdej godzinie.

Jeśli wyrazisz zgodę na otrzymywanie recentDeviceActivity, pole deviceIntegrity będzie miało 2 wartości:

deviceIntegrity: {
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
  recentDeviceActivity: {
    // "LEVEL_2" is one of several possible values.
    deviceActivityLevel: "LEVEL_2"
  }
}

Definicje deviceActivityLevel różnią się w zależności od trybów i mogą mieć jedną z tych wartości:

Pole szczegółów konta

Pole accountDetails zawiera pojedynczą wartość appLicensingVerdict, która reprezentuje stan licencji na aplikację w Google Play dla konta użytkownika zalogowanego na urządzeniu. Jeśli konto użytkownika ma licencję na aplikację, oznacza to, że pobrał ją z Google Play lub kupił w Google Play.

accountDetails: {
  // This field can be LICENSED, UNLICENSED, or UNEVALUATED.
  appLicensingVerdict: "LICENSED"
}

appLicensingVerdict może mieć jedną z tych wartości:

LICENSED

Użytkownik ma uprawnienia do korzystania z aplikacji. To znaczy, że zainstalował ją z Google Play lub kupił w Google Play.

UNLICENSED

Użytkownik nie ma uprawnień do korzystania z aplikacji. Może się tak zdarzyć, jeśli np. zainstaluje ją z innego urządzenia lub nie pozyska jej z Google Play. Aby rozwiązać ten problem, możesz pokazać użytkownikom okno GET_LICENSED.

UNEVALUATED

Szczegóły dotyczące licencji nie zostały określone, ponieważ pominięto niezbędny wymóg.

Może się tak zdarzyć z kilku powodów. Oto niektóre z nich:

• Urządzenie nie jest wystarczająco zaufane.
• Google Play nie rozpoznaje wersji aplikacji zainstalowanej na urządzeniu.
• użytkownik nie jest zalogowany w Google Play,

Aby sprawdzić, czy użytkownik ma uprawnienia do korzystania z Twojej aplikacji, sprawdź, czy właściwość appLicensingVerdict jest zgodna z oczekiwaniami, jak pokazano w tym fragmencie kodu:

val accountDetails = JSONObject(payload).getJSONObject("accountDetails")
val appLicensingVerdict = accountDetails.getString("appLicensingVerdict")

if (appLicensingVerdict == "LICENSED") {
    // Looks good!
}

JSONObject accountDetails =
    new JSONObject(payload).getJSONObject("accountDetails");
String appLicensingVerdict = accountDetails.getString("appLicensingVerdict");

if (appLicensingVerdict.equals("LICENSED")) {
    // Looks good!
}

Pole szczegółów środowiska

Możesz też wyrazić zgodę na dodatkowe sygnały dotyczące środowiska. Ryzyko związane z dostępem do aplikacji informuje aplikację, czy są uruchomione inne aplikacje, które można wykorzystać do przechwytywania ekranu, wyświetlania nakładek lub sterowania urządzeniem. Ocena Play Protect informuje, czy usługa Google Play Protect jest włączona na urządzeniu i czy wykryła znane złośliwe oprogramowanie.

Jeśli w Konsoli Google Play masz włączoną ocenę ryzyka dostępu aplikacji lub Play Protect, odpowiedź interfejsu API będzie zawierała pole environmentDetails. Pole environmentDetails może zawierać 2 wartości: appAccessRiskVerdict i playProtectVerdict.

Ocena ryzyka dostępu aplikacji (beta)

Po włączeniu pole environmentDetails w ładunku interfejsu Play Integrity API będzie zawierać nową ocenę ryzyka dostępu do aplikacji.

{
  requestDetails: { ... }
  appIntegrity: { ... }
  deviceIntegrity: { ... }
  accountDetails: { ... }
  environmentDetails: {
      appAccessRiskVerdict: {
          // This field contains one or more responses, for example the following.
          appsDetected: ["KNOWN_INSTALLED", "UNKNOWN_INSTALLED", "UNKNOWN_CAPTURING"]
      }
 }
}

Jeśli oceniono ryzyko związane z dostępem do aplikacji, appAccessRiskVerdict zawiera pole appsDetected z co najmniej 1 odpowiedzią. Te odpowiedzi trafiają do jednej z 2 grup w zależności od źródła instalacji wykrytych aplikacji:

• Aplikacje z Google Play lub aplikacje systemowe: aplikacje instalowane z Google Play lub wstępnie wczytywane przez producenta urządzenia na partycji systemowej urządzenia (identyfikowanej za pomocą elementu FLAG_SYSTEM). Odpowiedzi na takie aplikacje są poprzedzone znakiem KNOWN_.

• Inne aplikacje: aplikacje niezainstalowane z Google Play. Nie dotyczy to aplikacji wstępnie wczytanych na partycji systemowej przez producenta urządzenia. Odpowiedzi dotyczące takich aplikacji mają przedrostek UNKNOWN_.

Mogą zostać zwrócone te odpowiedzi:

KNOWN_INSTALLED, UNKNOWN_INSTALLED

Masz zainstalowane aplikacje, które pasują do odpowiedniego źródła instalacji.

KNOWN_CAPTURING, UNKNOWN_CAPTURING

Masz uruchomione aplikacje z włączonymi uprawnieniami, których można użyć do wyświetlania ekranu, gdy aplikacja jest uruchomiona. Nie dotyczy to zweryfikowanych usług ułatwień dostępu znanych Google Play działających na urządzeniu.

KNOWN_CONTROLLING, UNKNOWN_CONTROLLING

Istnieją uruchomione aplikacje z włączonymi uprawnieniami. Można ich używać do sterowania urządzeniem i bezpośredniego sterowania danymi wejściowymi oraz danych wejściowych i wyjściowych w aplikacji. Nie obejmuje to żadnych zweryfikowanych usług ułatwień dostępu znanych Google Play działających na urządzeniu.

KNOWN_OVERLAYS, UNKNOWN_OVERLAYS

Masz uruchomione aplikacje z włączonymi uprawnieniami, które można wykorzystać do wyświetlania nakładek w Twojej aplikacji. Nie dotyczy to zweryfikowanych usług ułatwień dostępu znanych Google Play i działających na urządzeniu.

EMPTY (pusta wartość)

Jeśli pominięto niezbędny wymóg, ryzyko dostępu do aplikacji nie jest oceniane. W tym przypadku pole appAccessRiskVerdict jest puste. Może się tak zdarzyć z kilku powodów, między innymi:

• Urządzenie nie jest wystarczająco zaufane.
• nie jest to telefon, tablet ani urządzenie składane;
• Na urządzeniu nie jest zainstalowany Android 6 (poziom interfejsu API 23) lub nowszy.
• Google Play nie rozpoznaje wersji aplikacji zainstalowanej na urządzeniu.
• Wersja Sklepu Google Play na urządzeniu jest nieaktualna.
• Tylko gry: konto użytkownika nie ma licencji na daną grę w Google Play.

Ryzyko związane z dostępem do aplikacji automatycznie wyklucza zweryfikowane usługi ułatwień dostępu, które zostały poddane ulepszonej weryfikacji ułatwień dostępu w Google Play (zainstalowanej z dowolnego sklepu z aplikacjami na urządzeniu). „Wykluczone” oznacza, że zweryfikowane usługi ułatwień dostępu działające na urządzeniu nie zwracają w ocenie ryzyka związanego z dostępem aplikacji do przechwytywania, kontrolowania ani nakładania się odpowiedzi. Aby poprosić o ulepszone sprawdzenie ułatwień dostępu w Google Play, opublikuj ją w Google Play, upewniając się, że w pliku manifestu aplikacji ma flaga isAccessibilityTool ustawiona na prawda, lub poproś o sprawdzenie.

W tabeli poniżej znajdziesz kilka przykładów ocen i ich znaczenia (nie zawiera ona wszystkich możliwych wyników):

W zależności od poziomu ryzyka możesz zdecydować, którą kombinację ocen można kontynuować i jakie werdykty chcesz podjąć. W tym fragmencie kodu widać, jak sprawdzić, czy nie ma uruchomionych aplikacji, które mogłyby przechwytywać ekran lub sterować aplikacją:

val environmentDetails =
    JSONObject(payload).getJSONObject("environmentDetails")
val appAccessRiskVerdict =
    environmentDetails.getJSONObject("appAccessRiskVerdict")

if (appAccessRiskVerdict.has("appsDetected")) {
    val appsDetected = appAccessRiskVerdict.getJSONArray("appsDetected").toString()
    if (!appsDetected.contains("CAPTURING") && !appsDetected.contains("CONTROLLING")) {
        // Looks good!
    }
}

JSONObject environmentDetails =
    new JSONObject(payload).getJSONObject("environmentDetails");
JSONObject appAccessRiskVerdict =
    environmentDetails.getJSONObject("appAccessRiskVerdict");

if (appAccessRiskVerdict.has("appsDetected")) {
    String appsDetected = appAccessRiskVerdict.getJSONArray("appsDetected").toString()
    if (!appsDetected.contains("CAPTURING") && !appsDetected.contains("CONTROLLING")) {
        // Looks good!
    }
}

Ocena Play Protect

Po włączeniu pole environmentDetails w ładunku interfejsu Play Integrity API będzie zawierać ocenę Play Protect:

environmentDetails: {
  playProtectVerdict: "NO_ISSUES"
}

playProtectVerdict może mieć jedną z tych wartości:

NO_ISSUES

Funkcja Play Protect jest włączona, ale nie wykryła żadnych problemów z aplikacją na urządzeniu.

NO_DATA

Play Protect jest włączone, ale jeszcze nie przeprowadzono skanowania. Urządzenie lub aplikacja Sklep Play mogły zostać niedawno zresetowane.

POSSIBLE_RISK

Funkcja Play Protect jest wyłączona.

MEDIUM_RISK

Usługa Play Protect jest włączona i znalazła potencjalnie szkodliwe aplikacje zainstalowane na urządzeniu.

HIGH_RISK

Usługa Play Protect jest włączona i wykryła zainstalowane na urządzeniu niebezpieczne aplikacje.

UNEVALUATED

Decyzja w sprawie Play Protect nie została rozpatrzona.

Może się tak zdarzyć z kilku powodów. Oto niektóre z nich:

• Urządzenie nie jest wystarczająco zaufane.
• Tylko gry: konto użytkownika nie ma licencji na daną grę w Google Play.

Wskazówki dotyczące korzystania z oceny Play Protect

Serwer backendu aplikacji może zdecydować o działaniu na podstawie oceny na podstawie tolerancji ryzyka. Oto kilka sugestii i potencjalnych działań użytkowników:

NO_ISSUES

Usługa Play Protect jest włączona i nie wykryła żadnych problemów, więc użytkownik nie musi nic robić.

POSSIBLE_RISK i NO_DATA

Gdy otrzymasz takie oceny, poproś użytkownika o sprawdzenie, czy funkcja Play Protect jest włączona i czy przeprowadziła skanowanie. Wartość NO_DATA powinna się pojawiać tylko w rzadkich przypadkach.

MEDIUM_RISK i HIGH_RISK

W zależności od tolerancji ryzyka możesz poprosić użytkownika o uruchomienie Play Protect i podjęcie działań związanych z ostrzeżeniami Play Protect. Jeśli użytkownik nie może spełnić tych wymagań, możesz zablokować mu dostęp do działania serwera.