Önbelleğe alma

Bu doküman aşağıdaki yöntemler için geçerlidir:

• Lookup API (v4): threatMatches.find
• API'yi güncelleme (v4): fullHashes.find

Ö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.