From 843f022c473ffbcec7e0f91e81aa1fd7719203ff Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Tue, 12 Apr 2016 11:35:23 -0700 Subject: [PATCH] cherry-pick from mnc-mr-docs: docs: SafeBrowsing API b/27438791 Change-Id: I14a34bbec51dc33dd4d730d59268690c9bee3992 Original-Change-Id: I00f4a374353dfb62cee44713ac5faadc0a9268d5 --- docs/html/training/_book.yaml | 5 + docs/html/training/safebrowsing/index.jd | 315 +++++++++++++++++++++++ 2 files changed, 320 insertions(+) create mode 100644 docs/html/training/safebrowsing/index.jd diff --git a/docs/html/training/_book.yaml b/docs/html/training/_book.yaml index 0523ec9e12b08..891574fbc6cad 100644 --- a/docs/html/training/_book.yaml +++ b/docs/html/training/_book.yaml @@ -1384,6 +1384,11 @@ toc: path_attributes: - name: description value: How to use the SafetyNet service to analyze a device where your app is running and get information about its compatibility with your app. + - title: Checking URLs with the Safe Browsing API + path: /training/safebrowsing/index.html + path_attributes: + - name: description + value: How to use the SafetyNet service to determine if a URL is designated as a known threat. - title: Verifying Hardware-backed Key Pairs with Key Attestation path: /training/articles/security-key-attestation.html path_attributes: diff --git a/docs/html/training/safebrowsing/index.jd b/docs/html/training/safebrowsing/index.jd new file mode 100644 index 0000000000000..c6c72bfd1460a --- /dev/null +++ b/docs/html/training/safebrowsing/index.jd @@ -0,0 +1,315 @@ +page.title=Checking URLs with the Safe Browsing API + +@jd:body + + +
+ +
+ +

+ SafetyNet provides services for determining whether a URL has been marked as + a known threat by Google. +

+ +

+ The service provides an API your app can use to determine whether a + particular URL has been classified by Google as a known threat. Internally, + SafetyNet implements a client for the Safe Browsing Network Protocol v4 + developed by Google. Both the client code and the v4 network protocol were + designed to preserve users' privacy, as well as keep battery and bandwidth + consumption to a minimum. This API allows you to take full advantage of + Google's Safe Browsing service on Android in the most resource-optimized way, + and without having to implement its network protocol. +

+ +

+ This document shows you how to use SafetyNet for checking a URL for threat + types of interest. +

+ +

+ Terms of Service +

+ +

+ By using the Safe Browsing API, you consent to be bound by the Terms of Service. + Please read and understand all applicable terms and policies before accessing + the Safe Browsing API. +

+ +

+ Requesting and Registering an Android API Key +

+ +

+ To create an API key, complete the following steps: +

+ +
    +
  1. Go to the Google Developers Console. +
    2. + +
  2. On the upper toolbar, choose Select a project > + your-project-name. +
    3. + +
  3. In the search box, enter Safe Browsing APIs; when the Safe + Browsing API name appears in the table, select it. +
    4. + +
  4. After the page redisplays, select Enable then select + Go to Credentials. +
    5. + +
  5. When the Add credentials to your project window appears, choose + your parameters then select What credentials do I need?. +
    6. + +
  6. Enter a name for your API key then select Create API + key. +
    7. + +
  7. +

    + Your new API key appears; copy and paste this key for future use. +

    + +

    + Note: Your API key allows you to perform a URL check + 10,000 times each day. The key, in this instance, should just be a + hexadecimal string, not part of a URL. +

    +
    8. + +
  8. Select Done to complete the process. +
    9. +
+ +

+ If you need more help, check out the Google Developers Console + Help Center. +

+ +

+ Adding the Android API key to your AndroidManifest.xml +

+ +

+ Once your key has been whitelisted, you need to add the key to the + AndroidManifest.xml file for your app: +

+ +
+<application>
+
+    ...
+
+   <!-- SafetyNet API metadata -->
+   <meta-data android:name="com.google.android.safetynet.API_KEY"
+   android:value="your-API-key" />
+
+    ...
+
+</application>
+
+

+ Connect to Google Play Services +

+ +

+ The SafetyNet API is part of Google Play services. To connect to the API, you + need to create an instance of the Google Play services API client. For + details about using the client in your app, see Accessing + Google APIs. Once you have established a connection to Google Play + services, you can use the Google API client classes to connect to the + SafetyNet API. +

+ +

+ To connect to the API, in your activity's onCreate() + method, create an instance of Google API Client using + GoogleApiClient.Builder. Use the builder to add the SafetyNet API, + as shown in the following code example: +

+ +
+protected synchronized void buildGoogleApiClient() {
+    mGoogleApiClient = new GoogleApiClient.Builder(this)
+            .addApi(SafetyNet.API)
+            .addConnectionCallbacks(myMainActivity.this)
+            .build();
+}
+
+

+ Note: You can only call these methods after your app has + established a connection to Google Play services by receiving the + + onConnected() callback. For details about listening for a completed + client connection, see Accessing + Google APIs. +

+ +

+ Requesting a URL Check +

+ +

+ A URL check allows your app to determine if a URL has been marked as a threat + of interest. Some threat types may not be of interest to your particular + app, and the API allows you to choose which threat types are important for + your needs. You can specify multiple threat types of interest. +

+ +

+ Specifying threat types of interest +

+ +

+ The constants in the {@code SafeBrowsingThreat} class contain the + currently-supported threat types: +

+ +
+package com.google.android.gms.safetynet;
+
+public class SafeBrowsingThreat {
+
+  /**
+   * This threat type identifies URLs of pages that are flagged as containing potentially
+   * harmful applications.
+   */
+  public static final int TYPE_POTENTIALLY_HARMFUL_APPLICATION = 4;
+
+  /**
+   * This threat type identifies URLs of pages that are flagged as containing social
+   * engineering threats.
+   */
+  public static final int TYPE_SOCIAL_ENGINEERING = 5;
+}
+
+

+ When using the API, you must use constants that are not marked as deprecated. + You add threat type constants as arguments to the API. You may add as many + threat type constants as is required for your app. +

+ +

+ Send the URL check request +

+ +

+ The API is agnostic to the scheme used, so you can pass the URL with or + without a scheme. For example, either +

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

+ or +

+ +
+String url = "www.google.com";
+
+

+ is valid. +

+ +
+SafetyNet.SafetyNetApi.lookupUri(mGoogleApiClient, url,
+       SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
+       SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING)
+               .setResultCallback(
+                       new ResultCallback<SafetyNetApi.SafeBrowsingResult>() {
+
+    @Override
+    public void onResult(SafetyNetApi.SafeBrowsingResult result) {
+        Status status = result.getStatus();
+        if ((status != null) && status.isSuccess()) {
+            // Indicates communication with the service was successful.
+            // Identify any detected threats.
+            if (result.getDetectedThreats().isEmpty()) {
+
+            }
+        } else {
+            // An error occurred. Let the user proceed without warning.
+        }
+    }
+});
+
+

+ Read the URL check response +

+ +

+ The result is provided as a list of {@code SafeBrowsingThreat} objects by + calling the {@code SafetyNetApi.SafeBrowsingResult.getDetectedThreats()} + method of the returned {@code SafetyNetApi.SafeBrowsingResult} object. If the + list is empty, no threats were detected; otherwise, calling {@code + SafeBrowsingThreat.getThreatType()} on each element in the list enumerates + the threats that were detected. +

+ +

+ Suggested Warning Language +

+ +

+ Please see the Safe Browsing API Developer's Guide for + suggested warning language. +

\ No newline at end of file