ממשק API לעדכון גלישה בטוחה (v4)

סקירה כללית

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

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

עדכון מסד הנתונים המקומי

כדי להישאר מעודכנים, לקוחות נדרשים לעדכן מדי פעם את רשימות הגלישה הבטוחה במסד הנתונים המקומי שלהם. כדי לחסוך ברוחב פס, לקוחות מורידים את הקידומות הגיבוב של כתובות URL במקום כתובות URL גולמיות. לדוגמה, אם "www.badurl.com/ " נמצא ברשימה של גלישה בטוחה, הלקוחות מורידים את לפני הגיבוב לפי אלגוריתם SHA256 של כתובת ה-URL הזו במקום כתובת ה-URL עצמה. ברוב המקרים, הקידומות של הגיבוב באורך 4 בייטים, כלומר העלות הממוצעת של רוחב הפס להורדת רשומה אחת ברשימה היא 4 בייטים לפני דחיסה.

כדי לעדכן את הרשימות של הגלישה הבטוחה במסד הנתונים המקומי, שולחים בקשת HTTP POST לשיטה threatListUpdates.fetch:

• הבקשה POST ב-HTTP כוללת את שמות הרשימות שרוצים לעדכן, יחד עם אילוצים שונים של לקוחות כדי להתחשב במגבלות הזיכרון וברוחב הפס.
• התגובה POST של HTTP מחזירה עדכון מלא או עדכון חלקי. התגובה עשוי גם להחזיר משך המתנה מינימלי.

דוגמה: threatListUpdates.fetch

בקשת HTTP POST

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

כותרת הבקשה

כותרת הבקשה כוללת את כתובת ה-URL של הבקשה ואת סוג התוכן. חשוב לזכור להחליף את הערך API_KEY בכתובת ה-URL במפתח ה-API שלכם.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

גוף הבקשה

גוף הבקשה כולל את פרטי הלקוח (מזהה וגרסה) ואת פרטי העדכון ( שם הרשימה, מצב הרשימה ומגבלות הלקוח). פרטים נוספים זמינים במאמר גוף הבקשה של threatListUpdates.fetch ואת ההסברים שמופיעים אחרי דוגמת הקוד.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

נתוני הלקוח

השדות clientID ו-clientVersion צריכים לזהות באופן ייחודי הטמעת לקוח, ולא למשתמש יחיד. (מידע על הלקוח משמש ביומן בצד השרת. אפשר לבחור כל שם למזהה הלקוח, אבל מומלץ לבחור שם שמייצג את הזהות האמיתית של הלקוח, כמו שם החברה, שמוצג כמילה אחת, באיות קטן בלבד.)

רשימות הגלישה הבטוחה

השדות threatType, platformType ו-threatEntryType משולבות כדי לזהות (שם) את רשימות הגלישה הבטוחה. בדוגמה, זוהי רשימה אחת: תוכנות זדוניות/Windows/כתובת URL. לפני שליחת הבקשה, חשוב לוודא ששילובי הסוגים שציינתם תקינים (ראו רשימות של גלישה בטוחה).

מצב הלקוח

השדה state מכיל את מצב הלקוח הנוכחי ברשימת הגלישה הבטוחה. (מצבי הלקוח מוחזרים בשדה newClientState של תגובת threatListUpdates.fetch.) לצורך העדכונים הראשוניים, צריך להשאיר את השדה state ריק.

מגבלות גודל

השדה maxUpdateEntries מציין את המספר הכולל של עדכונים שהלקוח יכול לנהל (ב לדוגמה, 2048). השדה maxDatabaseEntries מציין את המספר הכולל של הרשומות שמערכת מסד הנתונים המקומי יכולה לנהל (בדוגמה, 4096). לקוחות צריכים להגדיר אילוצים על הגודל כדי להגן על מגבלות הזיכרון ועל רוחב הפס, וכדי למנוע את הגדלת הרשימה. לקבלת מידע נוסף, (מידע נוסף זמין במאמר בנושא מגבלות עדכון).

דחיסת נתונים נתמכת

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

תגובת HTTP POST

בדוגמה הזו, התשובה מחזירה עדכון חלקי לרשימת הגלישה הבטוחה באמצעות סוג הדחיסה המבוקש.

כותרת תגובה

כותרת התגובה כוללת את קוד הסטטוס של ה-HTTP ואת סוג התוכן. לקוחות שמקבלים קוד סטטוס שאינו HTTP/200 חייבים לעבור למצב השהיה לפני ניסיון חוזר (backoff) (מידע נוסף זמין בקטע תדירות הבקשות).

HTTP/1.1 200 OK
Content-Type: application/json

גוף התשובה

