Eseguire una richiesta API classica

Se prevedi di effettuare solo richieste API standard, adatte alla maggior parte degli sviluppatori, puoi passare direttamente ai versetti di integrità. Questa pagina descrive l'esecuzione di richieste API classiche per gli esiti dell'integrità, che sono supportate su Android 4.4 (livello API 19) o versioni successive.

Considerazioni

Confrontare le richieste standard e classiche

Puoi effettuare richieste standard, richieste classiche o una combinazione delle due, a seconda delle esigenze di sicurezza e anti-abuso della tua app. Le richieste standard sono adatte a tutte le app e a tutti i giochi e possono essere utilizzate per verificare che qualsiasi azione o chiamata al server sia autentica, delegando a Google Play parte della protezione contro la riproducibilità e l'esfiltrazione. Le richieste classiche sono più costose da effettuare e sei responsabile della loro corretta implementazione per proteggerti da esfiltrazione e determinati tipi di attacchi. Le richieste classiche devono essere effettuate meno frequentemente rispetto alle richieste standard, ad esempio come controllo occasionale per verificare se un'azione di alto valore o sensibile è autentica.

La seguente tabella evidenzia le principali differenze tra i due tipi di richieste:

Richiesta API standard Richiesta API classica
Prerequisiti
Versione minima dell'SDK Android richiesta Android 5.0 (livello API 21) o versioni successive Android 4.4 (livello API 19) o versioni successive
Requisiti di Google Play Google Play Store e Google Play Services Google Play Store e Google Play Services
Dettagli dell'integrazione
È necessario il warm-up dell'API ✔️ (pochi secondi) ❌
Latenza tipica delle richieste Pochi centesimi di secondo Pochi secondi
Frequenza potenziale delle richieste Frequente (controllo on demand per qualsiasi azione o richiesta) Infrequente (controllo una tantum per le azioni di valore più elevato o le richieste più sensibili)
Timeout La maggior parte dei warm-up dura meno di 10 secondi, ma comporta una chiamata al server, quindi è consigliabile un timeout lungo (ad es. 1 minuto). Le richieste di esito vengono effettuate lato client La maggior parte delle richieste dura meno di 10 secondi, ma comporta una chiamata al server, quindi è consigliabile un timeout lungo (ad es.1 minuto).
Token di esito relativo all'integrità
Contiene dettagli su dispositivo, app e account ✔️ ✔️
Memorizzazione nella cache dei token Memorizzazione nella cache sul dispositivo protetta da Google Play Selezione sconsigliata
Decrittografare e verificare il token tramite il server di Google Play ✔️ ✔️
Latenza tipica delle richieste di decrittografia da server a server Decine di millisecondi con disponibilità a tre nove Decine di millisecondi con disponibilità a tre nove
Decriptare e verificare il token localmente in un ambiente server sicuro ❌ ✔️
Decrittografare e verificare il token lato client ❌ ❌
Aggiornamento dell'esito relativo all'integrità Alcune operazioni di memorizzazione nella cache e aggiornamento automatico da parte di Google Play Tutti i verdetti vengono ricalcolati a ogni richiesta
limiti
Richieste per app al giorno 10.000 per impostazione predefinita (è possibile richiedere un aumento) 10.000 per impostazione predefinita (è possibile richiedere un aumento)
Richieste per istanza dell'app al minuto Riscaldamento: 5 al minuto
Token di integrità: nessun limite pubblico*		 Token di integrità: 5 al minuto
Protezione
Mitigare la manomissione e attacchi simili Utilizzare il campo requestHash Utilizza il campo nonce con l'associazione dei contenuti in base ai dati della richiesta
Mitigare gli attacchi di replay e simili Mitigazione automatica da parte di Google Play Utilizzare il campo nonce con la logica lato server

* Tutte le richieste, comprese quelle senza limiti pubblici, sono soggette a limiti difensivi non pubblici a valori elevati

Effettua richieste classiche di rado

La generazione di un token di integrità utilizza tempo, dati e batteria e ogni app ha un numero massimo di richieste classiche che può effettuare al giorno. Pertanto, devi effettuare richieste classiche solo per verificare che le azioni di valore più elevato o più sensibili siano autentiche quando vuoi una garanzia aggiuntiva a una richiesta standard. Non devi effettuare richieste classiche per azioni ad alta frequenza o di basso valore. Non effettuare richieste classiche ogni volta che l'app passa in primo piano né ogni pochi minuti in background ed evita di chiamare da un numero elevato di dispositivi contemporaneamente. Un'app che effettua troppe chiamate di richieste classiche potrebbe essere limitata per proteggere gli utenti da implementazioni errate.

