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

סקירה

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

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

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

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

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

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

דוגמה: EveryListUpdates.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 משולבים כדי לזהות (שם) את רשימות הגלישה הבטוחה. בדוגמה מזוהה רשימה אחת: MALWARE/WINDOWS/URL. לפני שליחת בקשה, חשוב לוודא ששילובי הסוגים שציינתם חוקיים (ראו רשימות גלישה בטוחה).

מצב הלקוח

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

מגבלות גודל

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

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

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

תשובת HTTP POST

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

כותרת תגובה

כותרת התגובה כוללת את קוד הסטטוס של HTTP ואת סוג התוכן. לקוחות שמקבלים קוד סטטוס שאינו HTTP/200 צריכים להיכנס למצב השהיה (back-off) (ראו Request Frequency).

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

גוף התשובה

גוף התגובה כולל את פרטי העדכון (שם הרשימה, סוג התגובה, התוספות וההסרות שיש להחיל על מסד הנתונים המקומי, מצב הלקוח החדש וסיכום ביקורת). בדוגמה, התשובה כוללת גם משך המתנה מינימלי. לפרטים נוספים, קראו את גוף התגובה 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 מכיל את מצב הלקוח החדש עבור רשימת הגלישה הבטוחה המעודכנת. הלקוחות חייבים לשמור את מצב הלקוח החדש לבקשות עדכון עתידיות (השדה state בבקשה של threatListUpdates.fetch או השדה clientStates בבקשה של fullHashes.find).

סיכומי ביקורות

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

משך המתנה מינימלי

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

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

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

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

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

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

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

דוגמה: fullHashes.find

בקשת HTTP POST

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

כותרת הבקשה

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

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

גוף הבקשה

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

{
  "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 משולבים כדי לזהות את רשימות הגלישה הבטוחה. בדוגמה, מזוהות שתי רשימות: MALWARE/WINDOWS/URL ו-SOCIAL_EngineERING/WINDOWS/URL. לפני שליחת בקשה, חשוב לוודא ששילובי הסוגים שציינתם תקפים (כדאי לעיין בקטע רשימות גלישה בטוחה).

קידומות hash של איומים

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

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

הערה: ב-Update API וב-method fullHashes.find צריך להשתמש תמיד בשדה hash, ולא בשדה URL (מידע נוסף זמין במאמר ThreatEntry).

תשובת HTTP POST

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

כותרת תגובה

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

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

התאמות

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

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

Metadata

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

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

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

משך המתנה מינימלי

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