Dokumen ini berlaku untuk metode berikut:
Tentang penyimpanan cache
Untuk mengurangi penggunaan bandwidth klien dan melindungi Google dari lonjakan traffic, klien Lookup API dan Update API harus membuat dan mempertahankan cache lokal data ancaman.
Untuk Lookup API, cache digunakan untuk mengurangi jumlah permintaan threatMatches yang dikirim klien ke Google. Untuk Update API, cache digunakan untuk mengurangi jumlah permintaan fullHashes yang dikirim klien ke Google. Protokol caching untuk setiap API diuraikan di bawah ini.
Lookup API
Klien Lookup API harus menyimpan setiap item ThreatMatch yang ditampilkan ke dalam cache selama durasi yang ditentukan
oleh kolom cacheDuration-nya. Klien kemudian perlu berkonsultasi dengan cache sebelum membuat permintaan
threatMatches berikutnya ke server. Jika durasi cache untuk ThreatMatch yang ditampilkan sebelumnya belum berakhir, klien akan menganggap bahwa item tersebut masih tidak aman. Menyimpan item ThreatMatch ke dalam cache dapat mengurangi jumlah permintaan API yang dibuat oleh klien.
Contoh: ancamanMatches.find
Klik link permintaan dan respons di header tabel untuk melihat contoh selengkapnya.
| Pemeriksaan URL Permintaan Kecocokan Ancaman |
URL cocok dengan Respons threatMatches |
Perilaku Caching |
|---|---|---|
"threatEntries": [
{"url": "http://www.urltocheck.org/"}
]
|
"matches": [{
"threat": {"url": "http://www.urltocheck.org/"},
"cacheDuration": "300.000s"
}]
|
Kecocokan. Klien harus menunggu 5 menit sebelum dapat mengirim permintaan threatMatches baru yang menyertakan
URL http://www.urltocheck.org/.
|
Update API
Untuk mengurangi jumlah keseluruhan permintaan fullHashes yang dikirim ke Google menggunakan Update API, klien
harus mengelola cache lokal. API ini menetapkan dua jenis penyimpanan dalam cache, positif dan negatif.
Cache positif
Untuk mencegah klien berulang kali menanyakan status hash penuh yang tidak aman tertentu,
setiap ThreatMatch yang ditampilkan berisi durasi cache positif (ditentukan oleh kolom cacheDuration),
yang menunjukkan berapa lama hash penuh dianggap tidak aman.
Cache negatif
Untuk mencegah klien berulang kali menanyakan status hash penuh yang aman
tertentu, setiap respons fullHashes menentukan durasi cache negatif untuk awalan yang diminta (ditentukan oleh
kolom negativeCacheDuration). Durasi ini menunjukkan berapa lama semua hash penuh dengan awalan yang diminta akan dianggap aman untuk daftar yang diminta, kecuali yang ditampilkan oleh server sebagai tidak aman. Cache ini sangat penting karena mencegah kelebihan traffic yang dapat disebabkan oleh benturan awalan hash dengan URL aman yang menerima banyak traffic.
Memeriksa cache
Saat ingin memeriksa status URL, klien akan menghitung hash lengkapnya terlebih dahulu. Jika awalan hash lengkap ada di database lokal, klien harus melihat cache-nya sebelum membuat permintaan fullHashes ke server.
Pertama, klien harus memeriksa ditemukannya cache yang positif. Jika ada entri cache positif yang belum habis masa berlakunya untuk hash lengkap minat, entri tersebut harus dianggap tidak aman. Jika entri cache positif sudah tidak berlaku, klien harus mengirim permintaan fullHashes untuk awalan lokal yang terkait. Sesuai dengan protokol, jika server menampilkan hash penuh, error akan dianggap tidak aman; jika tidak, server akan dianggap aman.
Jika tidak ada entri cache positif untuk hash penuh, klien harus memeriksa hit cache negatif. Jika ada entri cache negatif yang belum habis masa berlakunya untuk awalan lokal terkait, hash penuh dianggap aman. Jika entri cache negatif sudah tidak berlaku, atau tidak ada, klien
harus mengirim permintaan fullHashes untuk awalan lokal terkait dan menafsirkan respons seperti biasa.
Memperbarui cache
Cache klien harus diperbarui setiap kali respons fullHashes diterima. Entri cache positif harus dibuat atau diperbarui untuk hash penuh per kolom cacheDuration. Durasi cache negatif awalan hash
juga harus dibuat atau diperbarui per kolom negativeCacheDuration
respons.
Jika permintaan fullHashes berikutnya tidak menampilkan hash penuh yang saat ini
di-cache secara positif, klien tidak perlu menghapus entri cache positif. Dalam praktiknya, hal ini tidak perlu dikhawatirkan, karena durasi cache positif biasanya singkat (beberapa menit) untuk memungkinkan koreksi positif palsu dengan cepat.
Contoh skenario
Pada contoh berikut, anggap h(url) adalah awalan hash URL, dan H(url) adalah hash lengkap untuk URL. Yaitu, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).
Sekarang, anggap klien (dengan cache kosong) mengunjungi example.com/ dan melihat bahwa h(example.com/) ada di database lokal. Klien meminta hash lengkap untuk awalan hash h(example.com/) dan menerima kembali hash panjang penuh H(example.com/) bersama dengan durasi cache positif 5 menit dan durasi cache negatif 1 jam.
Durasi cache positif selama 5 menit memberi tahu klien berapa lama hash lengkap
H(example.com/) harus dianggap tidak aman tanpa mengirim permintaan fullHashes lainnya. Setelah 5 menit, klien harus mengirimkan permintaan fullHashes lagi untuk awalan tersebut h(example.com/) jika klien mengunjungi example.com/ lagi. Klien harus mereset durasi cache negatif awalan hash per respons baru.
Durasi cache negatif 1 jam memberi tahu klien berapa lama semua hash lengkap lainnya selain H(example.com/) yang memiliki awalan h(example.com/) yang sama harus dianggap aman. Selama
1 jam, setiap URL sehingga h(URL) = h(example.com/) harus dianggap aman, dan oleh karena itu tidak menghasilkan permintaan fullHashes (dengan asumsi bahwa H(URL) != H(example.com/)).
Jika respons fullHashes berisi nol kecocokan dan durasi cache negatif ditetapkan, klien tidak boleh mengeluarkan permintaan fullHashes untuk awalan yang diminta selama durasi cache negatif tertentu.
Jika respons fullHashes berisi satu atau beberapa kecocokan, durasi cache negatif masih ditetapkan untuk seluruh respons. Dalam hal ini, durasi cache dari satu hash penuh menunjukkan berapa lama
hash lengkap tertentu tersebut harus dianggap tidak aman oleh klien. Setelah durasi cache ThreatMatch
berlalu, klien harus memuat ulang hash lengkap dengan mengeluarkan permintaan fullHashes untuk
awalan hash tersebut jika URL yang diminta cocok dengan hash lengkap yang ada dalam cache. Dalam hal ini, durasi cache negatif tidak berlaku. Durasi cache negatif respons hanya berlaku untuk hash berdurasi penuh yang tidak ada dalam respons fullHashes. Untuk hash berdurasi penuh yang tidak ada dalam respons, klien harus menahan diri untuk tidak mengeluarkan permintaan fullHashes apa pun sampai durasi cache negatif berlalu.
Contoh: fullHashes.find
Klik link permintaan dan respons di header tabel untuk melihat contoh selengkapnya.
| Awalan Hash Permintaan fullHashes |
Hash Lengkap Cocok dengan Respons fullHash |
Perilaku Caching |
|---|---|---|
"threatEntries": [
{"hash": "0xaaaaaaaa"}
]
|
"matches": [], "negativeCacheDuration": "3600.000s" |
Tidak ada yang cocok. Klien tidak boleh mengirim permintaan fullHashes apa pun untuk awalan hash 0xaaaaaaaa setidaknya selama satu jam.
Setiap hash dengan awalan 0xaaaaaaaa dianggap aman selama satu jam. |
"threatEntries": [
{"hash": "0xbbbbbbbb"}
]
|
"matches": [
"threat": {"hash": "0xbbbbbbbb0000..."}
"cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
|
Kemungkinan kecocokan. Klien harus menganggap URL dengan hash penuh 0xbbbbbbbb0000... tidak aman selama 10 menit. Klien harus menganggap semua URL lain dengan awalan hash 0xbbbbbbbb aman selama 5 menit. Setelah 5 menit, masa berlaku entri cache negatif awalan hash akan berakhir. Karena entri cache positif untuk 0xbbbbbbbb0000... belum habis masa berlakunya, klien harus mengirim permintaan fullHashes untuk semua hash kecuali yang itu. |
"threatEntries": [
{"hash": "0xcccccccc"}
]
|
"matches": [
"threat": {"hash": "0xccccccccdddd..."},
"cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
|
Kemungkinan kecocokan. Klien tidak boleh mengirim permintaan fullHashes apa pun untuk awalan hash 0xcccccccc setidaknya selama 1 jam dan menganggap
awalan tersebut aman — kecuali jika hash lengkap URL cocok dengan hash lengkap yang di-cache
0xcccccccdddd.... Jika demikian, klien harus menganggap URL tersebut tidak aman selama 10 menit.
Setelah 10 menit, hash lengkap akan berakhir. Pencarian berikutnya untuk hash lengkap tersebut akan
memicu permintaan fullHashes baru. |