Oceny integralności

Na tej stronie dowiesz się, jak interpretować zwróconą integralność i pracować z nimi wyroku. Niezależnie od tego, czy wysyłasz żądanie do interfejsu standardowego czy klasycznego, wynik jest zwracany w tym samym formacie z podobną treścią. Integralność informuje o prawidłowości urządzeń, aplikacji kont. Serwer aplikacji może użyć wynikowego ładunku w odszyfrowanej, zweryfikowanej oceny w celu określenia najlepszego sposobu postępowania w przypadku konkretnego działania, w aplikacji.

Zwrócony format oceny integralności

Ładunek jest zwykłym tekstem JSON i zawiera sygnały integralności podanymi przez dewelopera.

Ogólna struktura ładunku wygląda tak:

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

Najpierw sprawdź, czy wartości w polu requestDetails są zgodne z tymi pierwotnego żądania przed sprawdzeniem każdego wyniku integralności. Poniżej opisują poszczególne pola.

Pole szczegółów prośby

Pole requestDetails zawiera informacje o żądaniu, w tym podane przez dewelopera w: requestHash dotyczące standardowych żądań oraz nonce dla żą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 requested.
  timestampMillis: "1675655009345"
}

Wartości te powinny być zgodne z wartościami w pierwotnym żądaniu. Dlatego sprawdź requestDetails ładunku JSON, upewniając się, że para klucz-wartość requestPackageName i requestHash są zgodne z tym, co wysłano w oryginale. zgodnie z poniższym fragmentem 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 w pierwotnym żądaniu. Dlatego sprawdź requestDetails ładunku JSON, upewniając się, że para klucz-wartość requestPackageName i nonce są zgodne z treścią przesłaną w pierwotnym żądaniu, na przykład 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 o pakiecie.

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"
}

Pole appRecognitionVerdict może mieć następujące wartości:

PLAY_RECOGNIZED

Aplikacja i certyfikat odpowiadają wersjom rozpowszechnianym przez Google Play.

UNRECOGNIZED_VERSION

Nazwa certyfikatu lub pakietu nie zgadza się z nazwą Google Rekordy Play.

UNEVALUATED

Integralność aplikacji nie została oceniona. Konieczny wymóg na przykład gdy urządzenie nie było wystarczająco zaufane.

Aby mieć pewność, że token został wygenerowany przez utworzoną przez Ciebie aplikację, zweryfikuj że integralność aplikacji jest zgodna z oczekiwaniami, jak pokazano w tym kodzie snippet:

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ż sprawdzić nazwę pakietu aplikacji, wersję aplikacji i certyfikaty aplikacji ręcznie.

Pole integralności urządzenia

Pole deviceIntegrity może zawierać jedną wartość, deviceRecognitionVerdict, która ma co najmniej jedną etykietę reprezentującą skuteczność aby wymusić 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 pole deviceRecognitionVerdict może zawierać:

MEETS_DEVICE_INTEGRITY

Ta aplikacja działa na urządzeniu z Androidem i ma: Usługi Google Play. Urządzenie przeszło testy integralności systemu i jest zgodne wymagania dotyczące zgodności z Androidem.

Pusta (pusta wartość)

Aplikacja działa na urządzeniu, na którym występują objawy atak (np. podłączenie interfejsu API) lub przejęcie systemu (np. uzyskanie dostępu do roota) lub aplikacja nie jest uruchomiona na urządzeniu fizycznym (np. w emulatorze, który nie przeszły testów integralności w Google Play).

Aby mieć pewność, że token pochodzi z wiarygodnego urządzenia, zweryfikuj Pole deviceRecognitionVerdict jest zgodne z oczekiwaniami, jak widać w tym kodzie snippet:

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!
}

W przypadku problemów z integralnością urządzenia testowego do spotkań upewnij się, że fabryczna pamięć ROM jest zainstalowana (na przykład przez zresetowanie urządzenia). oraz że program rozruchowy jest zablokowany. Możesz też tworzyć testy interfejsu Play Integrity API. w Konsoli Play.

Warunkowe etykiety urządzeń

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 emulatorze z Androidem z Usługi Google Play. Emulator przeszedł testy integralności systemu i spełnia wymagania podstawowych wymagań dotyczących zgodności z Androidem.

Opcjonalne informacje o urządzeniu

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

MEETS_BASIC_INTEGRITY

Aplikacja działa na urządzeniu, które spełnia wymagania podstawowe i testów integralności systemu. Urządzenie może nie być zgodne z Androidem wymagania i mogą nie zostać zatwierdzone do uruchamiania Usług Google Play. Dla: na przykład na urządzeniu może działać nierozpoznana wersja Androida, mają odblokowany program rozruchowy lub nie mają certyfikatu producenta urządzenia.