Evitare la memorizzazione nella cache dei verdetti

La memorizzazione nella cache di un verdetto aumenta il rischio di attacchi come l'esfiltrazione e la riproduzione, in cui un verdetto positivo viene riutilizzato da un ambiente non attendibile. Se stai valutando la possibilità di effettuare una richiesta classica e poi memorizzarla nella cache per utilizzarla in un secondo momento, ti consigliamo invece di eseguire una richiesta standard on demand. Le richieste standard comportano una certa memorizzazione nella cache sul dispositivo, ma Google Play utilizza tecniche di protezione aggiuntive per ridurre il rischio di attacchi di riproduzione e esfiltrazione.

Utilizza il campo nonce per proteggere le richieste classiche

L'API Play Integrity offre un campo denominato nonce, che può essere utilizzato per proteggere ulteriormente la tua app da determinati attacchi, come quelli di replay e manomissione. L'API Play Integrity restituisce il valore impostato in questo campo all'interno della risposta di integrità firmata. Segui attentamente le indicazioni su come generare nonce per proteggere la tua app dagli attacchi.

Esegui nuovi tentativi per le richieste classiche con backoff esponenziale

Condizioni ambientali, come una connessione a internet instabile o un dispositivo sovraccarico, possono causare il mancato superamento dei controlli di integrità del dispositivo. Ciò può comportare la mancata generazione di etichette per un dispositivo altrimenti attendibile. Per mitigare questi scenari, includi un'opzione di ripetizione con backoff esponenziale.

Panoramica

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

Quando l'utente esegue un'azione di alto valore nella tua app che vuoi proteggere con un controllo dell'integrità, completa i seguenti passaggi:

  1. Il backend lato server della tua app genera e invia un valore univoco alla logica lato client. I passaggi rimanenti fanno riferimento a questa logica come "app".
  2. La tua app crea l'nonce dal valore univoco e dai contenuti dell'azione di alto valore. Chiama quindi l'API Play Integrity, passando il nonce.
  3. La tua app riceve un esito firmato e criptato dall'API Play Integrity.
  4. La tua app trasmette il verdetto firmato e criptato al backend dell'app.
  5. Il backend dell'app invia il verdetto a un server di 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 determina come procedere in base agli indicatori contenuti nel payload del token.
  7. Il backend della tua app invia i risultati della decisione alla tua app.

Generare un nonce

Quando proteggi un'azione nella tua app con l'API Play Integrity, puoi sfruttare il campo nonce per mitigare determinati tipi di attacchi, come gli attacchi di manomissione person-in-the-middle (PITM) e gli attacchi di riproduzione. L'API Play Integrity restituisce il valore impostato in questo campo all'interno della risposta di integrità firmata.

Il valore impostato nel campo nonce deve essere formattato correttamente:

  • String
  • Sicuro per URL
  • Codificato come Base64 e senza wrapping
  • Minimo 16 caratteri
  • Massimo 500 caratteri

Di seguito sono riportati alcuni modi comuni per utilizzare il campo nonce nell'API Play Integrity. Per ottenere la massima protezione da nonce, puoi combinare i metodi riportati di seguito.

Includi un hash della richiesta per proteggere da manomissioni

Puoi utilizzare il parametro nonce in una richiesta API classica in modo simile al parametro requestHash in una richiesta API standard per proteggere i contenuti di una richiesta dalla manomissione.

Quando richiedi un esito relativo all'integrità:

  1. Calcola un digest di tutti i parametri di richiesta critici (ad es. SHA256 di una serializzazione stabile della richiesta) dall'azione utente o dalla richiesta del server in corso.
  2. Utilizza setNonce per impostare il campo nonce sul valore del digest calcolato.

Quando ricevi un esito relativo all'integrità:

  1. Decodifica e verifica il token di integrità e ottieni il digest dal campo nonce.
  2. Calcola un digest della richiesta nello stesso modo dell'app (ad es. SHA256 di una serializzazione stabile della richiesta).
  3. Confronta i digest lato app e lato server. Se non corrispondono, la richiesta non è attendibile.

Includi valori unici per proteggere dagli attacchi di riproduzione

Per impedire agli utenti malintenzionati di riutilizzare le risposte precedenti dell'API Play Integrity, puoi utilizzare il campo nonce per identificare in modo univoco ogni messaggio.

