סקירה
ה-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).