SafetyNet Safe Browsing API

Die SafetyNet Safe Browsing API ist eine Bibliothek, die auf Google Play-Dienstenbasiert. Sie bietet Dienste, mit denen ermittelt werden kann, ob eine URL von Google als bekannte Bedrohung gekennzeichnet wurde.

Mit dieser API kann Ihre App ermitteln, ob eine bestimmte URL von Google als bekannte Bedrohung eingestuft wurde. Intern implementiert SafetyNet einen Client für das Safe Browsing Network Protocol v4, das von Google entwickelt wurde. Sowohl der Clientcode als auch das Netzwerkprotokoll v4 wurden entwickelt, um die Privatsphäre der Nutzer zu schützen und den Akku- und Bandbreitenverbrauch auf ein Minimum zu beschränken. Mit dieser API können Sie den Safe Browsing-Dienst von Google auf Android optimal nutzen, ohne das Netzwerkprotokoll implementieren zu müssen.

Mit dem Update auf die neue Version 5 (v5) werden durch die Verwendung von Oblivious HTTP erhebliche Verbesserungen bei der Aktualität der Daten und dem Datenschutz eingeführt.

In diesem Dokument wird erläutert, wie Sie mit der SafetyNet Safe Browsing Lookup API eine URL auf bekannte Bedrohungen prüfen.

Nutzungsbedingungen

Durch die Verwendung der Safe Browsing API stimmen Sie den Nutzungsbedingungen zu. Lesen und verstehen Sie alle anwendbaren Bedingungen und Richtlinien, bevor Sie auf die Safe Browsing API zugreifen.

Android-API-Schlüssel anfordern und registrieren

Bevor Sie die Safe Browsing API verwenden, müssen Sie einen Android-API-Schlüssel erstellen und registrieren. Eine detaillierte Anleitung finden Sie auf der Seite Erste Schritte mit Safe Browsing.

In Version 5 geben Sie diesen API-Schlüssel beim Erstellen der SafeBrowsingClient-Instanz an.

SafetyNet API-Abhängigkeit hinzufügen

Bevor Sie die Safe Browsing API verwenden, müssen Sie die SafetyNet API Ihrem Projekt hinzufügen. Wenn Sie Android Studio verwenden, fügen Sie diese Abhängigkeit der Gradle-Datei auf App-Ebene hinzu. Weitere Informationen finden Sie unter Schutz vor Sicherheitsbedrohungen mit SafetyNet.

API initialisieren

Wenn Sie die Safe Browsing API verwenden möchten, müssen Sie sie initialisieren. Rufen Sie dazu initSafeBrowsing auf und warten Sie, bis der Vorgang abgeschlossen ist. Das folgende Code-Snippet enthält ein Beispiel:

Kotlin

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

Java

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

In Version 5 bietet GmsCore den Safe Browsing-Client. Sie müssen eine SafeBrowsingClient-Instanz abrufen. Wir haben die API-Oberfläche optimiert, um die Effizienz zu steigern und die Größe zu reduzieren.

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

URL-Prüfung anfordern

Verwenden Sie die Methode lookupUri, um zu prüfen, ob eine URI eine Bedrohung darstellt. Sie müssen das gewünschte Protokoll angeben. Das kann entweder die lokale Blocklist (Version 4) oder der Schutz in Echtzeit (Version 5) sein.

Anfrage zur URL-Prüfung senden

Die API ist unabhängig vom verwendeten Schema. Sie können die URL also mit oder ohne Schema übergeben. Beide folgenden Beispiele sind gültig:

Kotlin

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

Java

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

und

Kotlin

var url = "www.google.com"

Java

String url = "www.google.com";

sind gültig.

Der folgende Code zeigt, wie Sie eine Anfrage zur URL-Prüfung senden:

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

Die aktualisierte lookupUri-Signatur verwendet die URI, eine Liste von Bedrohungstypen und das Protokoll.

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!
        }
    }

Antwort auf die URL-Prüfung lesen

Rufen Sie mit dem zurückgegebenen SafetyNetApi.SafeBrowsingResponse Objekt die Methode getDetectedThreats auf, die eine Liste von SafeBrowsingThreat Objekten zurückgibt. Wenn die zurückgegebene Liste leer ist, hat die API keine bekannten Bedrohungen erkannt. Wenn die Liste nicht leer ist, rufen Sie getThreatType für jedes Element in der Liste auf, um zu ermitteln, welche bekannten Bedrohungen die API erkannt hat.

Vorschläge für Warnmeldungen finden Sie im Entwicklerleitfaden zur Safe Browsing API.

Bedrohungstypen angeben