Quando richiedi un esito relativo all'integrità:

  1. Ottieni un valore univoco a livello globale in modo che gli utenti malintenzionati non possano prevederlo. Ad esempio, un numero casuale sicuro dal punto di vista crittografico generato sul lato server può essere un valore di questo tipo, oppure un ID preesistente, ad esempio una sessione o un ID transazione. Una variante più semplice e meno sicura consiste nel generare un numero casuale sul dispositivo. Ti consigliamo di creare valori di 128 bit o superiori.
  2. Chiama setNonce() per impostare il campo nonce sul valore univoco del passaggio 1.

Quando ricevi un esito relativo all'integrità:

  1. Decodifica e verifica il token di integrità e ottieni il valore univoco dal campo nonce.
  2. Se il valore del passaggio 1 è stato generato sul server, verifica che il valore univoco ricevuto sia uno dei valori generati e che venga utilizzato per la prima volta (il server dovrà conservare un record dei valori generati per un periodo di tempo adeguato). Se il valore univoco ricevuto è già stato utilizzato o non è presente nel record, rifiuta la richiesta
  3. In caso contrario, se il valore univoco è stato generato sul dispositivo, verifica che il valore ricevuto venga utilizzato per la prima volta (il server deve conservare un record dei valori già visualizzati per un periodo di tempo adeguato). Se il valore univoco ricevuto è già stato utilizzato, rifiuta la richiesta.

Combina entrambe le protezioni contro la manomissione e gli attacchi di riproduzione (consigliato)

È possibile utilizzare il campo nonce per proteggersi contemporaneamente da manomissioni e attacchi di replay. A questo scopo, genera il valore univoco come descritto sopra e includilo nella richiesta. Poi calcola l'hash della richiesta, assicurandoti di includere il valore univoco nell'hash. Un'implementazione che combina entrambi gli approcci è la seguente:

Quando richiedi un esito relativo all'integrità:

  1. L'utente avvia l'azione di alto valore.
  2. Ottieni un valore univoco per questa azione come descritto nella sezione Includi valori univoci per proteggere dagli attacchi di replay.
  3. Prepara un messaggio che vuoi proteggere. Includi il valore univoco del passaggio 2 nel messaggio.
  4. La tua app calcola un digest del messaggio che vuole proteggere, come descritto nella sezione Includi un hash della richiesta per proteggerti da manomissioni. Poiché il messaggio contiene il valore univoco, quest'ultimo fa parte dell'hash.
  5. Utilizza setNonce() per impostare il campo nonce sul digest calcolato nel passaggio precedente.

Quando ricevi un esito relativo all'integrità:

  1. Ottieni il valore univoco dalla richiesta
  2. Decodifica e verifica il token di integrità e ottieni il digest dal campo nonce.
  3. Come descritto nella sezione Includi un hash della richiesta per proteggerti dalle manomissioni, ricalcola il digest lato server e verifica che corrisponda al digest ottenuto dal token di integrità.
  4. Come descritto nella sezione Includi valori unici per proteggerti dagli attacchi di replay, controlla la validità del valore unico.

Il seguente diagramma di sequenza illustra questi passaggi con un nonce lato server:

Figura 2. Diagramma di sequenza che mostra come proteggersi sia dalla manomissione sia dagli attacchi di replay.

Richiedere un esito relativo all'integrità

Dopo aver generato un nonce, puoi richiedere un esito di integrità a Google Play. Per farlo, segui questi passaggi:

  1. Crea un IntegrityManager, come mostrato negli esempi seguenti.
  2. Crea un IntegrityTokenRequest fornendo nonce tramite il metodo setNonce() nel builder associato. Le app distribuite esclusivamente al di fuori di Google Play e gli SDK devono specificare anche il numero di progetto Google Cloud tramite il metodo setCloudProjectNumber(). Le app su Google Play sono collegate a un progetto Cloud in Play Console e non è necessario impostare il numero di progetto Cloud nella richiesta.

  3. Utilizza il gestore per chiamare requestIntegrityToken(), fornendo IntegrityTokenRequest.

Kotlin

// Receive the nonce from the secure server.
val nonce: String = ...

// Create an instance of a manager.
val integrityManager =
    IntegrityManagerFactory.create(applicationContext)

