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

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

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

כדי לצמצם את השימוש ברוחב הפס של הלקוח ולהגן על 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

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

בדיקת כתובת 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). משך הזמן הזה מציין למשך כמה זמן כל הגיבובים המלאים עם ייחשבו כבטוחות עבור הרשימות המבוקשות, למעט אלה שהוחזרו על ידי השרת כ- לא בטוחות. השמירה במטמון חשובה במיוחד כי היא מונעת עומס יתר של תנועה. על ידי התנגשות עם קידומת גיבוב (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

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

קידומות גיבוב (hash)
בקשת גיבובים מלאה 		התאמות גיבוב באורך מלא
תגובת גיבובים מלאה 		התנהגות השמירה במטמון 
"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"
אין התאמה.
אסור ללקוח לשלוח בקשות fullHashes לקידומת גיבוב (hash) 0xaaaaaa במשך שעה אחת לפחות. כל גיבוב עם הקידומת 0xaaaaaa נחשב בטוח למשך שעה.		 
"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
התאמות אפשריות.
הלקוח צריך להתייחס לכתובת ה-URL עם הגיבוב המלא 0xbbbbbb0000... לא בטוחה למשך 10 דקות. הלקוח צריך להתייחס לכל שאר כתובות ה-URL עם קידומת הגיבוב 0xbbbbbbb בטוחות לשימוש למשך 5 דקות. אחרי 5 דקות, הקידומות של הגיבוב (hash) יפוגו. מאז הרשומה החיובית של המטמון עבור 0xbbbbb0000... עדיין לא פג התוקף, הלקוח צריך לשלוח בקשות fullHashes עבור כל הגיבובים מלבד זאת.		 
"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
התאמות אפשריות.
ללקוח אסור לשלוח בקשת fullHashes לקידומת גיבוב (hash) 0xcccccccc למשך שעה לפחות, בהנחה זו קידומת בטוחה — אלא אם הגיבוב המלא של כתובת ה-URL תואם לגיבוב המלא שנשמר במטמון 0xccccccdddd... במקרה כזה, הלקוח צריך להתייחס לכתובת ה-URL הזו כלא בטוחה למשך 10 דקות. אחרי 10 דקות פג התוקף של הגיבוב באורך המלא. כל החיפושים הבאים של הגיבוב המלא אמורים הפעלה של בקשת fullHashes חדשה.