מסמך זה חל על השיטות הבאות:
מידע על שמירה במטמון
כדי לצמצם את השימוש ברוחב הפס של הלקוחות וכדי להגן על Google מפני עליות חדות בתנועה, לקוחות ב-Lookup API וב-Update API נדרשים ליצור ולתחזק מטמון מקומי של נתוני איומים.
ב-Lookup API, המטמון משמש להפחתת מספר הבקשות מסוג threatMatches שלקוחות שולחים ל-Google. ב-Update API, המטמון משמש להפחתת מספר הבקשות מסוג fullHashes שהלקוחות שולחים ל-Google. בהמשך תוכלו לקרוא על פרוטוקול השמירה במטמון של כל ממשק API.
ממשק API לחיפוש
לקוחות של Google Lookup API צריכים לשמור במטמון כל פריט ThreatMatch שהוחזר למשך הזמן שהוגדר בשדהcacheDuration שלו. לאחר מכן, הלקוחות צריכים לבדוק את המטמון לפני שהם שולחים בקשה
threatMatches נוספת לשרת. אם משך הזמן של המטמון של ThreatMatch שהוחזר בעבר
עדיין לא פג, הלקוח צריך להניח שהפריט עדיין לא בטוח. שמירה של ThreatMatch פריטים במטמון
עשויה לצמצם את מספר בקשות ה-API שהלקוח שולח.
דוגמה: EveryMatches.find
כדי לראות דוגמאות מלאות, אפשר ללחוץ על הקישורים לבקשה ולתגובה בכותרת הטבלה.
| בדיקת כתובת URL בקשה של threatMatches |
כתובת ה-URL תואמת תגובה של threatMatches |
התנהגות השמירה במטמון |
|---|---|---|
"threatEntries": [
{"url": "http://www.urltocheck.org/"}
]
|
"matches": [{
"threat": {"url": "http://www.urltocheck.org/"},
"cacheDuration": "300.000s"
}]
|
התאמה. הלקוח צריך להמתין 5 דקות לפני שהוא שולח בקשת threatMatches חדשה עם כתובת ה-URL http://www.urltocheck.org/.
|
עדכון API
כדי לצמצם את המספר הכולל של בקשות fullHashes שנשלחות ל-Google באמצעות Update API, הלקוחות נדרשים לשמור מטמון מקומי. ממשק ה-API יוצר שני סוגים של שמירה במטמון: חיובי ושלילי.
שמירה במטמון
כדי למנוע מלקוחות לשאול שוב ושוב לגבי המצב של גיבוב מלא מסוים לא בטוח, כל ערך ThreatMatch שהוחזר מכיל משך זמן חיובי של מטמון (מוגדר בשדה cacheDuration), שמציין כמה זמן הגיבוב המלא נחשב לא בטוח.
שמירה שלילית במטמון
כדי למנוע מלקוחות לשאול שוב ושוב לגבי המצב של גיבוב מלא בטוח מסוים, כל תגובת fullHashes מגדירה משך מטמון שלילי לקידומת המבוקשת (מוגדר על ידי השדה negativeCacheDuration). משך הזמן הזה מציין כמה זמן כל הגיבובים המלאים עם הקידומת המבוקשת נחשבים בטוחים לרשימות המבוקשות, מלבד אלה שהוחזרו על ידי השרת כלא בטוחים. השמירה במטמון חשובה במיוחד כי היא מונעת עומס יתר של תנועת הגולשים שעלולה להיגרם כתוצאה מהתנגשות של תחילית גיבוב עם כתובת URL בטוחה שמקבלת הרבה תנועה.
עיון במטמון
כשהלקוח רוצה לבדוק את המצב של כתובת URL, קודם הוא מחשב את הגיבוב המלא שלה. אם הקידומת המלאה של ה-hash קיימת במסד הנתונים המקומי, הלקוח צריך לבדוק את המטמון לפני שליחת בקשת fullHashes לשרת.
תחילה, הלקוחות צריכים לבדוק אם התקבלה תוצאה חיובית של הקובץ השמור. אם קיימת רשומה של מטמון חיובי שלא פג תוקף עבור גיבוב (hash) המלא של תחומי העניין, היא צריכה להיחשב כלא בטוחה. אם פג תוקף הרשומה החיובית של המטמון, הלקוח צריך לשלוח בקשת fullHashes עבור הקידומת המקומית המשויכת. לפי הפרוטוקול, אם השרת מחזיר את הגיבוב המלא, הוא נחשב לא בטוח, אחרת הוא נחשב בטוח.
אם אין רשומות מטמון חיוביות עבור הגיבוב המלא, הלקוח צריך לחפש היט מטמון שלילי. אם יש רשומה של מטמון שלילי לא פג תוקף לקידומת המקומית המשויכת, הצ'אט המלא נחשב בטוח. אם פג התוקף של הרשומה של המטמון השלילית או שהיא לא קיימת, הלקוח צריך לשלוח בקשת fullHashes לקידומת המקומית המשויכת ולפרש את התגובה כרגיל.
עדכון המטמון
צריך לעדכן את המטמון של הלקוח בכל פעם שמתקבלת תגובה מסוג fullHashes. צריך ליצור או לעדכן רשומה חיובית במטמון של הגיבוב המלא לפי השדה cacheDuration. צריך גם ליצור או לעדכן את משך הזמן השלילי של קידומת הגיבוב בהתאם לשדה negativeCacheDuration של התגובה.
אם בקשת fullHashes נוספת לא מחזירה גיבוב מלא שנשמר כרגע במטמון לחיוב, הלקוח לא נדרש להסיר את הרשומה החיובית מהמטמון. בפועל, זה לא גורם לדאגה, כי משך הזמן של המטמון החיובי הוא בדרך כלל קצר (כמה דקות), כדי לאפשר תיקון מהיר של תוצאות חיוביות שגויות.
תרחיש לדוגמה
בדוגמה הבאה, נניח ש-h(url) הוא קידומת הגיבוב של כתובת ה-URL, ו-H(url) הוא הגיבוב באורך המלא של כתובת ה-URL. כלומר, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).
עכשיו, נניח שלקוח (עם מטמון ריק) מבקר ב-example.com/ ורואה ש-h(example.com/) נמצא במסד הנתונים המקומי. הלקוח מבקש את הגיבובים באורך המלא עבור קידומת הגיבוב h(example.com/) ומקבלים בחזרה את הגיבוב באורך המלא H(example.com/) יחד עם משך זמן חיובי של מטמון 5 דקות ומשך מטמון שלילי של שעה אחת.
משך הזמן של המטמון החיובי (5 דקות) מורה ללקוח למשך כמה זמן הגיבוב (hash) באורך המלא (H(example.com/) צריך להיחשב כלא בטוח בלי לשלוח בקשת fullHashes נוספת. אחרי 5 דקות, הלקוח צריך לשלוח בקשת fullHashes נוספת לקידומת הזו h(example.com/) אם הוא מבקר שוב בכתובת example.com/ . על הלקוח לאפס את משך הזמן של המטמון השלילי לקידומת ה-hash בכל תגובה חדשה.
משך הזמן של המטמון השלילי (שעה אחת) מורה ללקוח למשך כמה זמן כל גיבובים אחרים באורך מלא
מלבד H(example.com/) שחולקים את אותה תחילית של h(example.com/) חייבים להיחשב בטוחים. במשך פרק זמן של שעה, כל כתובת URL ש-h(URL) = h(example.com/) צריכה להיחשב בטוחה, ולכן
לכן לא תוביל לבקשת fullHashes (בהנחה ש-H(URL) != H(example.com/)).
אם התשובה fullHashes מכילה אפס התאמות ומוגדר משך מטמון שלילי, הלקוח לא יכול לשלוח בקשות fullHashes לאף אחת מהקידומות הנדרשות למשך הזמן הנתון של המטמון השלילי.
אם התשובה fullHashes מכילה התאמה אחת או יותר, עדיין מוגדר משך מטמון שלילי לכל התגובה. במקרה כזה, משך הזמן במטמון של גיבוב מלא יחיד מציין למשך כמה זמן הלקוח צריך להניח שגיבוב מסוים באורך מלא לא בטוח. לאחר שיחלוף משך הזמן של
המטמון של ThreatMatch, הלקוח צריך לרענן את הגיבוב באורך המלא על ידי שליחת בקשת fullHashes
לקידומת הגיבוב הזו, אם כתובת ה-URL המבוקשת תואמת לקוד הגיבוב המלא הקיים במטמון. במקרה כזה, לא רלוונטי משך הזמן של המטמון השלילי. משך הזמן של המטמון השלילי לתשובה רלוונטי רק
לגיבובים באורך מלא שלא היו קיימים בתגובה fullHashes. לגיבובים באורך מלא שלא קיימים בתגובה, הלקוח צריך להימנע משליחת בקשות fullHashes עד לסיום משך הזמן של המטמון השלילי.
דוגמה: fullHashes.find
כדי לראות דוגמאות מלאות, אפשר ללחוץ על הקישורים לבקשה ולתגובה בכותרת הטבלה.
| קידומות Hash בקשה של fullHashes |
התאמות של גיבוב באורך מלא תגובת גיבוב (fullHashes) |
התנהגות השמירה במטמון |
|---|---|---|
"threatEntries": [
{"hash": "0xaaaaaaaa"}
]
|
"matches": [], "negativeCacheDuration": "3600.000s" |
אין התאמה. אסור ללקוח לשלוח בקשות fullHashes לקידומת hash 0xaaaaaaa במשך שעה לפחות.
כל גיבוב עם התחילית 0xaaaaaaa נחשב בטוח למשך שעה. |
"threatEntries": [
{"hash": "0xbbbbbbbb"}
]
|
"matches": [
"threat": {"hash": "0xbbbbbbbb0000..."}
"cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
|
התאמות אפשריות. הלקוח צריך להתייחס לכתובת ה-URL עם הגיבוב המלא 0xbbbbbbbb0000... שלא בטוח למשך 10 דקות. הלקוח צריך להתחשב בכל כתובות ה-URL עם קידומת הגיבוב 0xbbbbbbb כבטוחות למשך 5 דקות. אחרי 5 דקות, יפוג התוקף של רשומת המטמון השלילית עם קידומות הגיבוב. מאחר שהרשומה החיובית במטמון 0xbbbbbbbb0000... עדיין לא פגה, הלקוח צריך לשלוח בקשות fullHashes לכל הגיבוב (hash) מלבד זה. |
"threatEntries": [
{"hash": "0xcccccccc"}
]
|
"matches": [
"threat": {"hash": "0xccccccccdddd..."},
"cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
|
התאמות אפשריות. אסור ללקוח לשלוח בקשת fullHashes לקידומת hash 0xcccccccc למשך שעה אחת לפחות, ולהניח
שהקידומת הזו בטוחה — אלא אם הגיבוב המלא של כתובת ה-URL תואם לקידוד ה-hash המלא
0xccccccccdddd... במקרה הזה, הלקוח צריך להחשיב את כתובת ה-URL הזו כלא בטוחה למשך 10 דקות.
אחרי 10 דקות, התוקף של הגיבוב באורך המלא פג. כל החיפושים הבאים של הגיבוב המלא אמורים להפעיל בקשת fullHashes חדשה. |