// Request the integrity token by providing a nonce.
val integrityTokenResponse: Task<IntegrityTokenResponse> =
    integrityManager.requestIntegrityToken(
        IntegrityTokenRequest.builder()
             .setNonce(nonce)
             .build())

Java

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

// Receive the nonce from the secure server.
String nonce = ...

// Create an instance of a manager.
IntegrityManager integrityManager =
    IntegrityManagerFactory.create(getApplicationContext());

// Request the integrity token by providing a nonce.
Task<IntegrityTokenResponse> integrityTokenResponse =
    integrityManager
        .requestIntegrityToken(
            IntegrityTokenRequest.builder().setNonce(nonce).build());

Unity

IEnumerator RequestIntegrityTokenCoroutine() {
    // Receive the nonce from the secure server.
    var nonce = ...

    // Create an instance of a manager.
    var integrityManager = new IntegrityManager();

    // Request the integrity token by providing a nonce.
    var tokenRequest = new IntegrityTokenRequest(nonce);
    var requestIntegrityTokenOperation =
        integrityManager.RequestIntegrityToken(tokenRequest);

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

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

    // Get the response.
    var tokenResponse = requestIntegrityTokenOperation.GetResult();
}

Unreal Engine

// .h
void MyClass::OnRequestIntegrityTokenCompleted(
  EIntegrityErrorCode ErrorCode,
  UIntegrityTokenResponse* Response)
{
  // Check the resulting error code.
  if (ErrorCode == EIntegrityErrorCode::Integrity_NO_ERROR)
  {
    // Get the token.
    FString Token = Response->Token;
  }
}

// .cpp
void MyClass::RequestIntegrityToken()
{
  // Receive the nonce from the secure server.
  FString Nonce = ...

  // Create the Integrity Token Request.
  FIntegrityTokenRequest Request = { Nonce };

  // Create a delegate to bind the callback function.
  FIntegrityOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestIntegrityTokenCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestIntegrityTokenCompleted);

  // Initiate the integrity token request, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UIntegrityManager>()
    ->RequestIntegrityToken(Request, Delegate);
}

Nativo

/// Create an IntegrityTokenRequest opaque object.
const char* nonce = RequestNonceFromServer();
IntegrityTokenRequest* request;
IntegrityTokenRequest_create(&request);
IntegrityTokenRequest_setNonce(request, nonce);

/// Prepare an IntegrityTokenResponse opaque type pointer and call
/// IntegerityManager_requestIntegrityToken().
IntegrityTokenResponse* response;
IntegrityErrorCode error_code =
        IntegrityManager_requestIntegrityToken(request, &response);

/// ...
/// Proceed to polling iff error_code == INTEGRITY_NO_ERROR
if (error_code != INTEGRITY_NO_ERROR)
{
    /// Remember to call the *_destroy() functions.
    return;
}
/// ...
/// Use polling to wait for the async operation to complete.
/// Note, the polling shouldn't block the thread where the IntegrityManager
/// is running.

IntegrityResponseStatus response_status;

/// Check for error codes.
IntegrityErrorCode error_code =
        IntegrityTokenResponse_getStatus(response, &response_status);
if (error_code == INTEGRITY_NO_ERROR
    && response_status == INTEGRITY_RESPONSE_COMPLETED)
{
    const char* integrity_token = IntegrityTokenResponse_getToken(response);
    SendTokenToServer(integrity_token);
}
/// ...
/// Remember to free up resources.
IntegrityTokenRequest_destroy(request);
IntegrityTokenResponse_destroy(response);
IntegrityManager_destroy();

Decriptare e verificare l'esito relativo all'integrità

Quando richiedi un esito relativo all'integrità, l'API Play Integrity fornisce un token di risposta firmato. Il nonce che includi nella richiesta diventa parte del token di risposta.

Formato del token

Il token è un JSON Web Token (JWT) nidificato, che è una JSON Web Encryption (JWE) di una JSON Web Signature (JWS). I componenti JWE e JWS sono rappresentati utilizzando la serializzazione compatta.

Gli algoritmi di crittografia / firma sono ben supportati in varie implementazioni JWT:

  • JWE utilizza A256KW per alg e A256GCM per enc

  • JWS utilizza ES256.

Decrittografare e verificare sui server di Google (opzione consigliata)

L'API Play Integrity ti consente di decriptare e verificare l'esito relativo all'integrità sui server di Google, il che migliora la sicurezza della tua app. Per farlo, segui questi passaggi:

  1. Crea un service account nel progetto Google Cloud collegato alla tua app.

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

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

  3. Leggi la risposta JSON.

