Bu doküman aşağıdaki yöntemler için geçerlidir:
Önbelleğe alma hakkında
İstemci bant genişliği kullanımını azaltmak ve Google'ı trafik artışlarından korumak için hem Lookup API hem de Update API istemcilerinin tehdit verilerinin yerel önbelleğini oluşturup yönetmesi gerekir.
Lookup API için önbellek, istemcilerin Google'a gönderdiği threatMatches
isteklerinin sayısını azaltmak üzere kullanılır. Update API için önbellek, istemcilerin Google'a gönderdiği fullHashes
isteklerinin sayısını azaltmak üzere kullanılır. Her API için önbelleğe alma protokolü aşağıda özetlenmiştir.
Lookup API
Lookup API'nin istemcileri, döndürülen her ThreatMatch
öğesini cacheDuration alanı tarafından tanımlanan süre boyunca önbelleğe almalıdır. Bunun ardından istemcilerin sunucuya sonraki threatMatches
isteğini göndermeden önce önbelleğe başvurmaları gerekir. Daha önce döndürülen bir ThreatMatch
için önbellek süresi henüz sona ermediyse istemci, öğenin hâlâ güvenli olmadığını varsamalıdır. ThreatMatch
öğelerinin önbelleğe alınması, istemci tarafından gönderilen API isteklerinin sayısını azaltabilir.
Örnek: ThreatMatches.find
Tüm örnekler için tablo başlığındaki istek ve yanıt bağlantılarını tıklayın.
URL Kontrolü threatMatches İsteği |
URL eşleşmesi threatMatches Yanıtı |
Önbelleğe Alma Davranışı |
---|---|---|
"threatEntries": [ {"url": "http://www.urltocheck.org/"} ] |
"matches": [{ "threat": {"url": "http://www.urltocheck.org/"}, "cacheDuration": "300.000s" }] |
Eşleşme İstemci, http://www.urltocheck.org/ URL'sini içeren yeni bir threatMatches isteği göndermeden önce 5 dakika beklemelidir.
|
Update API
Update API kullanılarak Google'a gönderilen fullHashes
isteklerinin toplam sayısını azaltmak için istemcilerin yerel önbelleği tutması gerekir. API, pozitif ve negatif olmak üzere iki tür önbelleğe alma işlemi oluşturur.
Pozitif önbelleğe alma
İstemcilerin belirli bir güvenli olmayan tam karmanın durumunu tekrar tekrar sormasını önlemek için döndürülen her ThreatMatch
, tam önbellek güvenli olmayan olarak kabul edilecek olan, cacheDuration
alanı tarafından tanımlanan pozitif bir önbellek süresi içerir.
Negatif önbelleğe alma
İstemcilerin belirli bir güvenli tam karmanın durumunu tekrar tekrar sormasını önlemek için her fullHashes
yanıtı, istenen ön ek için negatif bir önbellek süresi tanımlar (negativeCacheDuration
alanı tarafından tanımlanır). Bu süre, istenen ön eke sahip tüm karmaların, sunucu tarafından güvenli olmadığı döndürülenler haricinde, istenen listeler için ne kadar süreyle güvenli olarak kabul edileceğini gösterir. Bu önbelleğe alma, çok trafik alan bir güvenli URL ile karma ön ek çakışmasının neden olabileceği aşırı trafik yükünü önlediğinden özellikle önemlidir.
Önbelleğe alma
İstemci bir URL'nin durumunu kontrol etmek istediğinde, önce tam karmasını hesaplar. Karma oluşturma işleminin tam ön eki yerel veritabanında mevcutsa istemci, sunucuya bir fullHashes
isteğinde bulunmadan önce önbelleği incelemelidir.
Öncelikle, istemcilerin olumlu bir önbellek isabeti olup olmadığını kontrol etmesi gerekir. İlgi alanının tam karması için süresi dolmamış pozitif önbellek girişi varsa güvenli değil olarak kabul edilmelidir. Pozitif önbellek girişinin süresi dolarsa istemci, ilişkili yerel ön ek için bir fullHashes
isteği göndermelidir. Protokol uyarınca, sunucu karmanın tamamını döndürürse güvenli olmadığı kabul edilir. Aksi takdirde güvenli olarak kabul edilir.
Tam karma için pozitif önbellek girişi yoksa istemci, negatif önbellek isabeti olup olmadığını kontrol etmelidir. İlişkili yerel ön ek için süresi dolmuş bir negatif önbellek girişi varsa tam karma güvenli olarak kabul edilir. Negatif önbellek girişinin süresi dolduysa veya mevcut değilse istemci, ilişkili yerel ön ek için fullHashes
isteği gönderip yanıtı normal olarak yorumlamalıdır.
Önbelleği güncelleme
fullHashes
yanıtı alındığında istemci önbelleği güncellenmelidir. cacheDuration
alanına göre tam karma için pozitif bir önbellek girişi oluşturulmalı veya güncellenmelidir. Karma ön ekin negatif önbellek süresi de yanıtın negativeCacheDuration
alanına göre oluşturulmalı veya güncellenmelidir.
Sonraki fullHashes
isteği şu anda pozitif olarak önbelleğe alınan bir tam karma değeri döndürmezse istemcinin pozitif önbellek girişini kaldırması gerekmez. Pozitif önbellek süreleri genellikle kısa (birkaç dakika) olduğundan yanlış pozitiflerin hızlıca düzeltilmesine imkan sağladığı için bu durum uygulamada soruna neden olmaz.
Örnek senaryo
Aşağıdaki örnekte h(url) parametresinin URL'nin karma ön eki, H(url)'in ise URL'nin tam uzunluktaki karması olduğunu varsayalım. Yani h(url) = SHA256(url).substr(4), H(url) = SHA256(url).
Şimdi, bir istemcinin (boş önbellekte) example.com/ adresini ziyaret ettiğini ve h(example.com/) adresinin yerel veritabanında olduğunu gördüğünü varsayalım. İstemci karma h(example.com/) karması için tam uzunlukta karmalar ister ve 5 dakikalık pozitif önbellek ve 1 saat negatif önbellek süresiyle birlikte tam uzunlukta karma (H(example.com/) karmasını geri alır.
5 dakikalık pozitif önbellek süresi, müşteriye başka bir fullHashes
isteği göndermeden tam uzunluktaki karma değerini(example.com/) güvenli olarak kabul edilmesi gerektiğini bildirir. 5 dakika sonra istemci tekrar example.com/ adresini ziyaret ederse h(example.com/) öneki için başka bir fullHashes
isteği göndermelidir. İstemci, yeni yanıta göre karma önekinin negatif önbellek süresini sıfırlamalıdır.
1 saatlik negatif önbellek süresi, istemciye h(example.com/) ile aynı ön eki paylaşan H(example.com/) dışındaki diğer tüm tam uzunluktaki karmaların güvenli olarak kabul edilmesi gerektiğini belirtir. 1 saatlik süre için, h(URL) = h(example.com/) gibi her URL güvenli olarak değerlendirilmelidir ve bu nedenle bir fullHashes
isteğiyle sonuçlanmaz (H(URL) != H(example.com/) varsayılır.
fullHashes
yanıtı sıfır eşleşme içeriyorsa ve negatif önbellek süresi ayarlanmışsa istemci, belirtilen negatif önbellek süresi için istenen ön eklerin hiçbiri için fullHashes
isteği göndermemelidir.
fullHashes
yanıtı bir veya daha fazla eşleşme içeriyorsa yanıtın tamamı için negatif önbellek süresi yine de ayarlanır. Bu durumda, tek bir tam karmanın önbellek süresi, söz konusu tam uzunluktaki karmanın istemci tarafından güvenli olmadığı varsayılması gereken zamanı belirtir. ThreatMatch
önbellek süresi dolduktan sonra, istenen URL önbellekteki mevcut tam uzunlukta karma ile eşleşirse istemci, bu karma öneki için fullHashes
isteği göndererek tam uzunluktaki karmayı yenilemelidir. Bu durumda, negatif önbellek süresi geçerli olmaz. Yanıtın negatif önbellek süresi, yalnızca fullHashes
yanıtında bulunmayan tam uzunluktaki karmalar için geçerlidir. Yanıtta bulunmayan tam uzunluktaki karmalar için istemci, negatif önbellek süresi dolana kadar fullHashes
isteği göndermekten kaçınmalıdır.
Örnek: fullHashes.find
Tüm örnekler için tablo başlığındaki istek ve yanıt bağlantılarını tıklayın.
Karma Ön ekleri fullHashes İsteği |
Tam uzunluktaki karma eşleme fullHashes Response |
Önbelleğe Alma Davranışı |
---|---|---|
"threatEntries": [ {"hash": "0xaaaaaaaa"} ] |
"matches": [], "negativeCacheDuration": "3600.000s" |
Eşleşme yok. İstemci, en az bir saat süreyle 0xaaaaaaa karma ön eki için fullHashes isteği göndermemelidir.
0xaaaaaaa ön ekine sahip tüm karmalar bir saat boyunca güvenli olarak kabul edilir. |
"threatEntries": [ {"hash": "0xbbbbbbbb"} ] |
"matches": [ "threat": {"hash": "0xbbbbbbbb0000..."} "cacheDuration": "600.000s", ], "negativeCacheDuration": "300.000s" |
Olası eşleşmeler. İstemci, 0xbbbbbbbb0000 tam karma değerini içeren URL'yi 10 dakika boyunca güvenli olarak değerlendirmelidir. İstemci, 0xbbbbbbbb karma ön eki olan diğer tüm URL'leri 5 dakika boyunca değerlendirmelidir. 5 dakikadan sonra karma ön eklerinin süresi sona erer. 0xbbbbbbbb0000... için pozitif önbellek girişinin henüz süresi dolmadığından istemci, bunun dışındaki tüm karmalar için fullHashes isteği göndermelidir. |
"threatEntries": [ {"hash": "0xcccccccc"} ] |
"matches": [ "threat": {"hash": "0xccccccccdddd..."}, "cacheDuration": "600.000s" ], "negativeCacheDuration": "3600.000s" |
Olası eşleşmeler. İstemci, URL'nin tam karma değeri önbelleğe alınan tam karma ile eşleşmediği sürece 0xcccccccc karma karma değeri için en az 1 saat fullHashes isteği göndermemeli ve bu ön eki güvenli olduğunu varsaymamalıdır. Bu durumda, istemcinin URL'yi 10 dakika boyunca güvenli olmadığını düşünmesi gerekir.
10 dakika sonra tam uzunluktaki karmanın süresi dolar. Bu karmanın sonraki tüm aramaları yeni bir fullHashes isteğini tetiklemelidir. |