API SafetyNet Safe Browsing

L'API SafetyNet Safe Browsing, une bibliothèque fournie par les services Google Play, propose des services permettant de déterminer si une URL a été marquée comme menace connue par Google.

Votre application peut utiliser cette API pour déterminer si une URL particulière a été classée par Google comme menace connue. En interne, SafetyNet met en œuvre un client pour la version 4 du protocole réseau de navigation sécurisée développé par Google. Le code client et la version 4 du protocole réseau ont tous deux été conçus pour préserver la confidentialité des utilisateurs et pour réduire au maximum l'utilisation de la batterie et de la bande passante. Utilisez cette API pour tirer pleinement parti du service de navigation sécurisée de Google sur Android de la manière la plus optimisée en termes de ressources, sans implémenter son protocole réseau.

Ce document explique comment utiliser l'API SafetyNet Safe Browsing Lookup pour rechercher des menaces connues dans une URL.

Conditions d'utilisation

En utilisant l'API Safe Browsing, vous acceptez de respecter les conditions d'utilisation. Veuillez lire attentivement l'ensemble des conditions d'utilisation et des règles applicables avant d'accéder à l'API Safe Browsing.

Demander et enregistrer une clé API Android

Avant d'utiliser l'API Safe Browsing, créez et enregistrez une clé API Android. Pour connaître la procédure à suivre, consultez Premiers pas avec la navigation sécurisée.

Ajouter la dépendance de l'API SafetyNet

Avant d'utiliser l'API Safe Browsing, ajoutez-la à votre projet. Si vous utilisez Android Studio, ajoutez cette dépendance à votre fichier Gradle au niveau de l'application. Pour en savoir plus, consultez Se protéger contre les menaces de sécurité avec SafetyNet.

Initialiser l'API

Pour utiliser l'API Safe Browsing, vous devez l'initialiser en appelant initSafeBrowsing() et en attendant que l'opération se termine. L'extrait de code suivant fournit un exemple :

Kotlin

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

Java

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

Remarque : Pour réduire l'impact de l'initialisation de votre application, appelez initSafeBrowsing() le plus tôt possible dans votre méthode onResume().

Demander une vérification d'URL

Votre application peut utiliser une vérification d'URL pour déterminer si une URL présente une menace connue. Certains types de menaces ne présentent pas d'intérêt pour votre application. L'API vous permet de choisir les types de menaces importants pour vos besoins. Vous pouvez spécifier plusieurs types de menaces connus.

Envoyer la requête de vérification d'URL

L'API est indépendante du schéma utilisé. Vous pouvez donc transmettre l'URL avec ou sans schéma. Par exemple,

Kotlin

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

Java

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

et

Kotlin

var url = "www.google.com"

Java

String url = "www.google.com";

sont tous deux valides.

Le code suivant montre comment envoyer une requête de vérification d'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());
               }
           }
   });

Lire la réponse de la vérification d'URL

À l'aide de l'objet SafetyNetApi.SafeBrowsingResponse renvoyé, appelez sa méthode getDetectedThreats(), qui renvoie une liste d'objets SafeBrowsingThreat. Si la liste renvoyée est vide, cela signifie que l'API n'a détecté aucune menace connue. Si la liste n'est pas vide, appelez getThreatType() sur chaque élément de la liste pour déterminer quelles menaces connues ont été détectées par l'API.

Pour afficher le langage d'avertissement suggéré, consultez le guide du développeur de l'API Safe Browsing.

Spécifier les types de menaces intéressants

Les constantes de la classe SafeBrowsingThreat contiennent les types de menaces actuellement pris en charge :

Type de menace	Définition
TYPE_POTENTIALLY_HARMFUL_APPLICATION	Ce type de menace identifie les URL des pages signalées comme contenant des applications potentiellement dangereuses.
TYPE_SOCIAL_ENGINEERING	Ce type de menace identifie les URL des pages signalées comme contenant des menaces d'ingénierie sociale.

Lorsque vous utilisez l'API, vous ajoutez des constantes de type de menace en tant qu'arguments. Vous pouvez ajouter autant de constantes de type de menace que nécessaire à votre application, mais vous ne pouvez utiliser que des constantes qui ne sont pas marquées comme obsolètes.

Fermer votre session de navigation sécurisée

Si votre application n'a pas besoin d'utiliser l'API Safe Browsing pendant une période prolongée, vérifiez toutes les URL nécessaires, puis fermez votre session de navigation sécurisée à l'aide de la méthode shutdownSafeBrowsing() :

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

Nous vous recommandons d'appeler shutdownSafeBrowsing() dans la méthode onPause() de votre activité et d'appeler initSafeBrowsing() dans la méthode onResume() de votre activité. Toutefois, assurez-vous que l'exécution de initSafeBrowsing() est terminée avant d'appeler lookupUri(). En vous assurant que votre session est toujours à jour, vous réduisez le risque d'erreurs internes dans votre application.

Données collectées par l'API SafetyNet Safe Browsing

L'API SafetyNet Safe Browsing collecte automatiquement les données suivantes lorsqu'elle communique avec le service de navigation sécurisée sur Android :

Données	Description
Activité dans l'application	Collecte le préfixe de hachage des URL après une correspondance de préfixe de hachage local afin de détecter les URL malveillantes.

Notre objectif est d'être le plus transparent possible. Toutefois, vous êtes seul responsable de vos réponses au formulaire Google Play sur la sécurité des données concernant la collecte et le partage des données utilisateur dans votre application, ainsi que vos pratiques de sécurité.