Standard-API-Anfrage stellen

Auf dieser Seite wird beschrieben, wie Sie Standard-API-Anfragen für Integritätsergebnisse stellen. werden auf Geräten mit Android 5.0 (API-Level 21) oder höher unterstützt. Sie können eine Standard- API-Anfrage für ein Integritätsergebnis, wenn deine App einen Serveraufruf durchführt um zu prüfen, ob die Interaktion echt ist.

Übersicht

Eine Standardanfrage besteht aus zwei Teilen:

• Bereiten Sie den Anbieter des Integritätstokens vor (einmalig): Sie müssen die Methode Mit der Integrity API den Integritätstoken-Anbieter lange vorbereiten, um das Integritätsergebnis zu erhalten. Das ist z. B. möglich, wenn Ihre App oder im Hintergrund laufen, bevor das Integritätsergebnis erforderlich ist.
• Integritätstoken anfordern (bei Bedarf): Immer, wenn Ihre App einen Server stellt die Sie auf Echtheit prüfen möchten, fordern Sie ein Integritätstoken an, und zur Entschlüsselung und Überprüfung an den Backend-Server der App senden. Dann kann Ihr Backend-Server entscheiden, wie er sich verhalten soll.

Bereiten Sie den Anbieter des Integritätstokens vor (einmalig):

1. Ihre App ruft den Anbieter von Integritätstokens mit Ihrem Google Cloud-Projekt auf Nummer.
2. Deine App speichert den Anbieter des Integritätstokens zur weiteren Aufrufe von Attestierungsprüfungen.

Integritätstoken anfordern (bei Bedarf):

1. Für die Nutzeraktion, die geschützt werden muss, berechnet Ihre App den Hashwert (unter Verwendung eines geeigneten Hash-Algorithmus wie SHA256) der Anfrage.
2. Ihre App fordert ein Integritätstoken an und übergibt den Anfrage-Hash.
3. Deine App empfängt das signierte und verschlüsselte Integritätstoken von Google Play Integrity API verwenden.
4. Ihre App übergibt das Integritätstoken an das Back-End Ihrer App.
5. Das Back-End Ihrer App sendet das Token an einen Google Play-Server. Google Play entschlüsselt und verifiziert das Ergebnis, sodass die Ergebnisse an die Back-End.
6. Das Back-End Ihrer App entscheidet anhand der Signale in der Token-Nutzlast.
7. Das Back-End Ihrer Anwendung sendet die Entscheidungsergebnisse an die Anwendung.

Anbieter von Integritätstokens vorbereiten (einmalig)

Bevor Sie ein Standardergebnis für ein Integritätsergebnis bei Google Play anfordern, müssen Sie den Anbieter von Integritätstokens vorbereiten (bzw. „aufwärmen“). Dadurch kann Google Play, um teilweise Attestierungsinformationen intelligent im Cache des Geräts zu speichern, um die Latenz im kritischen Pfad zu verringern, wenn Sie eine Anfrage für eine Integritätsergebnis vor. Wenn Sie den Tokenanbieter noch einmal vorbereiten, müssen Sie weniger wiederholen. ressourcenintensive Integritätsprüfungen, die das nächste Integritätsergebnis die Sie auf dem neuesten Stand halten.

Sie können den Anbieter von Integritätstokens vorbereiten:

• Wann Ihre App gestartet wird (z.B. beim Kaltstart). Tokenanbieter vorbereiten ist asynchron und wirkt sich daher nicht auf die Startzeit aus. Diese Option würde funktionieren gut, wenn Sie kurz nach der Veröffentlichung ein Integritätsergebnis App gestartet wird, beispielsweise wenn sich ein Nutzer anmeldet oder ein Spieler einem Spiel beitritt.
• Wenn Ihre App geöffnet wird (d. h. beim Warmstart) Beachten Sie jedoch, dass jede App -Instanz kann das Integritätstoken nur bis zu fünfmal pro Minute vorbereiten.
• Jederzeit im Hintergrund, wenn Sie das Token im Voraus vorbereiten möchten eines Ersuchens um ein Integritätsergebnis.