MEETS_STRONG_INTEGRITY

Ta aplikacja działa na urządzeniu z Androidem i ma: Usługom Google Play i obejmują silną gwarancję integralności systemu, np.: wspierany sprzętowo dowód integralności rozruchu. Urządzenie przekazuje system przeprowadza testy integralności i jest zgodny z Androidem.

Jedno urządzenie zwraca wiele etykiet w ramach integralności określa, czy spełnione są wszystkie kryteria etykiety.

Ostatnia aktywność na urządzeniach

Możesz też włączyć wyświetlanie ostatniej aktywności na urządzeniu, by dowiedzieć się, jak aplikacja wiele razy prosiła o token integralności na konkretnym urządzeniu. z ostatniej godziny. Dzięki ostatniej aktywności na urządzeniu możesz chronić swoją aplikację przed urządzenia, których nie rozpoznajesz, i które z nich mogą wskazywać na aktywny atak. Możesz określić, jak zaufanym użytkownikom ostatni poziom aktywności na urządzeniu, na podstawie tego, oczekuje, że aplikacja zostanie zainstalowana na typowym urządzeniu. token integralności co godzinę.

Jeśli wyrazisz zgodę na otrzymywanie recentDeviceActivity pola deviceIntegrity, ma 2 wartości:

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

Definicje funkcji 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 jedną wartość, appLicensingVerdict, która reprezentuje stan licencji na aplikację w Google Play dla konta użytkownika, zalogowany na urządzeniu. Jeśli konto użytkownika ma licencję Google Play na aplikację, co oznacza, że pobrali ją lub kupili w Google Play.

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

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

LICENSED

Użytkownik ma uprawnienia do korzystania z aplikacji. Innymi słowy, użytkownik zainstalował lub kupią aplikację w Google Play.

UNLICENSED

Użytkownik nie ma uprawnień do korzystania z aplikacji. Dzieje się tak, gdy w przypadku na przykład zainstaluje ją z innego źródła lub nie pozyska jej z Google Play. Aby temu zapobiec, możesz wyświetlić użytkownikom okno GET_LICENSED.

UNEVALUATED

Szczegóły dotyczące licencji nie zostały ocenione, ponieważ wymagania nie zostały spełnione.

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

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

Aby sprawdzić, czy użytkownik ma uprawnienia do korzystania z Twojej aplikacji, sprawdź, czy atrybut appLicensingVerdict działa zgodnie z oczekiwaniami, jak widać 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ż włączyć dodatkowe sygnały dotyczące środowiska. Dostęp do aplikacji informuje aplikację, czy są uruchomione inne aplikacje, których można użyć do zrobić zrzut ekranu, wyświetlać nakładki czy sterować urządzeniem. Play Protect informuje, czy na urządzeniu jest włączona usługa Google Play Protect wykrył znane złośliwe oprogramowanie.

Jeśli wyrazisz zgodę na ocenę ryzyka dostępu aplikacji lub Play Protect w Konsoli Google Play, odpowiedź interfejsu API będzie zawierać parametr environmentDetails. Pole environmentDetails może zawierać dwa wartości appAccessRiskVerdict i playProtectVerdict.

Ocena ryzyka dostępu do aplikacji (beta)

Po włączeniu pojawi się pole environmentDetails w interfejsie Play Integrity API. ładunek 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ą. Odpowiedzi te trafiają do jednej z tych kategorii: te 2 grupy w zależności od źródła instalacji wykrytych aplikacji:

• Aplikacje systemowe lub aplikacje systemowe: aplikacje zainstalowane z Google Play lub wstępnie wczytane przez producenta urządzenia na partycji systemowej urządzenia (określaną parametrem FLAG_SYSTEM). Odpowiedzi w takich aplikacjach są poprzedzone prefiksem KNOWN_.

• Inne aplikacje: aplikacje, które nie zostały zainstalowane przez Google Play. Nie uwzględnia aplikacje wstępnie wczytane na partycję systemową przez producenta urządzenia. Odpowiedzi dla takich aplikacji jest poprzedzony prefiksem 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: by widzieć ekran, gdy aplikacja jest uruchomiona. Nie obejmuje to wszystkich zweryfikowanych usług ułatwień dostępu znanych Google Play uruchomionym na urządzeniu.

KNOWN_CONTROLLING, UNKNOWN_CONTROLLING

Masz uruchomione aplikacje z włączonymi uprawnieniami, których można użyć do: sterować urządzeniem i bezpośrednio kontrolować wejścia do aplikacji. Mogą być służy do przechwytywania danych wejściowych i wyjściowych aplikacji. Nie obejmuje to wszystkich zweryfikowanych usług ułatwień dostępu znanych Google Play uruchomionym na urządzeniu.

