API SafetyNet Navigazione sicura

L'API SafetyNet Navigazione sicura, una libreria basata su Google Play Services, fornisce servizi per determinare se un URL è stato contrassegnato da Google come minaccia nota.

La tua app può utilizzare questa API per determinare se un determinato URL è stato classificato da Google come minaccia nota. Internamente, SafetyNet implementa un client per il protocollo di rete Navigazione sicura v4 sviluppato da Google. Sia il codice client sia il protocollo di rete v4 sono stati progettati per preservare la privacy degli utenti e ridurre al minimo il consumo di batteria e larghezza di banda. Utilizza questa API per sfruttare al meglio il servizio Navigazione sicura di Google su Android nel modo più ottimizzato per le risorse e senza implementare il relativo protocollo di rete.

Il nuovo aggiornamento alla versione 5 (v5) introduce miglioramenti significativi nella freschezza e nella privacy dei dati grazie all'utilizzo di HTTP Oblivious.

Questo documento spiega come utilizzare l'API SafetyNet Navigazione sicura Lookup per controllare se un URL presenta minacce note.

Termini di servizio

Utilizzando l'API Navigazione sicura, accetti di essere vincolato dai Termini di servizio. Leggi e comprendi tutti i termini e le norme applicabili prima di accedere all'API Navigazione sicura.

Richiedi e registra una chiave API Android

Prima di utilizzare l'API Navigazione sicura, crea e registra una chiave API Android. Per i passaggi specifici, consulta la pagina su come iniziare a utilizzare Navigazione sicura.

Nella versione 5, fornisci questa chiave API quando crei l'istanza SafeBrowsingClient.

Aggiungi la dipendenza dell'API SafetyNet

Prima di utilizzare l'API Navigazione sicura, aggiungi l'API SafetyNet al tuo progetto. Se utilizzi Android Studio, aggiungi questa dipendenza al file Gradle a livello di app. Per ulteriori informazioni, consulta Proteggere dalle minacce alla sicurezza con SafetyNet.

Inizializza l'API

Per utilizzare l'API Navigazione sicura, devi inizializzarla chiamando initSafeBrowsing e attendendo il completamento. Il seguente snippet di codice fornisce un esempio:

Kotlin

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing)

Java

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing);

Nella versione 5, GmsCore offre il client Navigazione sicura. Devi ottenere un'istanza SafeBrowsingClient. Abbiamo semplificato la superficie dell'API per aumentare l'efficienza e ridurre il bloat.

// Draft interface for the new client
public interface SafeBrowsingClient extends HasApiKey<SafeBrowsingApiOptions> {
  Task<SafeBrowsingResponse> lookupUri(String uri, @ThreatType List<Integer> threatTypes, @Protocol int protocol);
  Task<SupportedThreatTypesResponse> getSupportedThreatTypes();
}

Richiedi un controllo dell'URL

Utilizza il metodo lookupUri per verificare se un URI rappresenta una minaccia. Devi specificare il protocollo previsto, che può essere l'elenco di blocchi locale (v4) o la protezione in tempo reale (v5) .

Invia la richiesta di controllo dell'URL

L'API è indipendente dallo schema utilizzato, quindi puoi passare l'URL con o senza uno schema. Ad esempio, entrambi

Kotlin

var url = "https://www.google.com"

Java

String url = "https://www.google.com";

e

Kotlin

var url = "www.google.com"

Java

String url = "www.google.com";

sono validi.

Il seguente codice mostra come inviare una richiesta di controllo dell'URL:

Kotlin

SafetyNet.getClient(this).lookupUri(
       url,
       SAFE_BROWSING_API_KEY,
       SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
       SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING
)
       .addOnSuccessListener(this) { sbResponse ->
           // Indicates communication with the service was successful.
           // Identify any detected threats.
           if (sbResponse.detectedThreats.isEmpty()) {
               // No threats found.
           } else {
               // Threats found!
           }
       }
       .addOnFailureListener(this) { e: Exception ->
           if (e is ApiException) {
               // An error with the Google Play services API contains some
               // additional details.
               Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")

               // Note: If the status code, s.statusCode,
               // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
               // you need to call initSafeBrowsing(). It means either you
               // haven't called initSafeBrowsing() before or that it needs
               // to be called again due to an internal error.
           } else {
               // A different, unknown type of error occurred.
               Log.d(TAG, "Error: ${e.message}")
           }
       }

Java

SafetyNet.getClient(this).lookupUri(url,
         SAFE_BROWSING_API_KEY,
         SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
         SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING)
   .addOnSuccessListener(this,
       new OnSuccessListener<SafetyNetApi.SafeBrowsingResponse>() {
           @Override
           public void onSuccess(SafetyNetApi.SafeBrowsingResponse sbResponse) {
               // Indicates communication with the service was successful.
               // Identify any detected threats.
               if (sbResponse.getDetectedThreats().isEmpty()) {
                   // No threats found.
               } else {
                   // Threats found!
               }
        }
   })
   .addOnFailureListener(this, new OnFailureListener() {
           @Override
           public void onFailure(@NonNull Exception e) {
               // An error occurred while communicating with the service.
               if (e instanceof ApiException) {
                   // An error with the Google Play services API contains some
                   // additional details.
                   ApiException apiException = (ApiException) e;
                   Log.d(TAG, "Error: " + CommonStatusCodes
                       .getStatusCodeString(apiException.getStatusCode()));

                   // Note: If the status code, apiException.getStatusCode(),
                   // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
                   // you need to call initSafeBrowsing(). It means either you
                   // haven't called initSafeBrowsing() before or that it needs
                   // to be called again due to an internal error.
               } else {
                   // A different, unknown type of error occurred.
                   Log.d(TAG, "Error: " + e.getMessage());
               }
           }
   });