So bereiten Sie den Anbieter des Integritätstokens vor:

1. Erstellen Sie eine StandardIntegrityManager, wie in den folgenden Beispielen gezeigt.
2. PrepareIntegrityTokenRequest erstellen, die die Google Cloud bereitstellt Projektnummer mithilfe der Methode setCloudProjectNumber().
3. Rufen Sie prepareIntegrityToken() über das Manager-Konto auf und geben Sie dabei Folgendes an: PrepareIntegrityTokenRequest.

Tipp: Die Aufwärmlatenz beträgt in der Regel nur wenige Sekunden und ist bei den meisten unter 10 Sekunden. Beim Aufwärmen wird jedoch ein Serveraufruf ausgelöst, sodass eine Zeitüberschreitung auch ein langes Ende von Anfragen berücksichtigt (z.B. 1 Minute).

Java

import com.google.android.gms.tasks.Task;

// Create an instance of a manager.
StandardIntegrityManager standardIntegrityManager =
    IntegrityManagerFactory.createStandard(applicationContext);

StandardIntegrityTokenProvider integrityTokenProvider;
long cloudProjectNumber = ...;

// Prepare integrity token. Can be called once in a while to keep internal
// state fresh.
standardIntegrityManager.prepareIntegrityToken(
    PrepareIntegrityTokenRequest.builder()
        .setCloudProjectNumber(cloudProjectNumber)
        .build())
    .addOnSuccessListener(tokenProvider -> {
        integrityTokenProvider = tokenProvider;
    })
    .addOnFailureListener(exception -> handleError(exception));

Unity

IEnumerator PrepareIntegrityTokenCoroutine() {
    long cloudProjectNumber = ...;

    // Create an instance of a standard integrity manager.
    var standardIntegrityManager = new StandardIntegrityManager();

    // Request the token provider.
    var integrityTokenProviderOperation =
      standardIntegrityManager.PrepareIntegrityToken(
        new PrepareIntegrityTokenRequest(cloudProjectNumber));

    // Wait for PlayAsyncOperation to complete.
    yield return integrityTokenProviderOperation;

    // Check the resulting error code.
    if (integrityTokenProviderOperation.Error != StandardIntegrityErrorCode.NoError)
    {
        AppendStatusLog("StandardIntegrityAsyncOperation failed with error: " +
                integrityTokenProviderOperation.Error);
        yield break;
    }

    // Get the response.
    var integrityTokenProvider = integrityTokenProviderOperation.GetResult();
}

Ich bin Muttersprachler

/// Initialize StandardIntegrityManager
StandardIntegrityManager_init(/* app's java vm */, /* an android context */);
/// Create a PrepareIntegrityTokenRequest opaque object.
int64_t cloudProjectNumber = ...;
PrepareIntegrityTokenRequest* tokenProviderRequest;
PrepareIntegrityTokenRequest_create(&tokenProviderRequest);
PrepareIntegrityTokenRequest_setCloudProjectNumber(tokenProviderRequest, cloudProjectNumber);

/// Prepare a StandardIntegrityTokenProvider opaque type pointer and call
/// StandardIntegrityManager_prepareIntegrityToken().
StandardIntegrityTokenProvider* tokenProvider;
StandardIntegrityErrorCode error_code =
        StandardIntegrityManager_prepareIntegrityToken(tokenProviderRequest, &tokenProvider);

/// ...
/// Proceed to polling iff error_code == STANDARD_INTEGRITY_NO_ERROR
if (error_code != STANDARD_INTEGRITY_NO_ERROR)
{
    /// Remember to call the *_destroy() functions.
    return;
}
/// ...
/// Use polling to wait for the async operation to complete.

IntegrityResponseStatus token_provider_status;

/// Check for error codes.
StandardIntegrityErrorCode error_code =
        StandardIntegrityTokenProvider_getStatus(tokenProvider, &token_provider_status);