KNOWN_OVERLAYS, UNKNOWN_OVERLAYS

Masz uruchomione aplikacje z włączonymi uprawnieniami, których można użyć do: wyświetlanie nakładek w aplikacji. Nie obejmuje to zweryfikowanych ułatwień dostępu znane usługi Google Play działające na urządzeniu.

EMPTY (pusta wartość)

Ryzyko związane z dostępem do aplikacji nie jest oceniane, jeśli pominięto niezbędny wymóg. W w tym przypadku pole appAccessRiskVerdict jest puste. Może to dotyczyć: z kilku powodów, w tym:

• 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 Google Play na daną grę.
• Zostało użyte żądanie standardowe z parametrem verdictOptOut.
• Użyto standardowego żądania z wersją biblioteki Play Integrity API. , który nie obsługuje jeszcze ryzyka dostępu do aplikacji w przypadku żądań standardowych.

Ryzyko dostępu do aplikacji automatycznie wyklucza zweryfikowane usługi ułatwień dostępu, które zostały sprawdzone pod kątem ułatwień dostępu w Google Play (zainstalowane przez w dowolnym sklepie z aplikacjami na urządzeniu). „Wykluczono” oznacza, że zweryfikowane ułatwienia dostępu działające na urządzeniu nie zwracają przechwytywania, sterowania nakłada odpowiedź w ocenie ryzyka dotyczącego dostępu do aplikacji. Aby poprosić o Odtwórz opinię o ułatwieniach dostępu w swojej aplikacji ułatwień dostępu i opublikuj ją w Google Sprawdź, czy flaga isAccessibilityTool Twojej aplikacji ma wartość Prawda w pliku manifestu aplikacji lub poproś o jej sprawdzenie.

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

W zależności od poziomu ryzyka możesz wybrać kombinację ocen co można uznać za akceptowalne i jakie werdykty chcesz podjąć. Poniższy fragment kodu ilustruje przykład sprawdzania, czy nie ma uruchomionych aplikacji, które mogą 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!
    }
}

Eliminowanie ocen ryzyka dostępu do aplikacji

W zależności od poziomu ryzyka możesz określić oceny ryzyka dotyczącego dostępu do aplikacji w jaki sposób użytkownik chce podjąć działanie, zanim pozwoli mu to zrobić. Dostępne są opcjonalne prompty z Google Play, które możesz wyświetlać użytkownikowi sprawdzając ocenę ryzyka dostępu do aplikacji. Możesz wyświetlać CLOSE_UNKNOWN_ACCESS_RISK, aby poprosić użytkownika o zamknięcie nieznanych aplikacji powodujących ocenę ryzyka związanego z dostępem do aplikacji lub pokaż CLOSE_ALL_ACCESS_RISK, aby poprosić o zamknięcia wszystkich aplikacji (znane i nieznane) skutkujące oceną ryzyka dostępu do aplikacji.

Ocena Play Protect

Po włączeniu pojawi się pole environmentDetails w interfejsie Play Integrity API. ładunek będzie zawierać wynik Play Protect:

environmentDetails: {
  playProtectVerdict: "NO_ISSUES"
}

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

NO_ISSUES

Usługa Play Protect jest włączona, ale nie znaleziono na urządzeniu żadnych problemów z aplikacją.

NO_DATA

Usługa Play Protect jest włączona, ale nie przeprowadzono jeszcze skanowania. Urządzenie lub aplikacja Sklep Play mogła zostać niedawno zresetowana.

POSSIBLE_RISK

Usługa Play Protect jest wyłączona.

MEDIUM_RISK

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

HIGH_RISK

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

UNEVALUATED

Ocena Play Protect nie została sprawdzona.

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 Google Play na daną grę.

Wskazówki dotyczące korzystania z oceny Play Protect

Serwer backendu aplikacji może podjąć działanie na podstawie oceny tolerancji ryzyka. Oto kilka sugestii i możliwych działań użytkownika:

NO_ISSUES

Usługa Play Protect jest włączona i nie wykryto żadnych problemów, więc nie jest wymagane żadne działanie ze strony użytkownika.

POSSIBLE_RISK i NO_DATA

Gdy otrzymasz te oceny, poproś użytkownika, aby sprawdził, czy funkcja Play Protect jest włączona i przeprowadził skanowanie. NO_DATA powinna występować tylko w rzadkich przypadkach.

MEDIUM_RISK i HIGH_RISK

W zależności od tolerancji ryzyka możesz poprosić użytkownika o uruchomienie Google Play. Ochrona ostrzeżeń Play Protect i reagowanie na nie. Jeśli użytkownik nie może wypełnić kodu te wymagania mogą uniemożliwić wykonywanie działań serwera.