Decriptare e verificare localmente

Se scegli di gestire e scaricare le chiavi di crittografia delle risposte, puoi decrittografare e verificare il token restituito all'interno del tuo ambiente server sicuro. Puoi ottenere il token restituito utilizzando il metodo IntegrityTokenResponse#token().

L'esempio seguente mostra come decodificare la chiave AES e la chiave EC pubblica codificata in DER per la verifica della firma da Play Console alle chiavi specifiche della lingua (il linguaggio di programmazione Java, nel nostro caso) nel backend dell'app. Tieni presente che le chiavi sono codificate in base64 utilizzando i flag predefiniti.

Kotlin

// base64OfEncodedDecryptionKey is provided through Play Console.
var decryptionKeyBytes: ByteArray =
    Base64.decode(base64OfEncodedDecryptionKey, Base64.DEFAULT)

// Deserialized encryption (symmetric) key.
var decryptionKey: SecretKey = SecretKeySpec(
    decryptionKeyBytes,
    /* offset= */ 0,
    AES_KEY_SIZE_BYTES,
    AES_KEY_TYPE
)

// base64OfEncodedVerificationKey is provided through Play Console.
var encodedVerificationKey: ByteArray =
    Base64.decode(base64OfEncodedVerificationKey, Base64.DEFAULT)

// Deserialized verification (public) key.
var verificationKey: PublicKey = KeyFactory.getInstance(EC_KEY_TYPE)
    .generatePublic(X509EncodedKeySpec(encodedVerificationKey))

Java

// base64OfEncodedDecryptionKey is provided through Play Console.
byte[] decryptionKeyBytes =
    Base64.decode(base64OfEncodedDecryptionKey, Base64.DEFAULT);

// Deserialized encryption (symmetric) key.
SecretKey decryptionKey =
    new SecretKeySpec(
        decryptionKeyBytes,
        /* offset= */ 0,
        AES_KEY_SIZE_BYTES,
        AES_KEY_TYPE);

// base64OfEncodedVerificationKey is provided through Play Console.
byte[] encodedVerificationKey =
    Base64.decode(base64OfEncodedVerificationKey, Base64.DEFAULT);
// Deserialized verification (public) key.
PublicKey verificationKey =
    KeyFactory.getInstance(EC_KEY_TYPE)
        .generatePublic(new X509EncodedKeySpec(encodedVerificationKey));

Successivamente, utilizza queste chiavi per decriptare prima il token di integrità (parte JWE) e poi verificare ed estrarre la parte JWS nidificata.

Kotlin

val jwe: JsonWebEncryption =
    JsonWebStructure.fromCompactSerialization(integrityToken) as JsonWebEncryption
jwe.setKey(decryptionKey)

// This also decrypts the JWE token.
val compactJws: String = jwe.getPayload()

val jws: JsonWebSignature =
    JsonWebStructure.fromCompactSerialization(compactJws) as JsonWebSignature
jws.setKey(verificationKey)

// This also verifies the signature.
val payload: String = jws.getPayload()

Java

JsonWebEncryption jwe =
    (JsonWebEncryption)JsonWebStructure
        .fromCompactSerialization(integrityToken);
jwe.setKey(decryptionKey);

// This also decrypts the JWE token.
String compactJws = jwe.getPayload();

JsonWebSignature jws =
    (JsonWebSignature) JsonWebStructure.fromCompactSerialization(compactJws);
jws.setKey(verificationKey);

// This also verifies the signature.
String payload = jws.getPayload();

Il payload risultante è un token di testo normale che contiene verifiche dell'integrità.

Risolvere i problemi relativi al verdetto con un prompt di Google Play (facoltativo)

Dopo aver ricevuto un esito di integrità, il server può determinare come procedere. Se il verdetto indica che c'è un problema, ad esempio l'app non è concessa in licenza, è stata manomessa o il dispositivo è compromesso, puoi dare agli utenti la possibilità di risolvere il problema autonomamente.

L'API Play Integrity offre un'opzione per mostrare una finestra di dialogo di Google Play che chiede all'utente di intervenire, ad esempio per scaricare la versione ufficiale della tua app da Google Play.

Per scoprire come attivare queste finestre di dialogo dalla tua app in base alla risposta del server, consulta Finestre di dialogo di correzione.

Indietro
Effettua una richiesta standard
Avanti
Informazioni sugli esiti relativi all'integrità