if (error_code == STANDARD_INTEGRITY_NO_ERROR
    && token_provider_status == INTEGRITY_RESPONSE_COMPLETED)
{
    /// continue to request token from the token provider
}
/// ...
/// Remember to free up resources.
PrepareIntegrityTokenRequest_destroy(tokenProviderRequest);

Anfragen vor Manipulation schützen (empfohlen)

Wenn Sie eine Nutzeraktion in Ihrer App mit der Play Integrity API prüfen, kann das Feld requestHash nutzen, um Manipulationsangriffe abzuwehren. Für Beispiel: Ein Spiel möchte die Punktzahl des Spielers an das Back-End des Spiels und Ihr Server möchte sicherstellen, dass dieser Wert nicht durch einen Proxyserver. Die Play Integrity API gibt den Wert zurück, den du im Feld Das Feld requestHash in der signierten Integritätsantwort. Ohne die requestHash, ist das Integritätstoken nur an das Gerät gebunden, aber nicht an die spezifische Anforderung, was die Möglichkeit eines Angriffs eröffnet. Die folgenden Anweisungen zur effektiven Nutzung des Felds requestHash:

Wenn Sie ein Integritätsergebnis anfordern, gilt Folgendes:

• Digest aller relevanten Anfrageparameter berechnen (z.B. SHA256 einer stabilen Version) Serialisierung anfordern) aus der Nutzeraktion oder Serveranfrage, die was gerade passiert. Der im Feld requestHash festgelegte Wert hat eine maximale Länge von 500 Byte. Nimm alle wichtigen oder wichtigen App-Anfragedaten in die requestHash auf. die für die Aktion relevant sind, die Sie überprüfen oder schützen. Die Das Feld requestHash ist wörtlich im Integritätstoken enthalten, also ist kann die Größe der Anfrage erhöhen.
• Sende der Play Integrity API den Digest als Feld requestHash und um das Integritätstoken abzurufen.

Achtung: Geben Sie vertrauliche Informationen niemals als Klartext in das requestHash-Argument. Stattdessen sollten Sie alle Eingaben standardmäßig hashen.

Wenn du ein Integritätsergebnis erhältst, gilt Folgendes:

• Decodieren Sie das Integritätstoken und extrahieren Sie das Feld requestHash.
• Einen Digest der Anfrage auf dieselbe Weise wie in der App berechnen (z.B. SHA256 einer stabilen Serialisierung von Anfragen).
• Vergleichen Sie die App-seitigen und serverseitigen Digests. Stimmen sie nicht überein, Anfrage ist nicht vertrauenswürdig.

Hinweis: Standardanfragen sind automatisch vor Replay-Angriffen geschützt.

Integritätsergebnis anfordern (bei Bedarf)

Nachdem Sie den Anbieter des Integritätstokens vorbereitet haben, können Sie Integritätsergebnisse von Google Play. Führen Sie dazu die folgenden Schritte aus:

1. Besorgen Sie sich ein StandardIntegrityTokenProvider wie oben gezeigt.
2. Erstellen Sie ein StandardIntegrityTokenRequest mit dem Anfrage-Hash von Nutzeraktion, die Sie mit der Methode setRequestHash schützen möchten.
3. Rufen Sie request() mit dem Anbieter des Integritätstokens auf und geben Sie dabei den Parameter StandardIntegrityTokenRequest.

Java

import com.google.android.gms.tasks.Task;

StandardIntegrityTokenProvider integrityTokenProvider;

// See above how to prepare integrityTokenProvider.

// Request integrity token by providing a user action request hash. Can be called
// several times for different user actions.
String requestHash = "2cp24z...";
Task<StandardIntegrityToken> integrityTokenResponse =
    integrityTokenProvider.request(
        StandardIntegrityTokenRequest.builder()
            .setRequestHash(requestHash)
            .build());
integrityTokenResponse
    .addOnSuccessListener(response -> sendToServer(response.token()))
    .addOnFailureListener(exception -> handleError(exception));

Unity

