Menyimpan data ke dalam cache

Dokumen ini berlaku untuk metode berikut:

• Lookup API: uris.search
• Update API: hashes.search

Tentang penyimpanan dalam cache

Untuk mengurangi penggunaan bandwidth klien dan melindungi Google dari lonjakan traffic, klien Lookup API dan Update API diwajibkan untuk membuat dan memelihara cache lokal data ancaman. Lookup API menggunakan cache untuk mengurangi jumlah permintaan uris.search yang dikirim klien ke Google. Untuk Update API, cache digunakan untuk mengurangi jumlah permintaan hashes.search yang dikirim klien ke Google. Protokol penyimpanan dalam cache untuk setiap API diuraikan di bawah.

Lookup API

Klien Lookup API harus meng-cache setiap item ThreatUrl yang ditampilkan hingga waktu yang ditentukan di kolom expireTime. Klien kemudian perlu melihat cache sebelum membuat permintaan uris.search berikutnya ke server. Jika entri cache untuk ThreatUrl yang ditampilkan sebelumnya belum habis masa berlakunya, klien harus menganggap item tersebut masih tidak aman. Menyimpan item ThreatUrl dalam cache dapat mengurangi jumlah permintaan API yang dibuat oleh klien.

Update API

Untuk mengurangi jumlah keseluruhan permintaan hashes.search yang dikirim ke Google menggunakan Update API, klien diwajibkan untuk mempertahankan cache lokal. API menetapkan dua jenis penyimpanan dalam cache, positif dan negatif.

Caching positif

Untuk mencegah klien berulang kali menanyakan status hash penuh tidak aman tertentu, setiap ThreatHash yang ditampilkan berisi waktu cache positif (ditentukan oleh kolom expireTime). Hash lengkap dapat dianggap tidak aman hingga saat ini.

Caching negatif

Untuk mencegah klien berulang kali menanyakan status hash lengkap aman tertentu, respons menentukan durasi cache negatif untuk awalan yang diminta (ditentukan oleh kolom negativeExpireTime). Semua hash lengkap dengan awalan yang diminta akan dianggap aman untuk jenis ancaman yang diminta hingga saat ini, kecuali yang ditampilkan oleh server sebagai tidak aman. Penyimpanan dalam cache ini sangat penting karena mencegah kelebihan beban traffic yang dapat disebabkan oleh tabrakan awalan hash dengan URL aman yang menerima banyak traffic.

Mengakses cache

Saat klien ingin memeriksa status URL, klien akan terlebih dahulu menghitung hash lengkap URL tersebut. Jika awalan hash lengkap ada dalam database lokal, klien harus memeriksa cache-nya sebelum membuat permintaan hashes.search ke server.

Pertama, klien harus memeriksa hit cache positif. Jika ada entri cache positif yang belum habis masa berlakunya untuk hash lengkap yang diinginkan, entri tersebut harus dianggap tidak aman. Jika masa berlaku entri cache positif berakhir, klien harus mengirim permintaan hashes.search untuk awalan lokal terkait. Sesuai dengan protokol, jika server menampilkan hash lengkap, server tersebut dianggap tidak aman; jika tidak, server tersebut dianggap aman.

Jika tidak ada entri cache positif untuk hash lengkap, klien harus memeriksa hit cache negatif. Jika ada entri cache negatif yang belum habis masa berlakunya untuk awalan lokal terkait, hash lengkap dianggap aman. Jika entri cache negatif habis masa berlakunya, atau tidak ada, klien harus mengirim permintaan hashes.search untuk awalan lokal terkait dan menafsirkan respons seperti biasa.

Memperbarui cache

Cache klien harus diperbarui setiap kali respons hashes.search diterima. Entri cache positif harus dibuat atau diperbarui untuk hash lengkap sesuai dengan kolom expireTime. Durasi cache negatif awalan hash juga harus dibuat atau diperbarui sesuai kolom negativeExpireTime respons.

Jika permintaan hashes.search berikutnya tidak menampilkan hash lengkap yang saat ini di-cache secara positif, klien tidak perlu menghapus entri cache positif. Hal ini tidak perlu dikhawatirkan dalam praktiknya, karena durasi cache positif biasanya singkat (beberapa menit) untuk memungkinkan koreksi cepat terhadap positif palsu.

Contoh skenario

Pada contoh berikut, asumsikan h(url) adalah awalan hash URL dan H(url) adalah hash panjang penuh URL. Artinya, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Asumsikan klien dengan cache kosong mengunjungi example.com/ dan melihat bahwa h(example.com/) ada dalam database lokal. Klien meminta hash panjang penuh untuk awalan hash h(example.com/) dan menerima kembali hash panjang penuh H(example.com/) beserta waktu habis masa berlaku cache positif 5 menit dari sekarang dan waktu habis masa berlaku cache negatif 1 jam dari sekarang.

Durasi cache positif 5 menit memberi tahu klien berapa lama hash panjang penuh H(example.com/) harus dianggap tidak aman tanpa mengirim permintaan hashes.search lain. Setelah 5 menit, klien harus mengeluarkan permintaan hashes.search lain untuk awalan h(example.com/) tersebut jika klien mengunjungi example.com/ lagi. Klien harus mereset waktu habis masa berlaku cache negatif awalan hash sesuai respons baru.

Durasi cache negatif 1 jam memberi tahu klien berapa lama semua hash panjang lainnya selain H(example.com/) yang memiliki awalan yang sama dengan h(example.com/) harus dianggap aman. Selama durasi 1 jam, setiap URL sehingga h(URL) = h(example.com/) harus dianggap aman, sehingga tidak menghasilkan permintaan hashes.search (dengan asumsi bahwa H(URL) != H(example.com/)).

Jika respons fullHashes berisi nol kecocokan dan waktu habis masa berlaku cache negatif ditetapkan, klien tidak boleh mengeluarkan permintaan hashes.search untuk awalan yang diminta untuk waktu cache negatif yang diberikan.

Jika respons hashes.search berisi satu atau beberapa kecocokan, waktu habis masa berlaku cache negatif masih ditetapkan untuk seluruh respons. Dalam hal ini, waktu habis masa berlaku cache dari satu hash lengkap menunjukkan berapa lama klien harus menganggap hash panjang tertentu tidak aman. Setelah durasi cache ThreatHash berlalu, klien harus memuat ulang hash panjang penuh dengan mengeluarkan permintaan hashes.search untuk awalan hash tersebut jika URL yang diminta cocok dengan hash panjang penuh yang ada di cache. Dalam hal ini, durasi cache negatif tidak berlaku. Durasi cache negatif respons hanya berlaku untuk hash berdurasi penuh yang tidak ada dalam respons hashes.search. Untuk hash berdurasi penuh yang tidak ada dalam respons, klien harus menahan diri untuk tidak mengeluarkan permintaan hashes.search apa pun hingga durasi cache negatif berlalu.