ממשק API לגלישה בטוחה של SafetyNet

‫SafetyNet Safe Browsing API היא ספרייה שמבוססת על Google Play Services ומספקת שירותים לקביעה אם Google סימנה כתובת URL מסוימת כאיום מוכר.

האפליקציה יכולה להשתמש ב-API הזה כדי לבדוק אם Google סיווגה כתובת URL מסוימת כאיום מוכר. מבחינה פנימית, SafetyNet מטמיע לקוח עבור פרוטוקול רשת הגלישה הבטוחה v4 שפותח על ידי Google. גם קוד הלקוח וגם פרוטוקול הרשת v4 תוכננו כך שישמרו על פרטיות המשתמשים ויצמצמו למינימום את צריכת הסוללה ורוחב הפס. אפשר להשתמש ב-API הזה כדי לנצל את מלוא היתרונות של שירות הגלישה הבטוחה של Google ב-Android בצורה הכי יעילה מבחינת משאבים, בלי להטמיע את פרוטוקול הרשת שלו.

העדכון לגרסה 5 (v5) כולל שיפורים משמעותיים ברעננות הנתונים ובפרטיות באמצעות שימוש ב-Oblivious HTTP.

במאמר הזה מוסבר איך להשתמש ב-SafetyNet Safe Browsing Lookup API כדי לבדוק אם יש איומים מוכרים בכתובת URL.

תנאים והגבלות

השימוש ב-Safe Browsing API מהווה את הסכמתכם לתנאים ולהגבלות. לפני שמשתמשים ב-Safe Browsing API, חשוב לקרוא ולהבין את כל התנאים וההגבלות ותנאי המדיניות הרלוונטיים.

בקשה ורישום של מפתח API ל-Android

לפני שמשתמשים ב-Safe Browsing API, צריך ליצור ולרשום מפתח API ל-Android. שלבים ספציפיים מופיעים בדף איך מתחילים להשתמש בגלישה בטוחה.

בגרסה 5, צריך לספק את מפתח ה-API הזה כשיוצרים את מופע SafeBrowsingClient.

הוספת התלות ב-SafetyNet API

לפני שמשתמשים ב-Safe Browsing API, צריך להוסיף את SafetyNet API לפרויקט. אם משתמשים ב-Android Studio, מוסיפים את התלות הזו לקובץ Gradle ברמת האפליקציה. מידע נוסף זמין במאמר בנושא הגנה מפני איומי אבטחה באמצעות SafetyNet.

הפעלת ה-API

כדי להשתמש ב-Safe Browsing API, צריך לאתחל את ה-API על ידי קריאה ל-initSafeBrowsing והמתנה לסיום הפעולה. קטע הקוד הבא מספק דוגמה:

Kotlin

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

Java

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

בגרסה 5, ‏ GmsCore מציע את לקוח הגלישה הבטוחה. צריך לקבל מופע של SafeBrowsingClient. פישטנו את ממשק ה-API כדי לשפר את היעילות ולצמצם את נפח הקוד.

// 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

אפשר להשתמש בשיטה lookupUri כדי לבדוק אם URI מהווה איום. צריך לציין את הפרוטוקול הרצוי, שיכול להיות רשימת החסימה המקומית (גרסה 4) או הגנה בזמן אמת (גרסה 5) .

שליחת בקשת הבדיקה של כתובת ה-URL

ה-API לא תלוי בסכימה שבה נעשה שימוש, כך שאפשר להעביר את כתובת ה-URL עם או בלי סכימה. לדוגמה, גם

Kotlin

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

Java

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

וגם

Kotlin

var url = "www.google.com"

Java

String url = "www.google.com";

הם ערכים חוקיים.

בדוגמה הבאה אפשר לראות איך לשלוח בקשה לבדיקת כתובת 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());
               }
           }
   });

החתימה המעודכנת של lookupUri מקבלת את ה-URI, רשימה של סוגי איומים ואת הפרוטוקול.

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

קריאת התשובה של בדיקת כתובת ה-URL

באמצעות האובייקט SafetyNetApi.SafeBrowsingResponse שמוחזר, קוראים לשיטה getDetectedThreats, שמחזירה רשימה של אובייקטים SafeBrowsingThreat. אם הרשימה שמוחזרת ריקה, ה-API לא זיהה איומים מוכרים. אם הרשימה לא ריקה, צריך להפעיל את הקריאה getThreatType על כל רכיב ברשימה כדי לקבוע אילו איומים מוכרים זוהו על ידי ה-API.

כדי לראות את נוסח האזהרה המוצע, אפשר לעיין במדריך למפתחים של Safe Browsing API.

ציון סוגי האיומים שמעניינים אתכם