IEnumerator RequestIntegrityTokenCoroutine() {
    StandardIntegrityTokenProvider integrityTokenProvider;

    // See above how to prepare integrityTokenProvider.

    // Request integrity token by providing a user action request hash. Can be called
    // several times for different user actions.
    String requestHash = "2cp24z...";
    var integrityTokenOperation = integrityTokenProvider.Request(
      new StandardIntegrityTokenRequest(requestHash)
    );

    // Wait for PlayAsyncOperation to complete.
    yield return integrityTokenOperation;

    // Check the resulting error code.
    if (integrityTokenOperation.Error != StandardIntegrityErrorCode.NoError)
    {
        AppendStatusLog("StandardIntegrityAsyncOperation failed with error: " +
                integrityTokenOperation.Error);
        yield break;
    }

    // Get the response.
    var integrityToken = integrityTokenOperation.GetResult();
}

Ich bin Muttersprachler

/// Create a StandardIntegrityTokenRequest opaque object.
const char* requestHash = ...;
StandardIntegrityTokenRequest* tokenRequest;
StandardIntegrityTokenRequest_create(&tokenRequest);
StandardIntegrityTokenRequest_setRequestHash(tokenRequest, requestHash);

/// Prepare a StandardIntegrityToken opaque type pointer and call
/// StandardIntegrityTokenProvider_request(). Can be called several times for
/// different user actions. See above how to prepare token provider.
StandardIntegrityToken* token;
StandardIntegrityErrorCode error_code =
        StandardIntegrityTokenProvider_request(tokenProvider, tokenRequest, &token);

/// ...
/// Proceed to polling iff error_code == STANDARD_INTEGRITY_NO_ERROR
if (error_code != STANDARD_INTEGRITY_NO_ERROR)
{
    /// Remember to call the *_destroy() functions.
    return;
}
/// ...
/// Use polling to wait for the async operation to complete.

IntegrityResponseStatus token_status;

/// Check for error codes.
StandardIntegrityErrorCode error_code =
        StandardIntegrityToken_getStatus(token, &token_status);
if (error_code == STANDARD_INTEGRITY_NO_ERROR
    && token_status == INTEGRITY_RESPONSE_COMPLETED)
{
    const char* integrityToken = StandardIntegrityToken_getToken(token);
}
/// ...
/// Remember to free up resources.
StandardIntegrityTokenRequest_destroy(tokenRequest);
StandardIntegrityToken_destroy(token);
StandardIntegrityTokenProvider_destroy(tokenProvider);
StandardIntegrityManager_destroy();

Integritätsergebnis entschlüsseln und prüfen

Nachdem du ein Integritätsergebnis angefordert hast, bietet die Play Integrity API ein verschlüsseltes Antworttoken. Um die Ergebnisse zur Geräteintegrität zu erhalten, müssen Sie das Integritätstoken auf den Google-Servern zu entschlüsseln. Führen Sie dazu die folgenden Schritte aus:

1. Dienstkonto erstellen innerhalb des Google Cloud-Projekts, das mit Ihrer Anwendung verknüpft ist.

2. Rufen Sie auf dem Server der Anwendung das Zugriffstoken von Ihrem Dienstkonto ab. Anmeldedaten mit dem Playintegrity-Bereich und stellen Sie die folgende Anfrage:

   playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken -d \
   '{ "integrity_token": "INTEGRITY_TOKEN" }'

   Hinweis: Um auf die REST-Schnittstelle der API zuzugreifen, können Sie den Google API-Client verwenden. Mediathek, die in vielen Programmiersprachen verfügbar ist, einschließlich Java

3. Lesen Sie die JSON-Antwort.

Die resultierende Nutzlast ist ein Nur-Text-Token, das Integrität .

Automatischer Wiederholungsschutz

Um Replay-Angriffe abzuwehren, stellt Google Play automatisch sicher, dass alle Integritätstoken kann nicht mehrfach wiederverwendet werden. Sie versuchen wiederholt, den führt dasselbe Token zu leeren Ergebnissen.