Die Konstanten in der Klasse SafeBrowsingThreat enthalten die derzeit unterstützten Bedrohungstypen:

Bedrohungstyp Definition
TYPE_POTENTIALLY_HARMFUL_APPLICATION Dieser Bedrohungstyp kennzeichnet URLs von Seiten, die als potenziell schädliche Anwendungen enthalten gekennzeichnet sind.
TYPE_SOCIAL_ENGINEERING Dieser Bedrohungstyp kennzeichnet URLs von Seiten, die als Bedrohungen durch Social Engineering enthalten gekennzeichnet sind.

Wenn Sie die API verwenden, fügen Sie Konstanten für Bedrohungstypen als Argumente hinzu. Sie können so viele Konstanten für Bedrohungstypen hinzufügen, wie Ihre App benötigt. Sie können jedoch nur Konstanten verwenden, die nicht als veraltet gekennzeichnet sind.

Safe Browsing-Sitzung beenden

Wenn Ihre App die Safe Browsing API über einen längeren Zeitraum nicht verwenden muss, prüfen Sie alle erforderlichen URLs in Ihrer App und beenden Sie dann Ihre Safe Browsing-Sitzung mit der shutdownSafeBrowsing Methode:

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

Wir empfehlen, shutdownSafeBrowsing in der onPause-Methode Ihrer Aktivität und initSafeBrowsing in der onResume-Methode Ihrer Aktivität aufzurufen. Achten Sie jedoch darauf, dass die Ausführung von initSafeBrowsing abgeschlossen ist, bevor Sie lookupUri aufrufen. Wenn Sie dafür sorgen, dass Ihre Sitzung immer aktuell ist, verringern Sie die Wahrscheinlichkeit interner Fehler in Ihrer App.

Details zum Schutz in Echtzeit

Mit dem Update auf Version 5 wird ein Schutzmodus in Echtzeit eingeführt, der Probleme mit veralteten Daten umgeht (die in Version 4 20 bis 50 Minuten erreichen konnten). Es wird von einem Standardprotokoll für Zulassen zu einem Standardprotokoll für Prüfen gewechselt, wodurch der Schutz vor sich schnell verbreitenden Bedrohungen verbessert wird. Im Echtzeitmodus verwalten Clients eine lokale Datenbank und einen globalen Cache mit wahrscheinlich sicheren Websites, um Schutz in nahezu Echtzeit mit den neuesten Bedrohungsdaten zu bieten.

Unterstützte Bedrohungstypen

Mit der API können Sie auswählen, welche Bedrohungstypen für Ihre Anforderungen wichtig sind. Die Version 5 der API unterstützt eine größere Auswahl an Bedrohungstypen:

Konstante für Bedrohungstyp Beschreibung
NO_THREAT Keine Bedrohung.
TYPE_MALWARE Allgemeine Malware-Bedrohungen.
TYPE_UNWANTED_SOFTWARE Unerwünschte Software oder Anwendungen.
TYPE_POTENTIALLY_HARMFUL_APPLICATION Apps, die das Gerät oder den Nutzer schädigen können.
TYPE_SOCIAL_ENGINEERING Phishing- und andere betrügerische Websites.
TYPE_TRICK_TO_BILL Seiten, die Nutzer zu Abrechnungsaktionen verleiten.
TYPE_BETTER_ADS_VIOLATION Websites, die gegen die Better Ads Standards verstoßen.
TYPE_MALWARE_OFFLINE Offline-Malware.
TYPE_ABUSIVE_EXPERIENCE_VIOLATION Verstöße, die zu einer schlechten Nutzererfahrung führen.
TYPE_HIGH_CONFIDENCE_ALLOW_LIST Zulassungsliste mit hoher Zuverlässigkeit

Von der SafetyNet Safe Browsing API erhobene Daten

Die SafetyNet Safe Browsing API erhebt die folgenden Daten automatisch, wenn sie mit dem Safe Browsing-Dienst auf Android kommuniziert:

Daten Beschreibung
App-Aktivitäten Erhebt das Hash-Präfix von URLs nach einer lokalen Übereinstimmung des Hash-Präfix, um schädliche URLs zu erkennen.

Die SafetyNet Safe Browsing API erhebt das Hash-Präfix von URLs, um schädliche URLs zu erkennen. In Version 5 wird Oblivious HTTP implementiert, um Nutzerdaten bei diesen Suchvorgängen noch besser zu schützen.

Wir möchten so transparent wie möglich sein. Sie als App-Entwickler entscheiden jedoch selbstverantwortlich, wie Sie das Formular für den Abschnitt zur Datensicherheit in Google Play im Hinblick auf die Datenerhebung, Weitergabe und den Schutz von Nutzerdaten ausfüllen.