גוף התגובה כולל את פרטי העדכון (שם הרשימה, סוג התגובה, הוספות והסרות שצריך להחיל על מסד הנתונים המקומי, מצב הלקוח החדש ותוצאת סיכום הביקורת). בדוגמה, התגובה כוללת גם את משך ההמתנה המינימלי. למידע נוסף, ראו body של התגובה של threatListUpdates.fetch וההסברים שמופיעים אחרי דוגמת הקוד.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

עדכונים של מסדי נתונים

בשדה responseType יציין עדכון חלקי או מלא. בדוגמה הזו מוחזר עדכון חלקי, כך שהתגובה כוללת גם הוספות וגם הסרות. יכולות להיות כמה קבוצות של הוספות, אבל רק קבוצה אחת של הסרות (ראו עדכוני מסדי נתונים).

מצב לקוח חדש

השדה newClientState מכיל את מצב הלקוח החדש של רשימת Safe Browsing שעודכנה. הלקוחות חייבים לשמור את מצב הלקוח החדש לבקשות עדכון עתידיות (השדה state בשדה בקשת threatListUpdates.fetch או את השדה clientStates בקשה fullHashes.find).

בדיקת סיכום

סיכום הביקורות מאפשר ללקוחות לוודא שמסד הנתונים המקומי לא פגום. אם סיכום הביקורת (checksum) אינו תואם, הלקוח חייב לנקות את מסד הנתונים ולהנפיק מחדש עדכון עם שדה ריק שדה state. עם זאת, לקוחות במצב כזה עדיין צריכים לפעול בהתאם למרווחי הזמן לעדכונים (ראו תדירות הבקשות).

משכי המתנה מינימליים

השדה minimumWaitDuration מציין שהלקוח צריך להמתין 593.44 שניות (9.89 דקות) לפני שליחה של בקשת עדכון נוספת. הערה: ייתכן שלא תכלול תקופת המתנה תגובה (מידע נוסף זמין בקטע תדירות הבקשות).

כתובות ה-URL בבדיקה

כדי לבדוק אם כתובת URL נמצאת ברשימת הגלישה הבטוחה, הלקוח צריך קודם לחשב את הגיבוב ואת הקידומת של הגיבוב של כתובת ה-URL (ראו כתובות URL וגיבוב). הלקוח/ה ואז שולח שאילתה למסד הנתונים המקומי כדי לקבוע אם יש התאמה. אם תחילית הגיבוב היא לא קיימת במסד הנתונים המקומי, כתובת ה-URL נחשבת בטוחה (לא בדף 'בטוח' עיון ברשימות).

אם קידומת הגיבוב קיימת במסד הנתונים המקומי (התנגשות בקידומת הגיבוב), הלקוח צריך לשלוח את קידומת הגיבוב לשרתים של הגלישה הבטוחה לצורך אימות. השרתים יחזירו את כל גיבובי SHA 256 באורך מלא שמכילים את קידומת הגיבוב שצוינה. אם אחד מהגיבובים האלה באורך מלא תואם לגיבוב באורך מלא של כתובת ה-URL הרלוונטית, כתובת ה-URL נחשבת לא בטוחה. אם אף אחד מהגיבובים באורך המלא לא תואם לגיבוב באורך מלא של כתובת ה-URL המדוברת, כתובת ה-URL הזו נחשבת בטוחה.

בשום שלב לא לומדת Google על כתובות ה-URL שאתם בודקים. Google לומדת את הגיבוב תחיליות של כתובות URL, אבל הן לא מספקות הרבה מידע על כתובות ה-URL בפועל.

כדי לבדוק אם כתובת URL מופיעה ברשימה של הגלישה הבטוחה, צריך לשלוח בקשת HTTP POST אל fullHashes.find method:

• בקשת ה-HTTP POST יכולה לכלול עד 500 רשומות איומים.
• בקשת ה-HTTP POST כוללת את הקידומות גיבוב (hash) של כתובות ה-URL שצריך לבדוק. הלקוחות הם מומלץ לקבץ מספר רשומות של איומים בבקשה אחת כדי לצמצם את השימוש ברוחב הפס.
• תגובת HTTP POST מחזירה את הגיבובים התואמים באורך המלא יחד עם הערך החיובי ו- משך זמן של מטמון שלילי. ייתכן שהתשובה תחזיר גם את משך ההמתנה המינימלי.

דוגמה: fullHashes.find

בקשת HTTP POST

בדוגמה הבאה, נשלחים השמות של שתי הרשימות של הגלישה הבטוחה ושלוש תחיליות גיבוב (hash) לצורך השוואה ואימות.

כותרת הבקשה

כותרת הבקשה כוללת את כתובת ה-URL של הבקשה ואת סוג התוכן. חשוב לזכור להחליף את הערך API_KEY במפתח ה-API בכתובת ה-URL.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

גוף הבקשה