La firma di lookupUri aggiornata accetta l'URI, un elenco di tipi di minacce e il protocollo.

val threatTypes = listOf(ThreatType.TYPE_SOCIAL_ENGINEERING, ThreatType.TYPE_MALWARE)
val protocol = Protocol.REAL_TIME // or Protocol.LOCAL_BLOCK_LIST

safeBrowsingClient.lookupUri(url, threatTypes, protocol)
    .addOnSuccessListener { response ->
        if (response.detectedThreats.isEmpty()) {
            // No threats found
        } else {
            // Threats detected!
        }
    }

Leggi la risposta al controllo dell'URL

Utilizzando l'oggetto SafetyNetApi.SafeBrowsingResponse restituito, chiama il metodo getDetectedThreats, che restituisce un elenco di oggetti SafeBrowsingThreat. Se l'elenco restituito è vuoto, l'API non ha rilevato minacce note. Se l'elenco non è vuoto, chiama getThreatType su ogni elemento dell'elenco per determinare quali minacce note ha rilevato l'API.

Per visualizzare il linguaggio di avviso suggerito, consulta la Guida per gli sviluppatori dell'API Navigazione sicura.

Specifica i tipi di minacce di interesse

Le costanti nella classe SafeBrowsingThreat contengono i tipi di minacce attualmente supportati:

Tipo di minaccia Definizione
TYPE_POTENTIALLY_HARMFUL_APPLICATION Questo tipo di minaccia identifica gli URL delle pagine contrassegnate come contenenti applicazioni potenzialmente dannose.
TYPE_SOCIAL_ENGINEERING Questo tipo di minaccia identifica gli URL delle pagine contrassegnate come contenenti minacce di ingegneria sociale.

Quando utilizzi l'API, aggiungi le costanti del tipo di minaccia come argomenti. Puoi aggiungere tutte le costanti del tipo di minaccia richieste dalla tua app, ma puoi utilizzare solo le costanti non contrassegnate come obsolete.

Chiudi la sessione di Navigazione sicura

Se la tua app non deve utilizzare l'API Navigazione sicura per un periodo prolungato, controlla tutti gli URL necessari all'interno dell'app e poi chiudi la sessione di Navigazione sicura utilizzando il shutdownSafeBrowsing metodo:

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

Ti consigliamo di chiamare shutdownSafeBrowsing nel metodo onPause dell'attività e di chiamare initSafeBrowsing nel metodo onResume dell'attività. Tuttavia, assicurati che l'esecuzione di initSafeBrowsing sia terminata prima di chiamare lookupUri Assicurandoti che la sessione sia sempre aggiornata, riduci la possibilità di errori interni nell'app.

Dettagli sulla protezione in tempo reale

L'aggiornamento alla versione 5 introduce una modalità di protezione in tempo reale che aggira i problemi di obsolescenza dei dati (che nella versione 4 potevano raggiungere i 20-50 minuti). Passa da un protocollo consenti per impostazione predefinita a un protocollo controlla per impostazione predefinita , migliorando la protezione dalle minacce a propagazione rapida. Nella modalità in tempo reale, i client gestiscono un database locale e una cache globale di siti probabilmente sicuri per fornire una protezione quasi in tempo reale con i dati sulle minacce più recenti.

Tipi di minacce supportati

L'API ti consente di scegliere i tipi di minacce importanti per le tue esigenze. L'API v5 supporta una gamma più ampia di tipi di minacce:

Costante del tipo di minaccia Descrizione
NO_THREAT Nessuna minaccia.
TYPE_MALWARE Minacce malware generali.
TYPE_UNWANTED_SOFTWARE Software o applicazioni indesiderati.
TYPE_POTENTIALLY_HARMFUL_APPLICATION App che potrebbero danneggiare il dispositivo o l'utente.
TYPE_SOCIAL_ENGINEERING Siti di phishing e altri siti ingannevoli.
TYPE_TRICK_TO_BILL Pagine che inducono gli utenti a eseguire azioni di fatturazione.
TYPE_BETTER_ADS_VIOLATION Siti che violano gli standard per annunci migliori.
TYPE_MALWARE_OFFLINE Malware offline.
TYPE_ABUSIVE_EXPERIENCE_VIOLATION Violazioni che comportano una brutta esperienza per l'utente.
TYPE_HIGH_CONFIDENCE_ALLOW_LIST Elenco di consenti ad alta affidabilità

Dati raccolti dall'API SafetyNet Navigazione sicura

L'API SafetyNet Safe Browsing raccoglie automaticamente i seguenti dati quando comunica con il servizio Navigazione sicura su Android:

Dati Descrizione
Attività nelle app Raccoglie il prefisso con hash degli URL dopo una corrispondenza del prefisso con hash locale per rilevare gli URL dannosi.

L'API SafetyNet Navigazione sicura raccoglie il prefisso con hash degli URL per rilevare gli URL dannosi. La versione 5 implementa HTTP Oblivious per proteggere ulteriormente i dati utente durante queste ricerche.

Sebbene cerchiamo di essere il più trasparenti possibile, sei l'unico responsabile di decidere come rispondere al modulo della sezione Sicurezza dei dati di Google Play per quanto riguarda le modalità di raccolta dei dati utente, condivisione e sicurezza della tua app.