הופך לקובץ שמור

המסמך הזה רלוונטי לשיטות הבאות:

• Lookup API (גרסה 4): threatMatches.find
• Update API (v4): fullHashes.find

מידע על שמירה במטמון

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

ממשק API לחיפוש

לקוחות של Lookup API צריכים לשמור במטמון כל פריט ThreatMatch שהוחזר למשך הזמן שהוגדר בשדה cacheDuration. לאחר מכן הלקוחות צריכים לבדוק את המטמון לפני שהם מבצעים בקשת threatMatches לשרת. אם משך הזמן של המטמון עבור קובץ מוחזר קודם ThreatMatch עדיין לא פג התוקף, הלקוח צריך להניח שהפריט עדיין לא בטוח. ThreatMatch פריטים נשמרים במטמון עשוי להפחית את מספר בקשות ה-API שהלקוח שולח.

דוגמה: InvalidMatches.find

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

"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]

עדכון API

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

שמירה חיובית במטמון

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

שמירה שלילית במטמון

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

עיון במטמון

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

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

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

עדכון המטמון

יש לעדכן את מטמון הלקוח בכל פעם שמתקבלת תגובת fullHashes. מטמון חיובי יש ליצור או לעדכן רשומה עבור הגיבוב המלא לפי השדה cacheDuration. הערכים של תחילית הגיבוב צריך ליצור או לעדכן גם את משך הזמן של המטמון להחרגה לפי negativeCacheDuration של התשובה השדה הזה.

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

תרחיש לדוגמה

בדוגמה הבאה, נניח ש-h(url) היא קידומת הגיבוב של כתובת ה-URL ו-H(url) היא התחילית גיבוב (hash) באורך מלא של כתובת ה-URL. כלומר, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

עכשיו נניח שלקוח (עם מטמון ריק) מבקר בכתובת example.com/ ורואה את הכתובת h(example.com/) במסד הנתונים המקומי. הלקוח מבקש את הגיבובים באורך מלא של קידומת הגיבוב h(example.com/) ומקבל בחזרה את הגיבוב באורך מלא H(example.com/) יחד עם משך מטמון חיובי של 5 דקות ומשך מטמון שלילי של שעה.

משך הזמן של מטמון חיובי של 5 דקות מציין ללקוח כמה זמן נדרש הגיבוב באורך מלא הכתובת H(example.com/) צריכה להיחשב כלא בטוחה בלי לשלוח בקשת fullHashes נוספת. אחרי 5 דקות הלקוח חייב לשלוח בקשת fullHashes נוספת עבור אותה קידומת h(example.com/) אם הלקוח מבקר שוב בכתובת example.com/ . הלקוח צריך לאפס את משך המטמון השלילי של קידומת הגיבוב בהתאם לתשובה החדשה.

משך הזמן של מטמון שלילי של שעה אחת מציין ללקוח כמה זמן בוצעו כל שאר הגיבובים באורך מלא מלבד H(example.com/) עם אותה קידומת של h(example.com/) צריך להיחשב בטוח. עבור משך הזמן של שעה, כל כתובת URL כמו h(URL) = h(example.com/) צריכה להיחשב בטוחה, וגם ולכן לא תוביל לבקשת fullHashes (בהנחה ש-H(URL) != H(example.com/)).

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

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

דוגמה: fullHashes.find

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

"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"

"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"

"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"