גוף הבקשה כולל את פרטי הלקוח (מזהה וגרסה), את מצבי הלקוח ואת פרטי האיום (שמות הרשימות ותחיליות הגיבוב). בבקשות JSON, קידומות הגיבוב חייבות להישלח בקידוד base64. פרטים נוספים זמינים במאמר גוף הבקשה fullHashes.find ואת ההסברים שמופיעים אחרי דוגמת הקוד.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

פרטי הלקוח

השדות clientID ו-clientVersion צריכים לזהות באופן ייחודי הטמעת לקוח, ולא למשתמש יחיד. (פרטי הלקוח משמשים ברישום ביומן בצד השרת. אפשר לבחור שם כלשהו למזהה הלקוח, אבל מומלץ לבחור שם שמייצג את הזהות האמיתית של הלקוח, כמו שם החברה, שמוצג כמילה אחת, באיות קטן בלבד.)

כל מצבי הלקוח

השדה clientStates מכיל את מצבי הלקוח של כל הרשימות של הגלישה הבטוחה ב- במסד הנתונים המקומי של הלקוח. (מצבי הלקוח מוחזרים בשדה newClientState של תגובת threatListUpdates.fetch.)

רשימות הגלישה הבטוחה

הערכים threatTypes, platformTypes, threatEntryTypes משתלבים ביחד כדי לזהות (שם) את קובץ ה-Safe עיון ברשימות. בדוגמה הזו, מזוהות שתי רשימות: MALWARE/WINDOWS/URL ו-SOCIAL_ENGINEERING/WINDOWS/URL. לפני שליחת בקשה, חשוב לוודא שסוגי הסוגים משתלבים שצוינו חוקיים (ראו רשימות גלישה בטוחה).

תחיליות גיבוב (hash) של איומים

המערך threatEntries מכיל את הקידומות של הגיבוב של כתובות ה-URL שרוצים לבדוק. השדה hash חייב להכיל את הקידומת המדויקת של גיבוב (hash) שמופיעה במסד הנתונים המקומי. לדוגמה, אם הקידומת של הגיבוב המקומי באורך 4 בייטים, הרשומה של האיום צריכה להיות באורך 4 בייטים. אם הקידומת של הגיבוב המקומי אורכה ל-7 בייטים, ולכן רשומת האיום צריכה להיות באורך 7 בייטים.

בדוגמה, הבקשה כוללת שלוש קידומות של גיבוב (hash). תתבצע השוואה בין כל שלוש הקידומות בכל אחת מהרשימות של הגלישה הבטוחה כדי לקבוע אם יש גיבוב (hash) תואם באורך מלא.

הערה: תמיד צריך להשתמש בשדה hash ב-Update API ובשיטה fullHashes.find, לעולם לא בשדה URL (ראו ThreatEntry).

תגובת HTTP POST

בדוגמה הבאה, התשובה מחזירה את הנתונים התואמים, שמסודרים לפי רשימת הגלישה הבטוחה, את המטמון ואת משכי הזמן של ההמתנה.

כותרת תשובה

כותרת התגובה כוללת את קוד הסטטוס HTTP ואת סוג התוכן. לקוחות שמקבלים קוד סטטוס שאינו HTTP/200 חייבים לחזור אחורה (ראו תדירות בקשות).

HTTP/1.1 200 OK
Content-Type: application/json

גוף התשובה

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

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

התאמות

האובייקט Matches מחזיר גיבוב תואם באורך מלא בשביל שתי קידומות גיבוב. כתובות ה-URL שתואמים לגיבובים האלה נחשבים כלא בטוחים. לא נמצאה התאמה לתחילית הגיבוב השלישית, כך ששום דבר לא מוחזר, כתובת ה-URL שתואמת לקידומת הגיבוב הזו נחשבת בטוחה.

שימו לב שהדוגמה הזו תואמת גיבוב אחד באורך מלא לקידומת גיבוב אחת; אבל יכולים להיות מספר גיבובים מלאים שממופים לאותה תחילית גיבוב.

מטא-נתונים

השדה threatEntryMetadata הוא אופציונלי ומספק מידע נוסף על האיום בהתאמה. נכון לעכשיו, המטא-נתונים זמינים ברשימה של הגלישה הבטוחה של תוכנות זדוניות/חלונות/כתובות URL (ראו מטא-נתונים).

משך הזמן של המטמון

השדות cacheDuration ו-negativeCacheDuration מצביעים על משך הזמן שבו ה-hash צריך להיחשב לא בטוח או בטוח (ראו אחסון במטמון).

משכי המתנה מינימליים

השדה minimumWaitDuration מציין שהלקוח צריך להמתין 300 שניות (5 דקות) לפני שליחה של בקשת גיבובים מלאה נוספת. לתשומת ליבכם, תקופת ההמתנה עשויה להיכלל בתגובה או לא (ראו תדירות הבקשות).