Esegui una richiesta API standard

Questa pagina descrive le richieste API standard per gli esiti dell'integrità, che sono supportate su Android 5.0 (livello API 21) o versioni successive. Puoi effettuare una richiesta API standard per ottenere un esito relativo all'integrità ogni volta che la tua app effettua una chiamata al server per verificare se l'interazione è autentica.

Panoramica

Diagramma di sequenza che mostra la progettazione di alto livello dell'API Play Integrity

Una richiesta standard è costituita da due parti:

  • Prepara il provider di token di integrità (una tantum): devi chiamare l'API Integrity per preparare bene il provider di token di integrità prima di ottenere l'esito relativo all'integrità. Ad esempio, puoi farlo all'avvio dell'app o in background prima che sia necessario l'esito relativo all'integrità.
  • Richiedi un token di integrità (on demand): ogni volta che la tua app effettua una richiesta del server che vuoi verificare, richiedi un token di integrità e lo invii al server di backend dell'app per la decriptazione e la verifica. Successivamente, il tuo server di backend potrà decidere come agire.

Prepara il provider di token di integrità (una tantum):

  1. La tua app chiama il provider di token di integrità con il numero del tuo progetto Google Cloud.
  2. La tua app conserva in memoria il provider di token di integrità per ulteriori chiamate di controllo dell'attestazione.

Richiedi un token di integrità (on demand):

  1. Per l'azione utente che deve essere protetta, la tua app calcola l'hash (utilizzando qualsiasi algoritmo hash adatto, come SHA256) della richiesta da effettuare.
  2. La tua app richiede un token di integrità, passando l'hash della richiesta.
  3. La tua app riceve il token di integrità firmato e criptato dall'API Play Integrity.
  4. L'app passa il token di integrità al backend dell'app.
  5. Il backend dell'app invia il token a un server Google Play. Il server di Google Play decripta e verifica l'esito, restituendo i risultati al backend dell'app.
  6. Il backend della tua app decide come procedere in base agli indicatori contenuti nel payload del token.
  7. Il backend dell'app invia i risultati della decisione all'app.

Prepara il provider di token di integrità (una tantum)

Prima di effettuare una richiesta standard di un esito relativo all'integrità da Google Play, devi preparare (o "preparare") il fornitore di token di integrità. In questo modo, Google Play può memorizzare nella cache in modo intelligente le informazioni di attestazione parziale sul dispositivo al fine di ridurre la latenza sul percorso critico quando invii una richiesta di esito relativo all'integrità. Preparare di nuovo il provider di token è un modo per ripetere controlli di integrità meno intensivi delle risorse e che determinerà il successivo esito relativo all'integrità richiesto più aggiornato.

Potresti preparare il fornitore di token di integrità:

  • All'avvio dell'app (ad esempio all'avvio a freddo). La preparazione del provider di token è asincrona e non influisce sui tempi di avvio. Questa opzione funziona bene se prevedi di presentare una richiesta di esito relativo all'integrità poco dopo l'avvio dell'app, ad esempio quando un utente accede o un giocatore partecipa a un gioco.
  • All'apertura dell'app (ad esempio durante un avvio a caldo). Tuttavia, tieni presente che ogni istanza di app può preparare il token di integrità solo fino a cinque volte al minuto.
  • In qualsiasi momento in background quando vuoi preparare il token prima di una richiesta di esito relativo all'integrità.

Per preparare il fornitore di token di integrità, segui questi passaggi:

  1. Crea un'StandardIntegrityManager, come mostrato negli esempi seguenti.
  2. Crea un PrepareIntegrityTokenRequest, fornendo il numero di progetto Google Cloud tramite il metodo setCloudProjectNumber().
  3. Utilizza l'amministratore per chiamare prepareIntegrityToken(), fornendo il PrepareIntegrityTokenRequest.

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();
}

Nativo

/// 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);

Proteggi le richieste da manomissioni (opzione consigliata)

Quando controlli l'azione di un utente nella tua app con l'API Play Integrity, puoi sfruttare il campo requestHash per mitigare gli attacchi di manomissione. Ad esempio, un gioco potrebbe voler segnalare il punteggio del giocatore al suo server di backend, in modo che il tuo server voglia assicurarsi che il punteggio non sia stato manomesso da un server proxy. L'API Play Integrity restituisce il valore impostato nel campo requestHash, all'interno della risposta relativa all'integrità firmata. Senza requestHash, il token di integrità verrà associato solo al dispositivo, ma non alla richiesta specifica, il che apre la possibilità di attacchi. Le seguenti istruzioni descrivono come utilizzare il campo requestHash in modo efficace:

Quando richiedi un esito relativo all'integrità:

  • Calcola un digest di tutti i parametri di richiesta pertinenti (ad es. SHA256 di una serializzazione stabile) dall'azione utente o dalla richiesta del server in corso. Il valore impostato nel campo requestHash ha una lunghezza massima di 500 byte. Includi nel requestHash tutti i dati delle richieste di app che siano fondamentali o pertinenti all'azione che stai controllando o proteggendo. Il campo requestHash è incluso nel testo del token di integrità, quindi valori lunghi possono aumentare le dimensioni della richiesta.
  • Fornisci il digest come campo requestHash all'API Play Integrity e ottieni il token di integrità.

Quando ricevi un esito relativo all'integrità:

  • Decodifica il token di integrità ed estrai il campo requestHash.
  • Calcola un digest della richiesta come nell'app (ad es. SHA256 di una serializzazione di richiesta stabile).
  • Confronta le sintesi lato app e lato server. Se non corrispondono, la richiesta non è attendibile.

Richiedere un esito relativo all'integrità (on demand)

Dopo aver preparato il provider di token di integrità, puoi iniziare a richiedere esiti relativi all'integrità da Google Play. Per farlo, segui questi passaggi:

  1. Ottieni un StandardIntegrityTokenProvider, come mostrato sopra.
  2. Crea un StandardIntegrityTokenRequest, fornendo l'hash della richiesta dell'azione utente da proteggere tramite il metodo setRequestHash.
  3. Usa il provider di token di integrità per chiamare request(), fornendo il 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();
}

Nativo

/// 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();

Decripta e verifica l'esito relativo all'integrità

Dopo aver richiesto un esito relativo all'integrità, l'API Play Integrity fornisce un token di risposta criptato. Per ottenere gli esiti relativi all'integrità del dispositivo, devi decriptare il token di integrità sui server di Google. Per farlo, segui questi passaggi:

  1. Crea un account di servizio all'interno del progetto Google Cloud collegato alla tua app.

  2. Sul server dell'app, recupera il token di accesso dalle credenziali dell'account di servizio utilizzando l'ambito playintegrity ed effettua la richiesta seguente:

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

  3. Leggi la risposta JSON.

Il payload risultante è un token di testo normale che contiene verdetti di integrità.

Protezione dalla riproduzione automatica

Per mitigare gli attacchi di ripetizione, Google Play garantisce automaticamente che ogni token di integrità non possa essere riutilizzato molte volte. Se si tenta di decriptare ripetutamente lo stesso token, l'esito sarà vuoto.

Indietro
Configurazione
Avanti
Effettua una richiesta classica