הקבועים במחלקה SafeBrowsingThreat מכילים את סוגי האיומים שנתמכים כרגע:

סוג האיום הגדרה
TYPE_POTENTIALLY_HARMFUL_APPLICATION סוג האיום הזה מזהה כתובות URL של דפים שמסומנים כמכילים אפליקציות שעלולות להזיק.
TYPE_SOCIAL_ENGINEERING סוג האיום הזה מזהה כתובות URL של דפים שסומנו כדפים שמכילים איומי הנדסה חברתית.

כשמשתמשים ב-API, מוסיפים קבועים של סוג האיום כארגומנטים. אפשר להוסיף כמה קבועים של סוגי איומים שנדרשים לאפליקציה, אבל אפשר להשתמש רק בקבועים שלא מסומנים כקבועים שיצאו משימוש.

סגירת הסשן של הגלישה הבטוחה

אם האפליקציה לא צריכה להשתמש ב-Safe Browsing API למשך תקופה ממושכת, צריך לבדוק את כל כתובות ה-URL הנדרשות באפליקציה ואז להפסיק את הסשן של הגלישה הבטוחה באמצעות השיטה shutdownSafeBrowsing:

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

מומלץ לקרוא ל-shutdownSafeBrowsing בשיטה onPause של הפעילות ולקרוא ל-initSafeBrowsing בשיטה onResume של הפעילות. עם זאת, חשוב לוודא שהפונקציה initSafeBrowsing סיימה את ההרצה לפני שמפעילים את הפונקציה lookupUri. כך מצמצמים את הסיכוי לשגיאות פנימיות באפליקציה.

פרטים על ההגנה בזמן אמת

בעדכון לגרסה 5 נוסף מצב הגנה בזמן אמת שפותר בעיות של נתונים לא עדכניים (שמשך הזמן שלהם יכול היה להגיע ל-20 עד 50 דקות בגרסה 4). הפרוטוקול משתנה מאישור כברירת מחדל לבדיקה כברירת מחדל, וכך משפר את ההגנה מפני איומים שמתפשטים במהירות. במצב בזמן אמת, הלקוחות מנהלים מסד נתונים מקומי ומטמון גלובלי של אתרים שכנראה לא מסוכנים כדי לספק הגנה כמעט בזמן אמת עם נתוני האיומים העדכניים ביותר.

סוגי האיומים הנתמכים

ה-API מאפשר לכם לבחור אילו סוגי איומים חשובים לצרכים שלכם. גרסה 5 של ה-API תומכת במגוון רחב יותר של סוגי איומים:

קבוע של סוג האיום תיאור
NO_THREAT No threat.
TYPE_MALWARE איומים כלליים של תוכנות זדוניות.
TYPE_UNWANTED_SOFTWARE תוכנות או אפליקציות לא רצויות.
TYPE_POTENTIALLY_HARMFUL_APPLICATION אפליקציות שעלולות להזיק למכשיר או למשתמש.
TYPE_SOCIAL_ENGINEERING פישינג ואתרים מטעים אחרים.
TYPE_TRICK_TO_BILL דפים שמטעים משתמשים לגבי פעולות חיוב.
TYPE_BETTER_ADS_VIOLATION אתרים שמפירים את ההנחיות של Better Ads Standards.
TYPE_MALWARE_OFFLINE תוכנות זדוניות במצב אופליין.
TYPE_ABUSIVE_EXPERIENCE_VIOLATION הפרות שגורמות לחוויה רעה למשתמש.
TYPE_HIGH_CONFIDENCE_ALLOW_LIST רשימת היתרים ברמת מהימנות גבוהה

נתונים שנאספים על ידי SafetyNet Safe Browsing API

‫SafetyNet Safe Browsing API אוסף את הנתונים הבאים באופן אוטומטי כשהוא מתקשר עם שירות הגלישה הבטוחה ב-Android:

נתונים תיאור
פעילות באפליקציות איסוף קידומת הגיבוב של כתובות URL אחרי התאמה מקומית של קידומת הגיבוב למטרת זיהוי כתובות URL זדוניות.

‫API הגלישה הבטוחה של SafetyNet אוסף את קידומת הגיבוב של כתובות URL כדי לזהות כתובות URL זדוניות. בגרסה 5 מיושם Oblivious HTTP כדי להגן עוד יותר על נתוני המשתמשים במהלך החיפושים האלה.

המטרה שלנו היא להתנהל בשקיפות רבה ככל האפשר. עם זאת, רק אתם אחראים להחליט איך לענות על השאלות בטופס של סעיף אבטחת הנתונים של Google Play בנוגע לאיסוף נתוני המשתמשים באפליקציה, לשיתוף שלהם ולאבטחה שלהם.